Skip to main content

​
Synopsis

cowboy session drives the on-chain CIP-8 Session actor (0x0C): a payer escrows CBY against a runner, the runner is paid by cumulative off-chain vouchers, and unspent deposit is refunded after a dispute window. Write subcommands sign with the key found by key auto-discovery. Each signs with a 500,000 cycle / 100,000 cell limit and the protocol default access limit, prints the transaction hash, and submits via POST /submit. Without --json a write returns on acceptance; with --json it waits up to 90 seconds for the transaction to commit and reports it only once committed (transaction_failed if it commits unsuccessfully, receipt_pending if it does not commit in time). Parent flags:

​
Subcommands

​
cowboy session models

List the models active inference runners serve, with how many runners serve each (* is a runner that serves any model). Counts only runners that run llm jobs, advertise the inference entitlement, and have a route-serving endpoint. Read-only; no private key. Flags:

​
cowboy session open

Open a new session, escrowing max_amount from the payer: for a model the chain assigns a runner to (--model, the usual way), or, as an advanced option, against a runner you name (--runner). Exactly one of --model and --runner is required. Behavior:
  1. Load the payer key and derive the payer address.
  2. With --model: default --expires-at to the current height plus 2,592,000 blocks (30 days of 1-second blocks), default the session id to 32 random bytes, and submit SessionOpenAssigned; the chain assigns the runner when the transaction commits.
  3. With --runner: compute the session id as --session-id if given, otherwise keccak256(payer || runner || nonce || expires_at) using the --nonce value as passed (before auto-fetch), and submit SessionOpen. The runner must be registered and not the payer, but need not serve a model.
  4. Both use asset CBY, the given max_amount, and the price-advert digest (all zeros if omitted).
  5. Print session_id, payer, then runner (with --runner) or model, any exclude and signer (with --model), then max_amount and expires_at. With --json, wait for commit and report the session id, assigned runner, its endpoint, deposit, expiry, and transaction hash.
Flags: Example:

​
cowboy session voucher

Sign a voucher with the global --private-key and print it as JSON; nothing is sent. The output (or the voucher object of --json) is what settle --voucher accepts. Flags:

​
cowboy session deposit

Top up an open session. Flags:

​
cowboy session settle

Submit SessionSettle with a voucher the session’s signer signed elsewhere (--voucher), or sign one here with --signer-key. Behavior:
  1. With --voucher: parse the voucher object (inline JSON or @FILE, at most 64 KiB), check it matches --session-id if given, and sign the transaction with the global --private-key.
  2. Otherwise: load the signer key (--signer-key) and, if given, a separate submitter key (--private-key); the submitter defaults to the signer. Sign the voucher’s EIP-712 digest with the signer key over the Session actor domain.
  3. Read the session and check the voucher recovers to the session’s signer (its payer, unless opened with --signer) before anything is submitted.
  4. Submit SessionSettle { session_id, voucher } signed by the submitter.
  5. Print session_id, signer (voucher signer), submitter (tx signer), and the voucher’s nonce, cumulative amount, and expiry.
Flags:

​
cowboy session close

Payer-initiated close; the session enters its dispute window. Flags:

​
cowboy session finalize

Refund the unspent deposit after the dispute window expires. Flags:

​
cowboy session get

Read on-chain session state by id. Read-only; no private key. Behavior:
  1. Compute the session storage key and GET /actors/<session actor>/storage/value?key=<key>.
  2. A key the node does not hold fails with session_not_found; a node without the route fails with rpc_failed; a native route session’s record fails with session_unsupported.
  3. Otherwise print session_id, payer, signer, runner, deposit, spent, max_amount, opened_at_block, expires_at_block, last_voucher_nonce, and status (Open, Closing (closed_at=N), Disputed, Settled, or Refunded), followed by the runner’s endpoint when it has one.
Flags:

​
Edge Cases

  • Amounts are in CBY wei (1 CBY = 10^9 wei), not CBY.
  • With --nonce 0 the transaction nonce is fetched from the account; the derived session id for open --runner still uses the literal 0, so pass --session-id to control it explicitly.
  • settle lets a different account submit the transaction than the one that signed the voucher; the voucher signature is always the session signer’s (the payer, or the sponsor open --signer named), and a voucher signed by any other key is refused before submission.
  • get fails when the session is not on chain or the node does not serve actor storage reads.