CLI Reference¶

Complete reference for the dilithia-contract CLI. All subcommands are documented below with their full flag set, descriptions, and examples.

Global Options¶

dilithia-contract [OPTIONS] <COMMAND>

Flag	Description
`--version`	Print version information
`--help`	Print help information

Environment Variables¶

Variable	Used by	Description
`DILITHIA_SECRET_KEY`	`deploy`, `upgrade`, `call`	Default signing key. Used when `--secret-key` is not provided on the command line. Hex-encoded ML-DSA-65 secret key.

`init`¶

Scaffold a new contract project.

Synopsis¶

dilithia-contract init --name <NAME>

Description¶

Creates a new directory named <NAME> containing a starter Dilithia smart contract project with:

pinned Rust toolchain metadata
vendored contract SDK and macros
generated Cargo.lock
src/lib.rs with a template contract featuring set, get, and del methods

Arguments¶

Flag	Required	Default	Description
`--name <NAME>`	Yes	--	Name for the new contract project. Used as the directory name and the contract module name.

Examples¶

# Create a new token contract
dilithia-contract init --name my_token

# Create and immediately enter the project
dilithia-contract init --name dao_voting && cd dao_voting

`build`¶

Compile a contract to WASM.

Synopsis¶

dilithia-contract build [--path <PATH>] [--release] [--optimize]

Description¶

Runs cargo build --locked --target wasm32-unknown-unknown inside the specified project directory. By default, builds in release mode and requires wasm-opt to succeed when optimization is enabled.

The compiled artifact is placed at <PATH>/target/wasm32-unknown-unknown/release/<name>.wasm. A successful build also emits <name>.abi.json beside the .wasm.

Arguments¶

Flag	Required	Default	Description
`--path <PATH>`	No	`.`	Path to the contract project directory
`--release`	No	`true`	Build in release mode. Pass `--release false` for a debug build.
`--optimize`	No	`true`	Require `wasm-opt` on the output. If `wasm-opt` is unavailable or fails, the build fails. Pass `--optimize false` only when you explicitly want a non-optimized build.

Examples¶

# Build the contract in the current directory
dilithia-contract build

# Build a contract in a specific directory
dilithia-contract build --path ./contracts/my_token

# Debug build without optimization
dilithia-contract build --release false --optimize false

Output Metadata¶

Successful JSON output includes: - artifact_sha256 - cargo_lock_path - abi - abi_path - abi_error - environment.rustc_version - environment.cargo_version - environment.wasm_opt_version - optimization_applied

`extract-abi`¶

Extract ABI metadata from a compiled WASM artifact.

Synopsis¶

dilithia-contract extract-abi --wasm <PATH>

Description¶

Parses the compiled WASM module and extracts the JSON ABI embedded by the Dilithia contract SDK macro. This is intended for developer tooling and CI, not for general chain clients.

Arguments¶

Flag	Required	Default	Description
`--wasm <PATH>`	Yes	--	Path to the compiled `.wasm` file

Examples¶

dilithia-contract extract-abi \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm

dilithia-contract extract-abi \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm \
  --output json

`deploy`¶

Deploy a compiled contract to the network.

Synopsis¶

dilithia-contract deploy \
  --name <NAME> \
  --wasm <PATH> \
  --rpc <URL> \
  --secret-key <HEX> \
  [--chain-id <ID>] \
  [--nonce <N>]

Description¶

Submits a deploy transaction containing the compiled WASM bytecode to the specified Dilithia node. The transaction is signed with the provided ML-DSA-65 secret key. The CLI:

Reads the .wasm file and hex-encodes it
Derives the public key and sender address from the secret key
Fetches the current nonce from the node (unless --nonce is provided)
Builds a canonical deploy payload (alphabetically sorted keys)
Signs the payload with ML-DSA-65
POSTs the full deploy request using the SDK Rust request builder for the configured node base URL

Arguments¶

Flag	Required	Default	Description
`--name <NAME>`	Yes	--	Contract name. Used as the on-chain identifier.
`--wasm <PATH>`	Yes	--	Path to the compiled `.wasm` file
`--rpc <URL>`	Yes	--	RPC endpoint URL (e.g., `http://localhost:8000/rpc`)
`--secret-key <HEX>`	Yes	`$DILITHIA_SECRET_KEY`	Hex-encoded ML-DSA-65 secret key for signing
`--chain-id <ID>`	No	`dilithia`	Chain ID to include in the signed payload
`--nonce <N>`	No	auto-fetched	Transaction nonce. If omitted, fetched from the node via `GET <RPC>/nonce/<address>`.

Examples¶

# Deploy with explicit secret key
dilithia-contract deploy \
  --name my_token \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm \
  --rpc http://localhost:8000/rpc \
  --secret-key abc123...

# Deploy using environment variable for the key
export DILITHIA_SECRET_KEY=abc123...
dilithia-contract deploy \
  --name my_token \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm \
  --rpc http://localhost:8000/rpc

# Deploy with explicit nonce and chain ID
dilithia-contract deploy \
  --name my_token \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm \
  --rpc http://localhost:8000/rpc \
  --secret-key $DILITHIA_SECRET_KEY \
  --chain-id testnet \
  --nonce 42

`upgrade`¶

Upgrade an existing contract with new WASM bytecode.

Synopsis¶

dilithia-contract upgrade \
  --name <NAME> \
  --wasm <PATH> \
  --rpc <URL> \
  --secret-key <HEX> \
  [--chain-id <ID>] \
  [--nonce <N>]

Description¶

Replaces the on-chain WASM for an already-deployed contract. Uses the same signing flow as deploy, but sends the request through the SDK Rust upgrade request builder. Only the original deployer (admin) can upgrade a contract. Existing contract storage is preserved.

Arguments¶

Flag	Required	Default	Description
`--name <NAME>`	Yes	--	Name of the deployed contract to upgrade
`--wasm <PATH>`	Yes	--	Path to the new compiled `.wasm` file
`--rpc <URL>`	Yes	--	RPC endpoint URL
`--secret-key <HEX>`	Yes	`$DILITHIA_SECRET_KEY`	Hex-encoded ML-DSA-65 secret key for signing
`--chain-id <ID>`	No	`dilithia`	Chain ID
`--nonce <N>`	No	auto-fetched	Transaction nonce

Examples¶

# Upgrade a contract after rebuilding
dilithia-contract build
dilithia-contract upgrade \
  --name my_token \
  --wasm target/wasm32-unknown-unknown/release/my_token.wasm \
  --rpc http://localhost:8000/rpc \
  --secret-key $DILITHIA_SECRET_KEY

`call`¶

Execute a state-changing contract method via a signed transaction.

Synopsis¶

dilithia-contract call \
  --contract <NAME> \
  --method <METHOD> \
  --rpc <URL> \
  --secret-key <HEX> \
  [--args <JSON>] \
  [--chain-id <ID>] \
  [--nonce <N>] \
  [--wait]

Description¶

Sends a signed transaction that invokes a contract method. The CLI:

Derives the sender address from the secret key
Fetches the current nonce (unless provided)
Builds a canonical call payload with alphabetically sorted keys: args, chain_id, contract, from, method, nonce
Signs the payload with ML-DSA-65
POSTs the call using the SDK Rust request builder for the configured node base URL
If --wait is set, polls <RPC>/receipt/<tx_hash> until the transaction is confirmed (timeout: 60 seconds)

Arguments¶

Flag	Required	Default	Description
`--contract <NAME>`	Yes	--	Contract address or name
`--method <METHOD>`	Yes	--	Method name to invoke
`--args <JSON>`	No	`{}`	JSON-encoded arguments to pass to the method
`--rpc <URL>`	Yes	--	RPC endpoint URL
`--secret-key <HEX>`	Yes	`$DILITHIA_SECRET_KEY`	Hex-encoded ML-DSA-65 secret key for signing
`--chain-id <ID>`	No	`dilithia`	Chain ID
`--nonce <N>`	No	auto-fetched	Transaction nonce
`--wait`	No	`false`	Block until the transaction is included in a block

Examples¶

# Transfer tokens and wait for confirmation
dilithia-contract call \
  --contract my_token \
  --method transfer \
  --args '{"to":"0xabc...","amount":100}' \
  --rpc http://localhost:8000/rpc \
  --secret-key $DILITHIA_SECRET_KEY \
  --wait

# Call with no arguments
dilithia-contract call \
  --contract my_dao \
  --method finalize_vote \
  --rpc http://localhost:8000/rpc \
  --secret-key $DILITHIA_SECRET_KEY

# Fire-and-forget (don't wait for receipt)
dilithia-contract call \
  --contract my_token \
  --method set \
  --args '{"key":"version","value":"2.0"}' \
  --rpc http://localhost:8000/rpc \
  --secret-key $DILITHIA_SECRET_KEY

`query`¶

Read contract state without submitting a transaction.

Synopsis¶

dilithia-contract query \
  --contract <NAME> \
  --method <METHOD> \
  --rpc <URL> \
  [--args <JSON>]

Description¶

Performs a read-only query against a deployed contract. No signing key is required because queries do not modify state or cost gas. The CLI sends a GET request to the node's query endpoint with the contract name, method, and URL-encoded arguments.

Arguments¶

Flag	Required	Default	Description
`--contract <NAME>`	Yes	--	Contract address or name
`--method <METHOD>`	Yes	--	Method name to query
`--args <JSON>`	No	`{}`	JSON-encoded arguments
`--rpc <URL>`	Yes	--	RPC endpoint URL

Examples¶

# Query a balance
dilithia-contract query \
  --contract my_token \
  --method balance \
  --args '{"addr":"0xabc..."}' \
  --rpc http://localhost:8000/rpc

# Query with no arguments
dilithia-contract query \
  --contract my_token \
  --method total_supply \
  --rpc http://localhost:8000/rpc

CLI Reference¶

Global Options¶

Environment Variables¶

init¶

Synopsis¶

Description¶

Arguments¶

Examples¶

build¶

Synopsis¶

Description¶

Arguments¶

Examples¶

Output Metadata¶

extract-abi¶

Synopsis¶

Description¶

Arguments¶

Examples¶

deploy¶

Synopsis¶

Description¶

Arguments¶

Examples¶

upgrade¶

Synopsis¶

Description¶

Arguments¶

Examples¶

call¶

Synopsis¶

Description¶

Arguments¶

Examples¶

query¶

Synopsis¶

Description¶

Arguments¶

Examples¶

`init`¶

`build`¶

`extract-abi`¶

`deploy`¶

`upgrade`¶

`call`¶

`query`¶