sigil-cli · crate

pub mod genesis_ceremony;

#[derive(Debug, Clone, Parser)]
#[command(name = "sigil", version, about = "Sigil blockchain CLI")]
pub struct Cli {
/// The subcommand to execute.

#[command(subcommand)]
pub command: Commands,
/// RPC endpoint URL.

#[arg(long, default_value = "http://localhost:12618", global = true)]
pub rpc_url: String,
/// Chain ID.

#[arg(long, default_value = "sigil-mainnet-1", global = true)]
pub chain_id: String,
/// Sender DID for transaction-oriented subcommands.

#[arg(long, global = true)]
pub tx_sender_did: Option<String>,
/// Sender nonce for transaction-oriented subcommands.

#[arg(long, global = true)]
pub tx_nonce: Option<u64>,
/// 32-byte Ed25519 signing key as lowercase hex for transaction-oriented subcommands.

#[arg(long, global = true, conflicts_with = "tx_signing_key_file")]
pub tx_signing_key_hex: Option<String>,
/// File containing a 32-byte Ed25519 signing key as hex for transaction-oriented subcommands.

#[arg(long, global = true, conflicts_with = "tx_signing_key_hex")]
pub tx_signing_key_file: Option<String>
}

#[derive(Debug, Clone, Subcommand)]
pub enum Commands {
    /// NFT collection and token management.
    Nft {
        #[command(subcommand)]
        cmd: NftCommands,
    },
    /// DEX pool, swap, and liquidity operations.
    Dex {
        #[command(subcommand)]
        cmd: DexCommands,
    },
    /// Custom token class, mint, burn, and transfer operations.
    Token {
        #[command(subcommand)]
        cmd: TokenCommands,
    },
    /// Nova world, parcel, avatar, building, and auction operations.
    Nova {
        #[command(subcommand)]
        cmd: NovaCommands,
    },
    /// Initialize a new Sigil node data directory.
    Init {
        /// Chain ID to initialize with (overrides the global --chain-id for init).
        #[arg(long = "init-chain-id", default_value = "sigil-testnet-1")]
        init_chain_id: String,
        /// Path to the genesis file.
        #[arg(long, default_value = "genesis.json")]
        genesis: String,
        /// Data directory to initialize.
        #[arg(long, default_value = "./data")]
        data_dir: String,
        /// Validator DID (omit for non-validator nodes).
        #[arg(long)]
        validator_did: Option<String>,
    },
    /// Genesis management commands.
    Genesis {
        #[command(subcommand)]
        cmd: GenesisCommands,
    },
    /// Node management commands.
    Node {
        #[command(subcommand)]
        cmd: NodeCommands,
    },
    /// Staking operations.
    Stake {
        #[command(subcommand)]
        cmd: StakeCommands,
    },
    /// Governance participation.
    Gov {
        #[command(subcommand)]
        cmd: GovCommands,
    },
    /// On-chain identity document registration.
    Identity {
        #[command(subcommand)]
        cmd: IdentityCommands,
    },
    /// Query blockchain state.
    Query {
        #[command(subcommand)]
        cmd: QueryCommands,
    },
    /// Labor market job, bid, escrow, milestone, and dispute operations.
    Labor {
        #[command(subcommand)]
        cmd: LaborCommands,
    },
    /// Username registration and reverse lookup operations.
    Username {
        #[command(subcommand)]
        cmd: UsernameCommands,
    },
    /// Register and deploy WASM smart contracts.
    Contract {
        #[command(subcommand)]
        cmd: ContractCommands,
    },
    /// Native Sigil Mail registry operations.
    Mail {
        #[command(subcommand)]
        cmd: MailCommands,
    },
    /// Sigil Name System resolver operations.
    Sns {
        #[command(subcommand)]
        cmd: SnsCommands,
    },
    /// Crucible distributed training coordination.
    Crucible {
        #[command(subcommand)]
        cmd: CrucibleCommands,
    },
    /// Storage pinning marketplace provider and pin-contract operations.
    Storage {
        #[command(subcommand)]
        cmd: StorageCommands,
    },
    /// Compute provider tools.
    #[cfg(feature = "compute")]
    Compute {
        #[command(subcommand)]
        cmd: ComputeCommands,
    },
    /// Validator registration and management.
    Validator {
        #[command(subcommand)]
        cmd: ValidatorCommands,
    },
    /// Send a signed native token transfer.
    Transfer {
        /// Sender DID.
        #[arg(long)]
        sender_did: String,
        /// Recipient DID.
        #[arg(long)]
        to: String,
        /// Amount in the network's smallest native unit.
        #[arg(long)]
        amount: u64,
        /// Sender nonce. Use `sigil query balance <did>` first.
        #[arg(long)]
        nonce: u64,
        /// 32-byte Ed25519 signing key as lowercase hex.
        #[arg(long, conflicts_with = "signing_key_file")]
        signing_key_hex: Option<String>,
        /// File containing a 32-byte Ed25519 signing key as hex.
        #[arg(long, conflicts_with = "signing_key_hex")]
        signing_key_file: Option<String>,
    },
    /// Show the status of the connected node.
    Status,
}

#[derive(Debug, Clone, Subcommand)]
pub enum GenesisCommands {
    /// Generate a testnet genesis configuration.
    Generate {
        /// Number of validators to include.
        #[arg(long, default_value_t = 4)]
        validators: usize,
        /// Genesis time as Unix timestamp (0 = use current time).
        #[arg(long, default_value_t = 0)]
        genesis_time: u64,
        /// Output file path for the genesis JSON.
        #[arg(long, default_value = "genesis.json")]
        output: String,
    },
    /// Validate an existing genesis file.
    Validate {
        /// Path to the genesis file.
        #[arg(long, default_value = "genesis.json")]
        genesis: String,
    },
    /// Display summary information about a genesis file.
    Show {
        /// Path to the genesis file.
        #[arg(long, default_value = "genesis.json")]
        genesis: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum NodeCommands {
    /// Start the node with the given configuration.
    Start {
        /// Path to the node config file (TOML).
        #[arg(long, default_value = "config.toml")]
        config: String,
        /// Node operating mode.
        #[arg(long, default_value = "validator")]
        mode: String,
        /// Data directory.
        #[arg(long, default_value = "./data")]
        data_dir: String,
        /// P2P listen address.
        #[arg(long, default_value = "0.0.0.0:26656")]
        p2p_addr: String,
        /// RPC listen address.
        #[arg(long, default_value = "0.0.0.0:12618")]
        rpc_addr: String,
        /// Validator DID (required for validator/producer modes).
        #[arg(long)]
        validator_did: Option<String>,
    },
    /// Show the node's sync status.
    Status,
    /// Show node info (chain ID, version, mode).
    Info,
    /// List connected peers.
    Peers,
}

#[derive(Debug, Clone, Subcommand)]
pub enum ValidatorCommands {
    /// Register as a validator.
    Register {
        /// Validator OAS DID.
        #[arg(long)]
        did: String,
        /// Initial stake in micro-MINT.
        #[arg(long)]
        stake: u64,
        /// Validator mode: "producer" or "validator".
        #[arg(long, default_value = "validator")]
        mode: String,
        /// Human root DID for lineage verification.
        #[arg(long)]
        human_root: String,
    },
    /// Show this node's validator keys.
    ShowKeys {
        /// Data directory.
        #[arg(long, default_value = "./data")]
        data_dir: String,
    },
    /// Generate new testnet validator keys.
    GenerateKeys {
        /// Validator DID to generate keys for.
        #[arg(long)]
        did: String,
        /// Data directory to write keys to.
        #[arg(long, default_value = "./data")]
        data_dir: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum StakeCommands {
    /// Deposit stake to become a validator.
    Deposit {
        /// Amount in micro-MINT.
        amount: u64,
        /// Validator mode: "producer" or "validator".
        #[arg(long)]
        mode: String,
    },
    /// Withdraw stake (begins unbonding period).
    Withdraw {
        /// Amount in micro-MINT.
        amount: u64,
    },
    /// Delegate stake to a validator.
    Delegate {
        /// Validator DID.
        validator: String,
        /// Amount in micro-MINT.
        amount: u64,
    },
    /// Undelegate stake from a validator.
    Undelegate {
        /// Validator DID.
        validator: String,
        /// Amount in micro-MINT.
        amount: u64,
    },
    /// Show accumulated rewards.
    Rewards,
}

#[derive(Debug, Clone, Subcommand)]
pub enum GovCommands {
    /// Submit a governance proposal.
    Propose {
        /// Proposal title.
        title: String,
        /// Proposal description.
        #[arg(long)]
        description: String,
    },
    /// Vote on a governance proposal.
    Vote {
        /// Proposal ID.
        proposal_id: String,
        /// Vote choice: yes, no, abstain, no_with_veto.
        choice: String,
    },
    /// List all proposals.
    ListProposals,
    /// Show details of a specific proposal.
    ShowProposal {
        /// Proposal ID.
        proposal_id: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum QueryCommands {
    /// Query balance and nonce by DID.
    Balance {
        /// Account DID.
        did: String,
    },
    /// Query a block by height (defaults to latest).
    Block {
        /// Block height (omit for latest).
        #[arg(long)]
        height: Option<u64>,
    },
    /// Query a transaction by hash.
    Tx {
        /// Transaction hash (hex).
        hash: String,
    },
    /// Query a state value by partition and key.
    State {
        /// State partition (e.g. "identity", "stakes").
        partition: String,
        /// State key.
        key: String,
    },
    /// Query validator info by DID.
    Validator {
        /// Validator DID.
        did: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum LaborCommands {
    /// Post a labor job.
    PostJob {
        #[arg(long)]
        job_id: String,
        #[arg(long)]
        poster_did: String,
        #[arg(long)]
        budget: u128,
        /// Sender nonce. Required when submitting.
        #[arg(long)]
        nonce: Option<u64>,
        /// 32-byte Ed25519 signing key as lowercase hex.
        #[arg(long, conflicts_with = "signing_key_file")]
        signing_key_hex: Option<String>,
        /// File containing a 32-byte Ed25519 signing key as hex.
        #[arg(long, conflicts_with = "signing_key_hex")]
        signing_key_file: Option<String>,
    },
    /// Submit a bid for a job.
    SubmitBid {
        #[arg(long)]
        bid_id: String,
        #[arg(long)]
        job_id: String,
        #[arg(long)]
        bidder_did: String,
        #[arg(long)]
        price: u128,
    },
    /// Accept a submitted bid.
    AcceptBid {
        #[arg(long)]
        job_id: String,
        #[arg(long)]
        bid_id: String,
    },
    /// Fund contract escrow.
    FundEscrow {
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        funder_did: String,
        #[arg(long)]
        amount: u128,
    },
    /// Open and fund a bounty-style Labor offer.
    OpenOffer {
        #[arg(long)]
        offer_id: String,
        #[arg(long)]
        sponsor_did: String,
        #[arg(long, default_value = "SIGIL")]
        token_id: String,
        #[arg(long)]
        total_funding: u128,
        #[arg(long)]
        per_claim_payout_cap: u128,
        #[arg(long)]
        claim_bond: u128,
        #[arg(long)]
        spam_fee: u128,
        #[arg(long)]
        max_claims: u32,
        #[arg(long)]
        claim_window_start_block: u64,
        #[arg(long)]
        claim_window_end_block: u64,
        #[arg(long)]
        claim_timeout_blocks: u64,
        #[arg(long)]
        verification_mode: String,
        #[arg(long = "verifier-did")]
        verifier_dids: Vec<String>,
        #[arg(long)]
        threshold: u32,
        #[arg(long)]
        title_commitment: String,
        #[arg(long)]
        description_commitment: String,
        #[arg(long)]
        category: String,
        #[arg(long)]
        escrow_account_did: String,
        #[arg(long = "required-skill")]
        required_skills: Vec<String>,
        #[arg(long = "required-attestation")]
        required_attestations: Vec<String>,
        #[arg(long)]
        artifact_policy_commitment: Option<String>,
    },
    /// Submit a bonded claim against an open Labor offer.
    SubmitClaim {
        #[arg(long)]
        claim_id: String,
        #[arg(long)]
        offer_id: String,
        #[arg(long)]
        claimant_did: String,
        #[arg(long)]
        deliverable_hash: String,
        #[arg(long = "evidence-hash")]
        evidence_hashes: Vec<String>,
        #[arg(long)]
        requested_payout: u128,
    },
    /// Attest a claim against an open Labor offer.
    AttestClaim {
        #[arg(long)]
        attestation_id: String,
        #[arg(long)]
        claim_id: String,
        #[arg(long)]
        offer_id: String,
        #[arg(long)]
        attester_did: String,
        #[arg(long)]
        verdict: String,
        #[arg(long)]
        reason_commitment: Option<String>,
    },
    /// Cancel an open Labor offer after active claims settle or time out.
    CancelOffer {
        #[arg(long)]
        offer_id: String,
        #[arg(long)]
        sponsor_did: String,
        #[arg(long)]
        reason: Option<String>,
    },
    /// Submit a milestone deliverable.
    SubmitMilestone {
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        milestone_index: u32,
        #[arg(long)]
        deliverable_id: String,
        #[arg(long)]
        payload_hash: String,
        #[arg(long)]
        worker_did: String,
    },
    /// Attest/approve a submitted milestone.
    ApproveMilestone {
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        milestone_index: u32,
        #[arg(long)]
        attestation_id: String,
        #[arg(long)]
        attester_did: String,
    },
    /// Release payment for an attested milestone.
    ReleaseMilestone {
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        milestone_index: u32,
    },
    /// Open a labor dispute.
    OpenDispute {
        #[arg(long)]
        dispute_id: String,
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        raiser_did: String,
        #[arg(long)]
        cause: String,
    },
    /// Resolve a labor dispute.
    ResolveDispute {
        #[arg(long)]
        dispute_id: String,
        #[arg(long)]
        resolver_did: String,
        #[arg(long)]
        resolution: String,
    },
    /// Inspect live labor state through RPC.
    Inspect {
        #[arg(long)]
        job_id: Option<String>,
        #[arg(long)]
        bid_id: Option<String>,
        #[arg(long)]
        contract_id: Option<String>,
        #[arg(long)]
        dispute_id: Option<String>,
        #[arg(long)]
        offer_id: Option<String>,
        #[arg(long)]
        claim_id: Option<String>,
        #[arg(long)]
        account_did: Option<String>,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum UsernameCommands {
    /// Register an @username for a DID.
    Register {
        #[arg(long)]
        name: String,
        #[arg(long)]
        owner_did: String,
        #[arg(long, default_value_t = 1)]
        years: u32,
        /// Optional 32-byte metadata CID/hash as hex.
        #[arg(long)]
        metadata_cid: Option<String>,
    },
    /// Resolve a username to its owner record.
    Lookup {
        #[arg(long)]
        name: String,
    },
    /// Resolve a DID's primary username.
    Reverse {
        #[arg(long)]
        did: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum IdentityCommands {
    /// Register a DID document for the signing key.
    Register {
        /// DID subject to register. Must match the transaction sender.
        #[arg(long)]
        did: String,
        /// Optional canonical DID document JSON or path. Defaults to a minimal Ed25519 DID document.
        #[arg(long)]
        document_json: Option<String>,
        /// Initial conformance level.
        #[arg(long, default_value = "L1")]
        conformance_level: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum ContractCommands {
    /// Register WASM bytecode by content hash before deployment.
    RegisterCode {
        /// Path to a WASM bytecode file.
        #[arg(long)]
        code: String,
        /// SPDX license expression or governance-approved license label.
        #[arg(long)]
        license: String,
        /// Optional source artifact URI.
        #[arg(long)]
        source_uri: Option<String>,
        /// Optional BLAKE3/Sigil hash of the source artifact.
        #[arg(long)]
        source_hash: Option<String>,
        /// Optional audit report URI.
        #[arg(long)]
        audit_uri: Option<String>,
        /// Optional JSON object string for deterministic metadata.
        #[arg(long)]
        metadata_json: Option<String>,
    },
    /// Deploy a contract from previously registered bytecode.
    Deploy {
        /// Contract DID to create.
        #[arg(long)]
        contract_did: String,
        /// Hex or `blake3:<hex>` code hash registered on-chain.
        #[arg(long)]
        code_hash: String,
        /// Optional Organization Zone ID.
        #[arg(long)]
        zone_id: Option<String>,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum MailCommands {
    /// Create a mailbox from canonical MailCreateMailboxData JSON.
    CreateMailbox {
        /// Inline JSON or a path to a JSON file.
        #[arg(long)]
        data_json: String,
    },
    /// Resolve a mailbox route, alias, DID, wallet, or .sigil name.
    Resolve {
        #[arg(long)]
        route_or_name: String,
    },
    /// Fetch one mailbox capability record.
    GetMailbox {
        #[arg(long)]
        mailbox_id: String,
    },
    /// List mailboxes owned by a subject DID.
    ListByOwner {
        #[arg(long)]
        subject_did: String,
    },
    /// Fetch the current or a historical receive policy.
    Policy {
        #[arg(long)]
        mailbox_id: String,
        #[arg(long)]
        version: Option<u64>,
    },
    /// List active mail public keys.
    Keys {
        #[arg(long)]
        mailbox_id: String,
        #[arg(long)]
        purpose: Option<String>,
    },
    /// Fetch one delivery commitment.
    Delivery {
        #[arg(long)]
        delivery_commitment_id: String,
    },
    /// Scan delivery commitments by recipient mailbox.
    DeliveriesByRecipient {
        #[arg(long)]
        mailbox_id: String,
        #[arg(long)]
        cursor: Option<String>,
        #[arg(long, default_value_t = 100)]
        limit: u32,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum SnsCommands {
    /// Register a .sigil name through the reveal path.
    RegisterName {
        #[arg(long)]
        name: String,
        #[arg(long)]
        owner_did: String,
        #[arg(long, default_value_t = 1)]
        years: u8,
        #[arg(long)]
        salt: String,
        #[arg(long)]
        reveal_nonce: String,
        #[arg(long)]
        client_nonce: String,
    },
    /// Resolve a name and all public resolver records.
    ResolveName {
        #[arg(long)]
        name: String,
    },
    /// Fetch resolver records for a name.
    GetRecords {
        #[arg(long)]
        name: String,
    },
    /// Resolve a mail route through SNS.
    ResolveMail {
        #[arg(long)]
        route_or_name: String,
    },
    /// Resolve public website records.
    ResolveWebsite {
        #[arg(long)]
        name: String,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum CrucibleCommands {
    /// Open a training run and escrow its reward pool.
    Open {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        coordinator_did: String,
        #[arg(long)]
        reward_pool: u64,
        #[arg(long, default_value = "MINT")]
        reward_token_id: String,
        #[arg(long)]
        model_family: String,
        #[arg(long)]
        objective_cid: String,
        #[arg(long)]
        objective_blake3: String,
        #[arg(long, default_value_t = 1)]
        policy_version: u32,
        #[arg(long, default_value = "coordinator_signed")]
        verifier_mode: String,
        #[arg(long, default_value_t = 1)]
        min_verifier_attestations: u32,
        #[arg(long, default_value_t = 8)]
        max_staleness_epochs: u64,
        #[arg(long = "verifier-did")]
        verifier_dids: Vec<String>,
        #[arg(long = "publisher-did")]
        publisher_dids: Vec<String>,
        #[arg(long)]
        deadline_epoch: Option<u64>,
    },
    /// Commit an off-chain rollout batch root and reward budget.
    CommitRollout {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        batch_id: String,
        #[arg(long)]
        artifact_cid: String,
        #[arg(long)]
        artifact_blake3: String,
        #[arg(long)]
        environment_cid: String,
        #[arg(long)]
        environment_blake3: String,
        #[arg(long)]
        rollout_root: String,
        #[arg(long)]
        metrics_root: String,
        #[arg(long)]
        policy_digest: String,
        #[arg(long)]
        sample_count: u64,
        #[arg(long)]
        total_reward: u64,
        #[arg(long)]
        committed_by_did: String,
        #[arg(long)]
        committed_at_epoch: u64,
        #[arg(long, default_value = "coordinator_signed")]
        verifier_mode: String,
        #[arg(long, default_value_t = 1)]
        policy_version: u32,
    },
    /// Submit a signed reward attestation for a rollout batch.
    AttestRewards {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        batch_id: String,
        #[arg(long)]
        attestation_id: String,
        #[arg(long)]
        verifier_did: String,
        #[arg(long)]
        rewards_json: String,
        #[arg(long)]
        artifact_cid: String,
        #[arg(long)]
        artifact_blake3: String,
        #[arg(long, default_value_t = 1)]
        policy_version: u32,
        #[arg(long)]
        attested_at_epoch: u64,
    },
    /// Publish a model weight root and artifact commitment.
    PublishWeights {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        model_root: String,
        #[arg(long)]
        artifact_cid: String,
        #[arg(long)]
        artifact_blake3: String,
        #[arg(long)]
        publisher_did: String,
        #[arg(long)]
        previous_root: Option<String>,
        #[arg(long)]
        rollout_batch_id: Option<String>,
        #[arg(long)]
        published_at_epoch: u64,
    },
    /// Record slash evidence and apply a slash amount.
    Slash {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        slash_id: String,
        #[arg(long)]
        offender_did: String,
        #[arg(long)]
        reporter_did: String,
        #[arg(long)]
        reason: String,
        #[arg(long)]
        evidence_cid: String,
        #[arg(long)]
        evidence_blake3: String,
        #[arg(long)]
        amount: u64,
    },
    /// Close or cancel a training run.
    Close {
        #[arg(long)]
        run_id: String,
        #[arg(long)]
        reason: String,
        #[arg(long)]
        closed_at_epoch: Option<u64>,
    },
    /// Inspect live Crucible state through RPC.
    Inspect {
        #[arg(long)]
        run_id: Option<String>,
        #[arg(long)]
        batch_id: Option<String>,
        #[arg(long)]
        model_root: Option<String>,
        #[arg(long, default_value_t = false)]
        rewards: bool,
        #[arg(long, default_value_t = false)]
        slashes: bool,
        #[arg(long, default_value_t = false)]
        events: bool,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum NftCommands {
    // -- Transaction commands --
    /// Create a new NFT collection on-chain.
    CreateCollection {
        /// Unique collection identifier (e.g. "my-badges").
        #[arg(long)]
        id: String,
        /// Human-readable collection name.
        #[arg(long)]
        name: String,
        /// Short ticker symbol (e.g. "BADGE").
        #[arg(long, default_value = "NFT")]
        symbol: String,
        /// Collection kind: "standard" or "identity".
        #[arg(long, default_value = "standard")]
        kind: String,
        /// Issuer DID (must match the wallet's active DID).
        #[arg(long)]
        issuer_did: String,
        /// Controller DID (may differ from issuer).
        #[arg(long)]
        controller_did: Option<String>,
        /// Start tokens locked by default (soulbound).
        #[arg(long, default_value_t = false)]
        default_locked: bool,
        /// Allow metadata updates after mint.
        #[arg(long, default_value_t = false)]
        allow_metadata_updates: bool,
        /// Optional collection-level metadata URI.
        #[arg(long)]
        metadata_uri: Option<String>,
    },

    /// Mint a new NFT token into an existing collection.
    Mint {
        /// Collection ID to mint into.
        #[arg(long)]
        collection: String,
        /// Token ID to assign (decimal u128).
        #[arg(long)]
        token_id: String,
        /// Recipient DID (owner of the new token).
        #[arg(long)]
        owner: String,
        /// Per-token metadata URI.
        #[arg(long)]
        metadata_uri: Option<String>,
        /// BLAKE3 metadata hash (hex).
        #[arg(long)]
        metadata_hash: Option<String>,
        /// Override collection default_locked for this token.
        #[arg(long)]
        locked: Option<bool>,
        /// DID of the identity subject (identity collections only).
        #[arg(long)]
        identity_subject: Option<String>,
        /// Identity kind: agent | human | mhr | enr | ao | app.
        #[arg(long)]
        identity_kind: Option<String>,
        /// Root anchor DID (identity collections only).
        #[arg(long)]
        identity_root: Option<String>,
        /// Root kind: hmr | mhr | enr.
        #[arg(long)]
        root_kind: Option<String>,
    },

    /// Transfer an NFT token to a new owner.
    Transfer {
        /// Collection ID containing the token.
        #[arg(long)]
        collection: String,
        /// Token ID to transfer (decimal u128).
        #[arg(long)]
        token_id: String,
        /// Recipient DID.
        #[arg(long)]
        to: String,
    },

    /// Burn (destroy) an NFT token.
    Burn {
        /// Collection ID containing the token.
        #[arg(long)]
        collection: String,
        /// Token ID to burn (decimal u128).
        #[arg(long)]
        token_id: String,
    },

    /// Update the metadata URI and/or hash of an NFT (ERC-4906).
    SetMetadata {
        /// Collection ID containing the token.
        #[arg(long)]
        collection: String,
        /// Token ID whose metadata to update (decimal u128).
        #[arg(long)]
        token_id: String,
        /// New metadata URI.
        #[arg(long)]
        uri: Option<String>,
        /// New metadata hash (BLAKE3 hex).
        #[arg(long)]
        hash: Option<String>,
    },

    /// Advance the verification level on an identity NFT.
    VerifyIdentity {
        /// Collection ID containing the identity token.
        #[arg(long)]
        collection: String,
        /// Token ID (decimal u128).
        #[arg(long)]
        token_id: String,
        /// New verification level (0-255; must be >= current).
        #[arg(long)]
        level: u8,
        /// Optional human-readable verification note.
        #[arg(long)]
        note: Option<String>,
    },

    // -- Query commands --
    /// Fetch an NFT collection record.
    GetCollection {
        /// Collection ID to look up.
        collection_id: String,
    },

    /// Fetch a single NFT token.
    GetToken {
        /// Collection ID.
        collection: String,
        /// Token ID (decimal u128).
        token_id: String,
    },

    /// List all NFTs owned by a DID.
    Owner {
        /// Owner DID.
        did: String,
        /// Maximum number of results (default: 50).
        #[arg(long, default_value_t = 50)]
        limit: usize,
        /// Result offset for pagination (default: 0).
        #[arg(long, default_value_t = 0)]
        offset: usize,
    },

    /// Fetch the DID-identity index for a subject DID.
    Did {
        /// Subject DID.
        subject_did: String,
    },

    /// List NFT lifecycle events.
    Events {
        /// Filter by collection ID.
        #[arg(long)]
        collection: Option<String>,
        /// Filter by owner DID (matches from_did or to_did).
        #[arg(long)]
        owner: Option<String>,
        /// Filter by event kind (mint | transfer | burn | metadata_update |
        /// locked | unlocked | identity_verified).
        #[arg(long)]
        kind: Option<String>,
        /// Maximum number of events to return (default: 50).
        #[arg(long, default_value_t = 50)]
        limit: usize,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum DexCommands {
    /// Create a constant-product pool with initial liquidity.
    CreatePool {
        #[arg(long)]
        asset_a: String,
        #[arg(long)]
        asset_b: String,
        #[arg(long)]
        amount_a: u64,
        #[arg(long)]
        amount_b: u64,
        #[arg(long, default_value_t = 30)]
        fee_bps: u16,
        #[arg(long, default_value_t = 1)]
        min_lp_shares: u64,
        #[arg(long)]
        expiration_height: Option<u64>,
    },
    /// Quote a swap without submitting a transaction.
    Quote {
        #[arg(long)]
        pool: String,
        #[arg(long)]
        asset_in: String,
        #[arg(long)]
        amount_in: u64,
    },
    /// Swap an exact input amount through a pool.
    SwapExactIn {
        #[arg(long)]
        pool: String,
        #[arg(long)]
        asset_in: String,
        #[arg(long)]
        amount_in: u64,
        #[arg(long)]
        min_out: u64,
        #[arg(long)]
        recipient: String,
        #[arg(long)]
        expiration_height: Option<u64>,
    },
    /// Add proportional liquidity to an existing pool.
    AddLiquidity {
        #[arg(long)]
        pool: String,
        #[arg(long)]
        amount_a: u64,
        #[arg(long)]
        amount_b: u64,
        #[arg(long)]
        min_a: u64,
        #[arg(long)]
        min_b: u64,
        #[arg(long, default_value_t = 1)]
        min_lp_shares: u64,
        #[arg(long)]
        expiration_height: Option<u64>,
    },
    /// Remove liquidity from a pool.
    RemoveLiquidity {
        #[arg(long)]
        pool: String,
        #[arg(long)]
        lp_shares: u64,
        #[arg(long)]
        min_a: u64,
        #[arg(long)]
        min_b: u64,
        #[arg(long)]
        recipient: String,
        #[arg(long)]
        expiration_height: Option<u64>,
    },
    /// Inspect an LP position.
    Position {
        #[arg(long)]
        owner: String,
        #[arg(long)]
        pool: Option<String>,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum TokenCommands {
    /// Read a launch-live custom token class.
    Class {
        #[arg(long)]
        token_id: String,
    },
    /// Read a launch-live custom token balance for one DID.
    Balance {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        owner_did: String,
    },
    /// Create a launch-live custom token class.
    CreateClass {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        ticker: String,
        #[arg(long)]
        decimals: u8,
        #[arg(long)]
        issuer_did: String,
        #[arg(long)]
        controller_did: Option<String>,
        #[arg(long)]
        max_supply: Option<u128>,
        #[arg(long)]
        metadata_uri: Option<String>,
    },
    /// Mint custom-token units to a DID.
    Mint {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        recipient_did: String,
        #[arg(long)]
        amount: u128,
    },
    /// Transfer custom-token units.
    Transfer {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        recipient_did: String,
        #[arg(long)]
        amount: u128,
        #[arg(long)]
        memo: Option<String>,
    },
    /// Burn custom-token units from an owner account.
    Burn {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        owner_did: String,
        #[arg(long)]
        amount: u128,
    },
    /// Update the controlled supply policy for a custom token.
    SetPolicy {
        #[arg(long)]
        token_id: String,
        #[arg(long)]
        max_supply: Option<u128>,
    },
}

#[derive(Debug, Clone, Subcommand)]
pub enum NovaCommands {
    /// Create a new Nova world with a JSON config.
    CreateWorld {
        #[arg(long)]
        name: String,
        /// Inline JSON or a path to a JSON file.
        #[arg(long)]
        config_json: String,
    },
    /// Inspect a Nova world or list worlds when no world id is provided.
    World {
        #[arg(long)]
        world_id: Option<String>,
    },
    /// Claim a parcel in a Nova world.
    ClaimParcel {
        #[arg(long)]
        world_id: String,
        #[arg(long, allow_hyphen_values = true)]
        region_x: i32,
        #[arg(long, allow_hyphen_values = true)]
        region_z: i32,
        #[arg(long)]
        local_x: u16,
        #[arg(long)]
        local_z: u16,
        #[arg(long, default_value = "residential")]
        parcel_type: String,
    },
    /// Transfer a parcel to another DID.
    TransferParcel {
        #[arg(long)]
        world_id: String,
        #[arg(long, allow_hyphen_values = true)]
        region_x: i32,
        #[arg(long, allow_hyphen_values = true)]
        region_z: i32,
        #[arg(long)]
        local_x: u16,
        #[arg(long)]
        local_z: u16,
        #[arg(long)]
        to_did: String,
    },
    /// Register a building placement on a Nova parcel.
    RegisterBuilding {
        #[arg(long)]
        world_id: String,
        #[arg(long, allow_hyphen_values = true)]
        region_x: i32,
        #[arg(long, allow_hyphen_values = true)]
        region_z: i32,
        #[arg(long)]
        local_x: u16,
        #[arg(long)]
        local_z: u16,
        #[arg(long)]
        asset_did: String,
        #[arg(long)]
        polycount: u32,
        #[arg(long)]
        building_id: Option<String>,
    },
    /// Register an avatar profile in a Nova world.
    RegisterAvatar {
        #[arg(long)]
        world_id: String,
        #[arg(long)]
        avatar_asset_did: Option<String>,
    },
    /// Open an auction for a seller-owned parcel.
    AuctionCreate {
        #[arg(long)]
        world_id: String,
        #[arg(long, allow_hyphen_values = true)]
        region_x: i32,
        #[arg(long, allow_hyphen_values = true)]
        region_z: i32,
        #[arg(long)]
        local_x: u16,
        #[arg(long)]
        local_z: u16,
        #[arg(long)]
        reserve_amount: u64,
        #[arg(long)]
        closes_at_height: u64,
    },
    /// Inspect an auction record.
    AuctionInspect {
        #[arg(long)]
        auction_id: String,
    },
    /// Bid on a Nova auction.
    AuctionBid {
        #[arg(long)]
        auction_id: String,
        #[arg(long)]
        amount: u64,
    },
    /// Settle a closed Nova auction.
    AuctionSettle {
        #[arg(long)]
        auction_id: String,
    },
    /// Set zone permissions.
    SetZonePermissions {
        #[arg(long)]
        zone_id: String,
        #[arg(long, default_value = "public")]
        enter: String,
        #[arg(long, default_value = "public")]
        interact: String,
        #[arg(long, default_value = "owner")]
        build: String,
    },
}

#[cfg(feature = "compute")]
#[derive(Debug, Clone, Subcommand)]
pub enum ComputeCommands {
    /// Register as a compute provider.
    RegisterProvider {
        /// Stake tier: "consumer", "professional", "enterprise", "cluster".
        #[arg(long)]
        tier: String,
    },
    /// List all registered compute providers.
    ListProviders,
    /// Select a provider for a model and verification tier.
    SelectProvider {
        #[arg(long)]
        model_id: String,
        #[arg(long)]
        verification_tier: String,
    },
    /// Create a compute job through the canonical dispatch_compute flow.
    CreateJob {
        #[arg(long)]
        contract_did: String,
        #[arg(long)]
        model_id: String,
        #[arg(long)]
        input_commitment: String,
        #[arg(long)]
        max_cost: u64,
        #[arg(long)]
        verification_tier: String,
        #[arg(long)]
        mandate_id: String,
    },
    /// Fund compute escrow.
    FundEscrow {
        #[arg(long)]
        owner_did: String,
        #[arg(long)]
        amount: u64,
        #[arg(long)]
        mandate_id: Option<String>,
        #[arg(long)]
        budget_limit: Option<u64>,
    },
    /// Withdraw available compute escrow.
    WithdrawEscrow {
        #[arg(long)]
        owner_did: String,
        #[arg(long)]
        amount: u64,
    },
    /// Inspect compute escrow.
    Escrow {
        #[arg(long)]
        owner_did: String,
    },
    /// Inspect or submit compute receipts.
    Receipt {
        #[command(subcommand)]
        cmd: ComputeReceiptCommands,
    },
    /// Inspect or resolve compute challenges.
    Challenge {
        #[command(subcommand)]
        cmd: ComputeChallengeCommands,
    },
    /// Inspect MACA compute epochs and quorum proofs.
    Maca {
        #[command(subcommand)]
        cmd: ComputeMacaCommands,
    },
    /// Show accumulated compute earnings.
    Earnings,
    /// Attest local hardware for compute marketplace.
    AttestHardware,
}

#[derive(Debug, Clone, Subcommand)]
pub enum StorageCommands {
    /// Register as a Weave/Weft storage provider.
    RegisterProvider {
        #[arg(long)]
        provider_did: String,
        #[arg(long)]
        capacity_gib: u64,
        #[arg(long, value_delimiter = ',')]
        regions: Vec<String>,
        #[arg(long)]
        price_per_gib_epoch: u64,
        #[arg(long, default_value_t = 0)]
        retrieval_price_per_gib: u64,
        #[arg(long)]
        replication_guarantee: u16,
        #[arg(long)]
        stake: u64,
        #[arg(long)]
        provider_pubkey_hex: String,
    },
    /// Update provider capacity, pricing, regions, or signing key.
    UpdateProvider {
        #[arg(long)]
        provider_did: String,
        #[arg(long)]
        capacity_gib: Option<u64>,
        #[arg(long, value_delimiter = ',')]
        regions: Option<Vec<String>>,
        #[arg(long)]
        price_per_gib_epoch: Option<u64>,
        #[arg(long)]
        retrieval_price_per_gib: Option<u64>,
        #[arg(long)]
        replication_guarantee: Option<u16>,
        #[arg(long)]
        provider_pubkey_hex: Option<String>,
    },
    /// Begin provider exit.
    ExitProvider {
        #[arg(long)]
        provider_did: String,
    },
    /// Request replicated pinning for an artifact commitment.
    RequestPin {
        #[arg(long)]
        owner_did: String,
        #[arg(long)]
        artifact_json: String,
        #[arg(long)]
        duration_epochs: u64,
        #[arg(long)]
        replication_factor: u16,
        #[arg(long)]
        max_price_per_gib_epoch: u64,
        #[arg(long)]
        escrowed_amount: u64,
        #[arg(long)]
        expires_at_height: Option<u64>,
    },
    /// Accept a pin request as a registered provider.
    AcceptPin {
        #[arg(long)]
        request_id: String,
        #[arg(long)]
        provider_did: String,
        #[arg(long)]
        accepted_price_per_gib_epoch: u64,
    },
    /// Settle a provider's signed pin receipt.
    SettleReceipt {
        #[arg(long)]
        receipt_json: String,
    },
    /// Open a proof-of-possession challenge.
    Challenge {
        #[arg(long)]
        contract_id: String,
        #[arg(long)]
        challenger_did: String,
        #[arg(long, value_delimiter = ',')]
        sample_indices: Vec<u64>,
        #[arg(long)]
        response_window_blocks: u64,
    },
    /// Resolve a challenge with sampled Weft chunk proofs.
    ResolveChallenge {
        #[arg(long)]
        challenge_id: String,
        #[arg(long)]
        proof_json: String,
    },
    /// List storage providers.
    ListProviders,
    /// Inspect a storage provider.
    Provider {
        #[arg(long)]
        provider_did: String,
    },
    /// Inspect a storage pin request.
    PinRequest {
        #[arg(long)]
        request_id: String,
    },
    /// Inspect a storage pin contract.
    Contract {
        #[arg(long)]
        contract_id: String,
    },
    /// Inspect a storage pin receipt.
    Receipt {
        #[arg(long)]
        receipt_id: String,
    },
    /// Inspect a storage challenge.
    ChallengeStatus {
        #[arg(long)]
        challenge_id: String,
    },
}

#[cfg(feature = "compute")]
#[derive(Debug, Clone, Subcommand)]
pub enum ComputeReceiptCommands {
    /// Submit a provider-signed receipt for deterministic settlement.
    Settle {
        #[arg(long)]
        receipt_json: String,
    },
    /// Fetch a settled compute receipt.
    Get {
        #[arg(long)]
        receipt_id: String,
    },
    /// Fetch compute proof metadata for a receipt.
    Proof {
        #[arg(long)]
        receipt_id: String,
    },
}

#[cfg(feature = "compute")]
#[derive(Debug, Clone, Subcommand)]
pub enum ComputeChallengeCommands {
    /// Open a challenge against a compute receipt.
    Open {
        #[arg(long)]
        receipt_id: String,
        #[arg(long)]
        challenger_did: String,
        #[arg(long)]
        evidence_json: String,
        #[arg(long)]
        deposit: Option<u64>,
    },
    /// Resolve an open challenge.
    Resolve {
        #[arg(long)]
        challenge_id: String,
        #[arg(long)]
        resolution_json: String,
    },
    /// Fetch one challenge.
    Get {
        #[arg(long)]
        challenge_id: String,
    },
    /// List challenges for a receipt.
    List {
        #[arg(long)]
        receipt_id: String,
    },
}

#[cfg(feature = "compute")]
#[derive(Debug, Clone, Subcommand)]
pub enum ComputeMacaCommands {
    /// Fetch a MACA epoch.
    Epoch {
        #[arg(long)]
        epoch_id: u64,
    },
    /// List MACA epochs.
    Epochs,
    /// Fetch a MACA quorum proof.
    QuorumProof {
        #[arg(long)]
        epoch_id: u64,
        #[arg(long)]
        work_id: String,
    },
    /// List MACA quorum proofs for an epoch.
    QuorumProofs {
        #[arg(long)]
        epoch_id: u64,
    },
}

#[derive(Debug, Error)]
pub enum CliError {
    #[error("rpc: {0}")]
    Rpc(String),
    #[error("http: {0}")]
    Http(#[from] reqwest::Error),
    #[error("json: {0}")]
    Json(#[from] serde_json::Error),
    #[error("invalid signing key: {0}")]
    SigningKey(String),
    #[error("unsupported command: {0}")]
    Unsupported(String),
    #[error("transaction: {0}")]
    Transaction(String),
}

pub trait RpcTransport {
    fn call(&self, method: &str, params: Value) -> Result<Value, CliError>;
}

#[derive(Debug, Clone)]
pub struct RpcClient {

}

pub fn new(endpoint: impl Into<String>) -> Result<Self, CliError>;

pub fn normalize_rpc_url(mut endpoint: String) -> String;

pub fn run_cli(cli: Cli) -> Result<Value, CliError>;

pub fn execute_cli(cli: Cli) -> Result<Value, CliError>;

pub fn dispatch_command(cli: &Cli, rpc: &dyn RpcTransport) -> Result<Value, CliError>;

pub fn run_cli_with_rpc(cli: &Cli, rpc: &dyn RpcTransport) -> Result<Value, CliError>;