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

Prerequisites#

  • Rust 1.75+ (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh)
  • Git

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 (e.g., 0x742d35Cc...). 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": [
      "0xYOUR_ADDRESS_HERE"
    ],
    "block_time_secs": 2,
    "epoch_length": 0
  },
  "alloc": {
    "0xYOUR_ADDRESS_HERE": {
      "balance": "0x3635c9adc5dea00000"
    }
  },
  "boot_nodes": []
}

Replace 0xYOUR_ADDRESS_HERE with the address from Step 2. The balance 0x3635c9adc5dea00000 is 1,000 ETH 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 0xYOUR_ADDRESS_HERE --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":["0xYOUR_ADDRESS_HERE","latest"],"id":1}'

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

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 ETH (1000000000000000000 wei) from your funded account:

shell-node tx send \
  --to 0xRECIPIENT_ADDRESS \
  --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 0xRECIPIENT_ADDRESS --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}'

Alpha Testnet#

Join the public alpha testnet:

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.6.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#

  • Run a multi-node testnet: See the Testnet Operator Guide for Docker deployment with 3 validators + monitoring.
  • Deploy smart contracts: See Smart Contract Guide for deploying Solidity/Vyper contracts with Hardhat or Foundry.
  • Full API reference: See JSON-RPC API Reference for all 61 RPC methods.
  • Understand the cryptography: See PQ Crypto Guide for details on Dilithium3, key formats, and quantum resistance.
  • Deploy a contract: Use shell-node tx deploy --code 0x... --keystore my-key.json.
  • Make a read-only call: Use shell-node tx call --to 0xContractAddr --data 0x....
  • Monitor with Grafana: Start the full stack with docker compose -f docker-compose.prod.yml up -d and open http://localhost:3000.

Last updated: 2025