Local Development
You can create a local IOTA network to develop and test your dApps with the latest changes in the IOTA repository. You
can set it up using the iota
binary with the iota start
subcommand, which can start a local IOTA network
consisting of 4 IOTA validators with indexer and a test token faucet.
Prerequisites
You should install the IOTA CLI tool to interact with the local node.
Start a Local Network
You can start a local network by running the following command from your iota
root folder.
RUST_LOG="off,iota_node=info" cargo run --bin iota start --force-regenesis --with-faucet
The command will start a local network with a test token faucet. The RUST_LOG
=off,iota_node=info
turns off logging for all
components except iota-node. If you want to see more detailed logs, you can remove RUST_LOG
from the command.
Data on the local network does not persist when the --force-regenesis
flag is
used.
To persist data use the --config-dir
flag instead.
Customize a Local Network
You can add the following additional parameters to the start command to customize your network:
--epoch-duration-ms <EPOCH_DURATION_MS>
: Change epoch duration from the default one minute to your desired value.--with-faucet=<FAUCET_PORT>
: Change the port where the IOTA faucet starts.--fullnode-rpc-port <FULLNODE_RPC_PORT>
: Change the port where the Full-node RPC server starts.
Use iota start --help
to see these options in your console.
Interact With Your Local Node
Using cURL
You can use cURL to send JSON requests to your local node. The following example will retrieve the total transaction count from your local network:
curl --location --request POST 'http://127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
"jsonrpc": "2.0",
"id": 1,
"method": "iota_getTotalTransactionBlocks",
"params": []
}'
If successful, the response resembles the following:
{
"jsonrpc": "2.0",
"result": 168,
"id": 1
}
Using the IOTA Client CLI
Create a local env
The IOTA Client CLI is compatible with all IOTA networks. You only need to specify the RPC URL by passing
the --rpc <RPC URL>
parameter. We recommend that you also assign an alias to the network by passing
the --alias <ALIAS>
parameter so you can easily access this env in the future.
iota client new-env --alias local --rpc http://127.0.0.1:9000
Connect to the local env
After creating the env, you can use the switch
command to set it as the current active
environment:
iota client switch --env local
You can check the current active environment with the following command, which should return the environment alias you assigned:
iota client active-env
Show the current active address
The IOTA Client CLI will default to the active address if you don't specify an address. You can use the following command to show the current active address on your local network.
iota client active-address
You can also use the iota client addresses
command to see all the addresses on your local network.
Use the local faucet
Even though it's a local network, transactions still require gas. You can use
You can use the iota client faucet
command to get coins from your local faucet. Keep in mind that it may take up to
one minute
to complete your request. You can check if your coins have arrived using the iota client gas
command.
The faucet
command uses the active address and the active network environment by default. If you need to pass in a
different address or faucet server URL, check the help
menu. If you're using a different network than a local
or public one, you must pass the URL to the faucet server.
To send coins to a IOTA Wallet is connected to your local network. See Set up a local IOTA Wallet. You can use the address for the local IOTA Wallet with the faucet.
Check the gas coin objects for the active address
After you get coins from the faucet, you can use the following command to view the coin objects for the address:
iota client gas
The response resembles the following, but with different IDs:
╭────────────────────────────────────────────────────────────────────┬────────────╮
│ gasCoinId │ gasBalance │
├────────────────────────────────────────────────────────────────────┼────────── ──┤
│ 0x1d790713c1c3441a307782597c088f11230c47e609af2cec97f393123ea4de45 │ 200000000 │
│ 0x20c1d5ad2e8693953fca09fd2fec0fbc52a787e0a0f77725220d36a09a5b312d │ 200000000 │
│ [...] │ │
╰────────────────────────────────────────────────────────────────────┴────────────╯
In order to use the explorer locally users can use the deployed explorer and set another endpoint like this: https://explorer.rebased.iota.org/?network=http%3A%2F%2F127.0.0.1%3A9000 or manually provide a Custom RPC URL on the Explorer page in the top right corner.
The IOTA Explorer requires a secure HTTPS connection. If your local network doesn't support HTTPS, consider running your own instance of the Explorer.
Install IOTA Wallet Locally
Prerequisites
Install Dependencies
After you install pnpm
, you should run the following command from the root folder of IOTA to install the necessary dependencies:
pnpm install
Build
After the installation completes, run the following command to build the IOTA Wallet:
pnpm turbo build
Set Up a Local IOTA Wallet
You can use a local IOTA Wallet to test with your local network.
Configure the Wallet
Before you start the IOTA Wallet app, update its default environment to point to your local network. First,
make a copy of iota/apps/wallet/configs/environment/.env.defaults
and rename it to .env
in the same directory. In
your .env
file, edit the first line to read API_ENV=local
and then save the file.
Run the following command from the iota
root folder to start the IOTA Wallet on your local network:
pnpm wallet build
Add a Local IOTA Wallet to Chrome
After you build your local version of IOTA Wallet, you can add the extension to Chrome:
- Open a Chrome browser to
chrome://extensions
. - Click the Developer mode toggle to enable if it's not already on.
- Click the Load unpacked button and select your
apps/wallet/dist
directory in your local copy of the IOTA repository.
Consult the IOTA Wallet Readme for more information on working with a locally built wallet on Chrome is needed.
Generate example data
Use the TypeScript SDK to add example data to your network.
Before running the command, you must complete the Prerequisites for Building Apps locally
section.
Run the following command from the iota
root folder:
pnpm --filter @iota/iota-sdk test:e2e
For additional information about example data for testing, see https://github.com/iotaledger/iota/tree/develop/sdk/typescript#testing.
Troubleshooting
If you do not use Node.js 18, you might see the following message:
Retrying requesting from the faucet: Retry failed: fetch is not defined
To resolve this, switch or update to Node.js 18 and then try again.
Test with the IOTA TypeScript SDK
The published version of the IOTA TypeScript SDK might be an earlier version than the version of IOTA you installed for your local network. To make sure you're using the latest version of the SDK, use a local built version of SDK.
In your local checkout of the IOTA repository make sure you are using the same branch as the network you are developing against. Run
pnpm install && pnpm build
to compile the SDK.
To use the local built SDK in your project go to your project folder and execute
pnpm add <PATH_TO_YOUR_REPO>/sdk/typescript
and the locally compiled version of @iota/iota-sdk
package will be installed for your application.