Shell-Chain Quickstart Guide

Get a local shell-chain node running in 5 minutes.

See also: Testnet Operator Guide · JSON-RPC API Reference · Post-Quantum Cryptography Guide · Smart Contract Guide · Native Account Abstraction Guide

Prerequisites

1. Clone and build

git clone https://github.com/ShellDAO/shell-chain.git
cd shell-chain
cargo build --release

The binary is at target/release/shell-node.

For convenience, add it to your PATH:

export PATH="$PWD/target/release:$PATH"

2. Generate a key

Shell-chain uses post-quantum Dilithium3 signatures (see PQ Crypto Guide). Generate a validator keypair:

shell-node key generate --output my-key.json

You will be prompted to set an encryption password. Save it — you'll need it to start the node.

View the derived address:

shell-node key inspect my-key.json

Note the displayed address (a 0x + 64 lowercase hex string). You'll use it in the genesis file.

3. Initialize genesis

Create a genesis.json with your address as the sole validator and pre-fund it:

{
  "chain_id": 1337,
  "chain_name": "shell-local",
  "timestamp": 1700000000,
  "gas_limit": 30000000,
  "extra_data": "shell-genesis",
  "consensus": {
    "engine": "poa",
    "authorities": [
      "0x<YOUR_ADDRESS_64_HEX>"
    ],
    "block_time_secs": 2,
    "epoch_length": 0
  },
  "alloc": {
    "0x<YOUR_ADDRESS_64_HEX>": {
      "balance": "0x3635c9adc5dea00000"
    }
  },
  "boot_nodes": []
}

Replace 0x<YOUR_ADDRESS_64_HEX> with the address from Step 2. The balance 0x3635c9adc5dea00000 is 1,000 Ether in wei.

Initialize the data directory:

shell-node init --genesis genesis.json --chain-id 1337 --datadir shell-data

4. Start a single node

shell-node run \
  --datadir shell-data \
  --keystore my-key.json \
  --rpc-addr 127.0.0.1:8545 \
  --block-time 2000 \
  --chain-id 1337 \
  --db memory \
  --rpc-api eth,net,web3,shell

Enter your keystore password when prompted. You should see log output showing blocks being produced every 2 seconds.

5. Check block height

Open a new terminal and query the node:

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Expected response:

{"jsonrpc":"2.0","id":1,"result":"0x5"}

The block number should increase every 2 seconds.

6. Check your balance

Using the CLI:

shell-node account balance 0x<YOUR_ADDRESS_64_HEX> --rpc-url http://127.0.0.1:8545

Or via curl:

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x<YOUR_ADDRESS_64_HEX>","latest"],"id":1}'

Expected result: "0x3635c9adc5dea00000" (1,000 Ether).

7. Send a test transaction

Generate a second key to use as the recipient:

shell-node key generate --output recipient-key.json
shell-node key inspect recipient-key.json
# Note the recipient address

Send 1 Ether (1000000000000000000 wei) from your funded account:

shell-node tx send \
  --to 0x<RECIPIENT_ADDRESS_64_HEX> \
  --value 1000000000000000000 \
  --keystore my-key.json \
  --rpc-url http://127.0.0.1:8545

Enter your keystore password when prompted. The command outputs the transaction hash.

Verify the recipient received the funds:

shell-node account balance 0x<RECIPIENT_ADDRESS_64_HEX> --rpc-url http://127.0.0.1:8545

8. Explore the API

Query node information:

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getNodeInfo","params":[],"id":1}' | python3 -m json.tool

List validators:

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"shell_getValidators","params":[],"id":1}'

Check client version:

curl -s http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}'

Public Testnet

Coming Soon — The public incentivised testnet (M14) is launching shortly. Public RPC endpoint: https://testnet.shell.org · Faucet & explorer are being deployed.

To run a local private testnet in the meantime:

Using Docker

cp .env.example .env
docker compose -f docker-compose.alpha.yml up -d

Health Check

curl http://localhost:9090/health
# {"status":"ok","version":"0.21.0","block_height":...}

curl http://localhost:9090/ready
# {"ready":true} or {"ready":false,"reason":"..."}

For more details on alpha testnet operations, see the Testnet Operator Guide.

Next Steps

Last updated: 2025