Docs

This page covers how to build, run, inspect, and interact with Compute Substrate using the current csd CLI. The current CLI supports both the original low-level wallet subcommands and the newer easy commands at the top level.

1. Install

Build from source:

git clone https://github.com/compute-substrate/compute-substrate
cd compute-substrate
cargo build --release

Binary will be at:

target/release/csd

Optional:

sudo cp target/release/csd /usr/local/bin/csd

2. Mainnet Hardware Requirements

Running a mainnet node requires reliable hardware and a stable network connection. Requirements scale with chain growth, peer count, and indexing features, so the values below are recommended baselines rather than strict limits.

A practical baseline for mainnet is a modern 4-core CPU, 16 GB RAM, and fast SSD storage, with more headroom preferred for long-running nodes, heavy peer load, or mining. NVMe storage is preferred. Linux is recommended for production deployments. Nodes that fall behind the network may experience delayed synchronization or reduced peer connectivity, and mining performance depends both on CPU availability and on whether the node remains connected and up to date.

3. Create a Genesis File

Create a genesis file:

csd genesis --out genesis.bin

You can also set a burn address explicitly:

csd genesis \
  --out genesis.bin \
  --burn-addr20 0x0000000000000000000000000000000000000000

Parameters:

--out — output path for the genesis file
--burn-addr20 — 20-byte burn address used in genesis

4. Run a Node

csd node \
  --datadir /var/lib/csd/node \
  --rpc 0.0.0.0:8789 \
  --genesis /etc/csd/genesis.bin \
  --p2p-listen /ip4/0.0.0.0/tcp/17999 \
  --bootnodes <multiaddr,...>

A node stores chain state locally, serves RPC, participates in libp2p networking, and syncs headers and blocks from peers. If --bootnodes is omitted, the node starts without explicit peers and must discover the network through other means.

Parameters:

--datadir — database directory
--rpc — RPC listen address
--genesis — path to genesis file
--p2p-listen — libp2p multiaddr to listen on
--bootnodes — comma-separated bootnode multiaddrs

5. Run a Miner

csd node \
  --datadir /var/lib/csd/miner \
  --rpc 0.0.0.0:8789 \
  --mine \
  --miner-addr20 0x... \
  --genesis /etc/csd/genesis.bin \
  --p2p-listen /ip4/0.0.0.0/tcp/17999 \
  --bootnodes <multiaddr,...>

Mining is enabled by adding --mine and a payout address. The miner only produces blocks when the node is in a valid mining state, including peer and freshness gating.

Additional miner parameters:

--mine — enables mining
--miner-addr20 — payout address for block rewards; required with --mine

6. Wallet Setup

Create a fresh keypair:

csd wallet new

Recover the corresponding public key and address from an existing private key:

csd wallet recover --privkey 0x<privkey>

The CLI now supports wallet defaults. This lets you save a default private key, RPC URL, and datadir once, so that later commands can be much shorter.

csd wallet init \
  --privkey 0x<privkey> \
  --rpc-url http://127.0.0.1:8789 \
  --datadir /var/lib/csd/node

Update saved defaults later if needed:

csd wallet set-rpc --rpc-url http://127.0.0.1:8789
csd wallet set-datadir --datadir /var/lib/csd/node
csd wallet config

Once initialized, the top-level easy commands can use your saved private key and RPC configuration automatically.

7. Check Balance

csd wallet balance \
  --address 0x<addr20> \
  --datadir /var/lib/csd/node

This inspects the local datadir directly. It does not query a remote node.

8. Inspect UTXOs

You can still inspect spendable local inputs directly:

csd wallet input \
  --privkey 0x<privkey> \
  --datadir /var/lib/csd/node \
  --min 25000000

Or by address:

csd wallet input \
  --address 0x<addr20> \
  --datadir /var/lib/csd/node \
  --min 25000000

This prints one candidate input as txid:vout:value. The low-level wallet input command reads from the local database. The newer easy commands instead prefer RPC-based input selection so they can avoid choosing an outpoint already reserved in the mempool.

9. Easy Spend

The new top-level csd spend command is the simplest way to build a normal spend transaction. If you do not provide --input, it automatically selects an available input over RPC using your configured wallet key and RPC URL.

csd spend \
  --fee 1000 \
  --output 0x<addr20>:100000

You can still override everything explicitly:

csd spend \
  --privkey 0x<privkey> \
  --rpc-url http://127.0.0.1:8789 \
  --input 0x<txid>:0:250000 \
  --output 0x<addr20>:100000 \
  --fee 1000 \
  --change 0x<change-addr20>

Parameters:

--privkey — optional; uses saved wallet key if omitted
--input — manual input triple in the form <txid>:<vout>:<value>; can be repeated
--auto-input — force auto-pick mode explicitly; usually unnecessary because easy commands auto-pick when no input is given
--min-input — minimum value required for auto input selection
--datadir — optional local datadir override
--output — output pair in the form <addr20>:<value>; can be repeated
--fee — fee in native units
--change — optional change address; otherwise the CLI derives it from the sender unless a saved default exists

10. Easy Propose

The new top-level csd propose command is the main user-facing path for submitting proposals. It can auto-pick an available input via RPC, derive the sender from the saved private key, compute the payload hash automatically, and default expiry for you.

Simplest form:

csd propose \
  --fee 25000000 \
  --domain test \
  --payload "hello world"

More explicit form:

csd propose \
  --fee 25000000 \
  --domain eth_price_weekly \
  --payload "ETH > 4000 by Friday" \
  --uri "ETH > 4000 by Friday" \
  --rpc-url http://127.0.0.1:8789

Or provide the payload hash yourself:

csd propose \
  --fee 25000000 \
  --domain eth_price_weekly \
  --payload-hash 0x<32-byte-hash> \
  --uri "ETH > 4000 by Friday"

Parameters:

--privkey — optional; uses saved wallet key if omitted
--input — optional manual input triple; can be repeated
--auto-input — force auto-pick mode explicitly
--min-input — minimum value required for auto input selection; defaults to fee
--datadir — optional local datadir override
--fee — fee in native units
--change — optional change address
--domain — proposal namespace
--payload — raw payload text; the CLI computes payload_hash automatically
--payload-hash — explicit 32-byte payload hash instead of --payload
--uri — human-readable description or pointer; if omitted and --payload is used, the CLI uses the payload text as the URI
--expires-epoch — optional explicit expiry; if omitted the CLI sets a default future epoch automatically
--rpc-url — optional; uses saved wallet RPC if omitted

Use either --payload or --payload-hash, but not both. The easy path is intended for human use: write the payload once, let the CLI hash it, and submit directly.

11. Easy Attest

The new top-level csd attest command is the main user-facing path for attestations. Like csd propose, it can auto-pick an available RPC-visible input when one is not provided manually.

csd attest \
  --fee 25000000 \
  --proposal-id 0x<proposal-id> \
  --score 100 \
  --confidence 90

Parameters:

--privkey — optional; uses saved wallet key if omitted
--input — optional manual input triple; can be repeated
--auto-input — force auto-pick mode explicitly
--min-input — minimum value required for auto input selection; defaults to fee
--datadir — optional local datadir override
--fee — fee in native units
--change — optional change address
--proposal-id — proposal txid being attested to
--score — structured score field stored in the attestation
--confidence — structured confidence field stored in the attestation
--rpc-url — optional; uses saved wallet RPC if omitted

The attestation object contains score and confidence as explicit fields, while canonical ranking currently grows by attestation fee.

12. Low-Level Wallet Commands

The original low-level commands remain available under csd wallet. These are useful for debugging, reproducible test flows, scripts, and situations where you want explicit local control over every field.

Build but do not submit a proposal:

csd wallet propose-build \
  --privkey 0x<privkey> \
  --auto-input \
  --datadir /var/lib/csd/node \
  --min-input 25000000 \
  --fee 25000000 \
  --domain eth_price_weekly \
  --payload-hash 0x<32-byte-hash> \
  --uri "ETH > 4000 by Friday" \
  --expires-epoch 100

Build but do not submit an attestation:

csd wallet attest-build \
  --privkey 0x<privkey> \
  --auto-input \
  --datadir /var/lib/csd/node \
  --min-input 25000000 \
  --fee 25000000 \
  --proposal-id 0x<proposal-id> \
  --score 100 \
  --confidence 90

Build and submit via the original wallet path:

csd wallet propose ...
csd wallet attest ...
csd wallet spend ...

The top-level easy commands are the recommended user path. The csd wallet ... commands remain the explicit low-level path.

13. Chain Inspection Helpers

Expected minted supply through a given height:

csd chain expected-supply --height 1000

This sums block rewards from genesis through the given height inclusively.

14. Database Inspection Helpers

Sum all current UTXO values in a datadir:

csd db sum-utxos --datadir /var/lib/csd/node

This is a local inspection command and is useful for invariant testing, debugging, and supply checks.

15. Query Outputs Over RPC

Examples:

curl http://127.0.0.1:8789/tip
curl http://127.0.0.1:8789/health
curl http://127.0.0.1:8789/mempool
curl http://127.0.0.1:8789/block/0x<block-hash>
curl http://127.0.0.1:8789/utxos/0x<addr20>
curl "http://127.0.0.1:8789/utxos/0x<addr20>?available=true&min_value=25000000&limit=1"
curl http://127.0.0.1:8789/proposal/0x<proposal-id>
curl http://127.0.0.1:8789/top/eth_price_weekly
curl http://127.0.0.1:8789/top/eth_price_weekly/0

The /utxos/:addr20 endpoint can now be used as a better input-selection surface, including filters such as available-only, minimum value, and result limits. The easy CLI commands rely on this surface when auto-picking inputs.

16. Transaction Template Endpoints

Public template endpoints remain available for external tooling that wants to build unsigned proposal or attestation transactions, sign them independently, and then submit them later.

POST /tx/template/propose
POST /tx/template/attest
POST /tx/submit

These are intended for external clients, scripts, and custom integrations. The CLI easy commands are the simpler path for most users.

17. Concepts

A domain is the namespace a proposal belongs to. A proposal is a persisted claim or candidate with a payload commitment. An attestation is a persisted support signal pointing at a proposal. Score and confidence are structured fields stored inside the attestation object. Aggregate weight is the current canonical ranking contribution and is presently derived from attestation fee. An epoch is the chain time bucket used for expiry and ranking windows.

18. Notes

Compute Substrate records inputs and aggregates them, but does not decide outcomes. Outputs are non-authoritative. Interpretation and action remain external. The private key is currently the recovery mechanism for a wallet. The current CLI now exposes both explicit low-level wallet commands and simpler top-level commands designed to reduce friction for normal users.