Canonical AI Workflows
All commands below are checked against the Commander CLI inventory (apps/docs/docs-data/cli-command-inventory.json) and repository simnet guides (docs/start/build-on-simnet.md, docs/start/silverscript-covenants.md, docs/start/receipts-and-levels.md).
Replace
hardkaswithnpx hardkasinside a project where@hardkas/cliis installed, orpnpm hardkasinside the HardKAS monorepo.
1. Send KAS on simnet and Confirm the Transaction
- Goal: Send a real KAS payment on
simnetand confirm inclusion via an independent node query. - Supported environments:
simnet(verified),simulated(synthetic only),testnet-10(experimental opt-in). Mainnet is blocked. - Prerequisites:
- Running
rusty-kaspadv2.1.0simnet node (e.g.hardkas localnet start --profile toccata-v2onws://127.0.0.1:18210, or your own node configured inhardkas.config.ts). - Funded sender account on
simnetwith mature UTXOs (coinbase outputs require 1,000 DAA maturity on simnet) andHARDKAS_PASSWORDset in the environment.
- Running
Option A: Fast 2-step send (when plan review is not needed)
- Omit
--urlif using the default HardKAS localnet (ws://127.0.0.1:18210). Nohardkas.config.mjsis needed:tx send --waitsubmits and waits untilCONFIRMEDon the same--urlnode (default--wait-timeout 60; if confirmation times out, it exits1withcode: TX_SEND_WAIT_FAILEDandoutcome: submitted).
export HARDKAS_PASSWORD='choose-a-simnet-password'
hardkas accounts real import --name payer --address <kaspasim:sender> --network simnet --private-key-env PK --password-env HARDKAS_PASSWORD
hardkas tx send --from payer --to <kaspasim:recipient> --amount 10 --network simnet --url ws://<host>:18210 --password-env HARDKAS_PASSWORD --yes --wait --json
Option B: Audited 4-step lifecycle (plan → verify → sign → send --wait)
hardkas tx plan --network simnet --url ws://<host>:18210 --from miner --to alice --amount 100 --out plan.json
hardkas artifact verify plan.json
hardkas tx sign plan.json --account miner --password-env HARDKAS_PASSWORD --out signed.json
hardkas tx send signed.json --network simnet --url ws://<host>:18210 --yes --wait --json
# Or wait separately: hardkas tx wait <txId> --until confirmed --network simnet --url ws://<host>:18210 --json
- Expected output:
tx sendemits ahardkas.txSubmission.v1record under.hardkas/artifacts/receipts/and printstxId.tx wait --until confirmedpolls until the accepting chain block reaches 100 blue-score confirmations (HardKAS default policy) and the node's UTXO view reflects the outputs. - Avoid: Writing a custom
kaspa-wasmscript to build/sign/send standard payments. - Known limitations:
replay verifydoes not work onsimnet(REPLAY_MODE_UNSUPPORTED); usetx statusandartifact verifyinstead.
2. Compile and Execute SilverScript P2SH Workflows
- Goal: Compile a
.silcontract with the pinnedsilverccompiler, verify reproducibility, deploy a P2SH output onsimnet, and spend it. - Supported environments:
simnet(verified),testnet-10(experimental). Mainnet is refused (SILVERSCRIPT_MAINNET_NOT_ENABLED). - Prerequisites:
hardkas toolchain install silverc(installssilverc v1.0.0with SHA-256 verification).hardkas silver doctor --network simnetreportssilver.compile.v1andsilver.p2sh.deploy-spend.v1asready.- Constructor bytes arguments must use
{ "kind": "bytes", "value": [/* 32-byte x-only pubkey bytes */] }(raw hex strings are rejected withSILVER_VALUE_INVALID).
Commands
# 1. Compile and verify deterministic reproduction
hardkas silver compile contracts/signed-release.sil --args contracts/owner.args.json --network simnet --out contracts/signed-release.compile.json
hardkas silver verify contracts/signed-release.compile.json --args contracts/owner.args.json
# 2. Deploy P2SH output on simnet (v0 by default; --wait confirms UTXO creation)
hardkas silver deploy contracts/signed-release.compile.json --from alice --amount 1 --network simnet --password-env HARDKAS_PASSWORD --wait
# 3. Spend entry using signature arg: [{"kind":"signature","account":"alice"}]
hardkas silver spend .hardkas/artifacts/silver/silverDeploy-<id>.json --entry release --to <alice-address> --args contracts/release.args.json --network simnet --password-env HARDKAS_PASSWORD --wait
- Verification:
silver verifyprintsREPRODUCED <hash> with silverc v1.0.0.silver deployandsilver spendwrite.hardkas/artifacts/silver/silverDeploy-*.jsonandsilverSpend-*.json; verify consensus depth withhardkas artifact verify <record> --network simnet --require consensus. - Important distinction (
silver testvs node validation):hardkas silver testruns the localcli-debuggerrunner (SCRIPT_VM, labelledUNVERIFIED, requires--allow-unverified-runner). It is NOT independent consensus proof.hardkas silver test --on-node --network simnet(experimental) executes reproducible cases as real node transactions and records node verdicts.
3. Perform Valid and Invalid Covenant Transitions Against a Real Node
- Goal: Create a Toccata 1:1 auth-bound covenant (
v1transaction) onsimnet, advance it with a valid state transition, and verify that an invalid transition is rejected byrusty-kaspadconsensus. - Supported environments:
simnet(verified for 1:1 auth-bound transitions). 1:N / N:M / termination (silver covenant start|advance) are experimental. - Prerequisites: Compiled
.silcovenant artifact (e.g.Counterwith#[covenant(binding = auth, from = 1, to = 1, mode = transition)]), funded accountalice, runningrusty-kaspad 2.1.0simnet node with miner active.
Step A — Genesis & Valid Transition
# 1. Compile covenant with initial constructor args (e.g. [{"kind":"int","value":7}])
hardkas silver compile contracts/counter.sil --args contracts/counter.args.json --network simnet --out contracts/counter.compile.json
# 2. Genesis (v1 transaction; explicit compute-budget and fee are required)
hardkas silver covenant genesis contracts/counter.compile.json --from alice --amount 10 --compute-budget 10 --fee 1000000 --network simnet --password-env HARDKAS_PASSWORD --wait
# 3. Valid transition (e.g. bump delta = 5 -> next state value = 12)
hardkas silver covenant transition .hardkas/artifacts/silver/silverCovenant-<genesisId>.json \
--policy bump \
--constructor-args contracts/counter.args.json \
--state-map contracts/counter.state-map.json \
--next-state contracts/counter.next-state.json \
--args contracts/bump.args.json \
--compute-budget 0 \
--emit-args contracts/counter.next-args.json \
--network simnet \
--password-env HARDKAS_PASSWORD \
--wait
Step B — Invalid Transition (Negative Node Consensus Test)
hardkas silver covenant transition checks locally that the template did not change (SILVER_SUCCESSOR_TEMPLATE_CHANGED) and that the compiled successor state differs from the current state (SILVER_SUCCESSOR_STATE_UNCHANGED — so keeping next-state equal to the current state is rejected locally before broadcast). However, HardKAS does not evaluate SilverScript require(...) predicates or state arithmetic locally; rusty-kaspad enforces them at consensus.
To send an invalid transition that reaches the node and tests consensus rejection:
- Keep
--next-statedifferent from the current state (so it passesSILVER_SUCCESSOR_STATE_UNCHANGED), while violating the contract rule — for example, passnext-state{"value":{"kind":"int","value":99}}withdelta = 5(violatesprev_state.value + delta), orvalue: 13withdelta = 0(violatesrequire(delta > 0)). - Run
hardkas silver covenant transition ... --wait --json. - Expected result: HardKAS submits the
v1transaction, the node rejects it at script verification,silver covenant transitionexits non-zero, and the covenant tip on the node remains unchanged.
Step C — Independent Verification
hardkas silver covenant inspect <covenantId> --network simnet
hardkas artifact verify .hardkas/artifacts/silver --recursive
- Expected output:
covenant <covenantId> VERIFIED, showinggenesisanchor verified andtippointing to the unspent successor UTXO on the node. - Note on shells: On PowerShell 5.1 /
cmd, pass--state-mapas a JSON file path (e.g.contracts/counter.state-map.jsoncontaining{"value":0}) to avoid quote-escaping issues.
4. Verify Transaction Receipts and Execution Artifacts
- Goal: Distinguish file integrity, node observation, and consensus confirmation for any transaction or SilverScript artifact.
- Supported environments: Offline integrity works everywhere (including
mainnetartifacts); network/consensus checks require a node on the artifact's network (simnetortestnet-10).
Commands
# 1. Inspect local artifact fields and lineage
hardkas artifact inspect <artifact-or-signed.json> --json
# 2. Offline integrity check (detects tampering via contentHash)
hardkas artifact verify <artifact-or-signed.json> --strict --json
# 3. Real-node consensus check (100 blue-score confirmations by default)
hardkas artifact verify <artifact-or-signed.json> --network simnet --require consensus --json
# 4. Query recorded submission receipt and live node status
hardkas tx receipt <txId> --json
hardkas tx status <txId> --network simnet --json
- Replay asymmetry:
hardkas replay verify <receipt-id>works only forsimulatedledger runs. Real-node sends writehardkas.txSubmission.v1and fail closed onreplay verifywithREPLAY_MODE_UNSUPPORTED.
5. Diagnose Node, RPC, Account, and UTXO Problems
- Goal: Isolate failures across workspace config, Docker container, RPC sync, keystore, or UTXO maturity without guessing.
Commands
# 1. Overall workspace, toolchain, and node readiness
hardkas doctor --network simnet --json
# 2. Docker localnet status (managed container hardkas-kaspad-toccata-v2, wRPC 18210)
hardkas localnet status --json
# 3. Live node health, sync state, and virtual DAA score
hardkas rpc health --network simnet --json
hardkas rpc info --network simnet --json
# 4. Account balance and raw UTXOs visible to the node
hardkas accounts balance <account> --network simnet --json
hardkas rpc utxos <kaspasim-address> --network simnet --json
- Key diagnostic rule:
accounts balancecounts immature coinbase UTXOs, whereastx planskips them (NO_SPENDABLE_UTXOS). Onsimnet, wait ~1,000 DAA with the miner running before spending coinbase rewards.
6. Select the Appropriate HardKAS CLI or SDK Workflow
Use the CLI when orchestrating environments, keystores, or SilverScript tooling, and the TypeScript SDK (@hardkas/sdk) inside application code or Vitest suites.
| Task | Use CLI | Use SDK (@hardkas/sdk) | Notes |
|---|---|---|---|
Start/stop/fund Docker localnet (--profile toccata-v2) | hardkas localnet start|stop|fund | Not supported in 0.13.0-rc.3 | SDK explicitly throws directing you to the CLI. |
Install silverc / kaspa-wasm | hardkas toolchain install | No | CLI-managed with SHA-256 verification. |
| Payments & batching in app logic | hardkas tx plan|sign|send|wait | sdk.tx.plan, sign, send, waitForConfirmations | Both use the kaspa-wasm Generator and emit artifacts. |
| Capability discovery before execution | hardkas doctor --json, hardkas silver doctor --json | sdk.capabilities.get() | Always check capabilities first. |
| SilverScript compile / P2SH / 1:1 covenant | hardkas silver compile|deploy|spend|covenant | sdk.silver.* | CLI is fastest for scripts & ops; SDK for custom tests. |
| Complex v1 covenants (1:N, N:M) | hardkas silver covenant start|advance (experimental) | sdk.covenants.* (experimental) | Requires explicit v1 compute budget & fee. |
Related Repository Resources
- Hands-on simnet walkthrough:
docs/start/build-on-simnet.md,docs/start/quickstart-simnet.md,docs/start/silverscript-covenants.md - Runnable TypeScript examples:
examples/01-hello-kaspathroughexamples/11-kcc20-token(pnpm example:hello,pnpm example:transfer,pnpm example:localnet,pnpm example:covenant-demo) - Builder Labs:
labs/bl-001-offline-multisig,labs/bl-002-escrow-multisig,labs/bl-003-silverscript-covenant,labs/02-merchant-checkout(overview) - Video tutorials: KasLabDevs YouTube