cowboy trading-post

Synopsis

cowboy trading-post [--rpc-url <url>] [--private-key <path>] <subcommand>

# Declarations and versions
cowboy trading-post declaration-id --creator <address> --actor <address> --salt <hex>
cowboy trading-post declare [--prepare] --actor <address> --salt <hex> --manifest-root <hex> --code-visibility <public|private> --volume-id <hex> --claimed-root <hex> [flags]
cowboy trading-post version [--prepare] --declaration-id <hex> --manifest-root <hex> --code-visibility <public|private> --volume-id <hex> --claimed-root <hex> [flags]
cowboy trading-post retire --declaration-id <hex>

# Stores, grants, artifacts
cowboy trading-post register-store [--prepare] (--metadata <str> | --metadata-hex <hex> | --metadata-file <path>)
cowboy trading-post grant [--prepare] --declaration-id <hex> --store-id <n> --lease-epoch-blocks <n> [--split <address>:<bps>]... [--max-referral-bps <n>]
cowboy trading-post revoke-grant --grant-id <n>
cowboy trading-post register-artifact [--prepare] --store-id <n> --declaration-id <hex> --version <n> --volume-id <hex> --claimed-root <hex> [--ibe-ciphertext-hex <hex> | --ibe-ciphertext-file <path>]
cowboy trading-post retire-artifact --declaration-id <hex> --version <n> --artifact-id <n>

# Hires
cowboy trading-post hire --declaration-id <hex> --term <spec> --amount <n> [--version <n>] [--grant-id <n>] [--referral <address>:<bps>] [--asset cby|cip20] [--token-id <hex>]
cowboy trading-post deposit --hire-id <n> --amount <n> [--asset cby|cip20] [--token-id <hex>]
cowboy trading-post withdraw --hire-id <n>
cowboy trading-post renew --hire-id <n>
cowboy trading-post set-renewal --hire-id <n> (--on | --off)
cowboy trading-post pause [--prepare] --hire-id <n>
cowboy trading-post resume [--prepare] --hire-id <n>
cowboy trading-post revoke [--prepare] --hire-id <n>
cowboy trading-post settle --hire-id <n> (--session-receipt-hex <hex> | --session-receipt-file <path>)

# Attestation
cowboy trading-post attest [--prepare] --manifest-root <hex> --verdict <approved|rejected|flagged> [--policy-uri <str> | --policy-uri-hex <hex> | --policy-uri-file <path>]

# Reads
cowboy trading-post get-declaration --declaration-id <hex>
cowboy trading-post get-version --declaration-id <hex> --version <n>
cowboy trading-post get-store --store-id <n>
cowboy trading-post get-store-artifacts --store-id <n>
cowboy trading-post get-grant --store-id <n> --declaration-id <hex>
cowboy trading-post get-hire --hire-id <n>
cowboy trading-post get-hirer-hires --hirer <address>
cowboy trading-post get-attestations --manifest-root <hex>
cowboy trading-post get-lease-authorize --runner <address> --job <hex> --hire <n>

cowboy trading-post drives the CIP-33 Trading Post: creators declare actors hireable with pricing terms, stores distribute them under grants, hirers pay in CBY or CIP-20 tokens, and attesters vouch for manifest roots. Write subcommands sign with the key found by key auto-discovery, with limits from the node’s estimate, and print the transaction hash and the node response. declaration-id and the get-* subcommands need no key. declare, version, register-store, grant, register-artifact, pause, resume, revoke and attest accept --prepare: sign the transaction and print it as one JSON object (transaction_hex, digest, sender, nonce, chain_id) without submitting it. Global flags:

Flag	Default	Description
`--rpc-url`	Auto-discovered	RPC URL (`--rpc-url`, then `COWBOY_RPC_URL`, then `.cowboy/config.json`, then `http://localhost:4000`)
`--private-key`	Auto-discovered	Private key file path, or set `COWBOY_PRIVATE_KEY`

Shared argument formats

32-byte hex (--salt, --manifest-root, --volume-id, --claimed-root, --declaration-id, --token-id, --job): 64 hex chars, 0x optional.
Pricing term (--term): free, one-shot:cby:<amount>, subscription:cby:<amount>:<period_blocks>, per-call:cby:<amount>, or the CIP-20 forms one-shot:cip20:<token_id>:<base_units>, subscription:cip20:<token_id>:<base_units>:<period_blocks>, per-call:cip20:<token_id>:<base_units>.
CBY amounts accept up to 9 decimal places (1.5 = 1,500,000,000 base units); CIP-20 amounts are raw base units and must not contain a decimal point.
Split / referral entries: <address>:<bps>.
Bytes inputs (--capability-schema-*, --ibe-ciphertext-*, --metadata*, --policy-uri*, --session-receipt-*): give at most one of the -hex, -file, or plain-text forms.

Subcommands

`cowboy trading-post declaration-id`

Compute the deterministic declaration id for a creator, actor, and salt. Local only; no network call. Flags:

Flag	Default	Description
`--creator`	Required	Creator address that will sign the declaration
`--actor`	Required	Actor address being declared
`--salt`	Required	32-byte declaration salt, hex

Example:

$ cowboy trading-post declaration-id --creator 0x7a3B...F92E --actor 0x9c0D...E1F2 --salt 0x00..01
Declaration ID: 0x5d2a...

`cowboy trading-post declare`

Declare a hireable actor and its first version and artifact. Behavior:

Derive the creator from the signing key and compute the declaration id; print it (unless --prepare).
Build the version fields (manifest root, visibility, capability schema, terms, default split) and the artifact escrow (volume, claimed root, IBE ciphertext).
Enforce the visibility pairing locally: private requires an IBE ciphertext; public requires it to be omitted. A ciphertext that is only whitespace is rejected.
Sign and submit TradingPostDeclare.

Flags:

Flag	Default	Description
`--prepare`	`false`	Sign and print the transaction without submitting it
`--actor`	Required	Actor address being declared hireable
`--salt`	Required	32-byte declaration salt, hex
`--human-hireable`	`false`	Mark the actor human-hireable
`--agent-hireable`	`false`	Mark the actor agent-hireable
`--manifest-root`	Required	32-byte manifest root, hex
`--code-visibility`	Required	`public` or `private`
`--capability-schema-hex`	None	Capability schema bytes, hex
`--capability-schema-file`	None	Capability schema bytes from a file
`--term`	None	Pricing term spec; repeatable
`--split`	None	Default split `<address>:<bps>`; repeatable
`--volume-id`	Required	CBFS volume id holding the artifact
`--claimed-root`	Required	Claimed artifact root; must match `--manifest-root`
`--ibe-ciphertext-hex`	None	Escrow IBE ciphertext, hex (required for `private`)
`--ibe-ciphertext-file`	None	Escrow IBE ciphertext from a file (required for `private`)

Example:

$ cowboy trading-post declare [--prepare] --actor 0x9c0D...E1F2 --salt 0x00..01 \
    --agent-hireable --manifest-root 0xaa.. --code-visibility public \
    --term free --term per-call:cby:0.01 \
    --volume-id 0xbb.. --claimed-root 0xaa..
Declaration ID: 0x5d2a...
Transaction hash: 0xabc123...
Trading Post command submitted: <node response>

`cowboy trading-post version`

Declare a new version and artifact for an existing declaration. Takes the same version and artifact flags as declare (--manifest-root, --code-visibility, --capability-schema-*, --term, --split, --volume-id, --claimed-root, --ibe-ciphertext-*) plus:

Flag	Default	Description
`--declaration-id`	Required	Declaration id, 32-byte hex

`cowboy trading-post retire`

Retire a declaration.

Flag	Default	Description
`--declaration-id`	Required	Declaration id, 32-byte hex

`cowboy trading-post register-store`

Flag	Default	Description
`--metadata`	None	Store metadata as UTF-8 text
`--metadata-hex`	None	Store metadata as hex
`--metadata-file`	None	Store metadata from a file

The three forms conflict; omitting all of them registers empty metadata.

`cowboy trading-post grant`

Grant a store distribution rights for a declaration.

Flag	Default	Description
`--declaration-id`	Required	Declaration id, 32-byte hex
`--store-id`	Required	Store id
`--split`	None	Split `<address>:<bps>`; repeatable
`--max-referral-bps`	`0`	Maximum referral share in basis points
`--lease-epoch-blocks`	Required	Lease epoch length in blocks

`cowboy trading-post revoke-grant`

Flag	Default	Description
`--grant-id`	Required	Grant id

`cowboy trading-post register-artifact`

Register a store artifact for an existing declaration version. The visibility pairing cannot be checked locally here (the version’s visibility lives on chain); consensus enforces it.

Flag	Default	Description
`--store-id`	Required	Store id
`--declaration-id`	Required	Declaration id, 32-byte hex
`--version`	Required	Declaration version
`--volume-id`	Required	CBFS volume id, 32-byte hex
`--claimed-root`	Required	Claimed artifact root, 32-byte hex
`--ibe-ciphertext-hex`	None	Escrow IBE ciphertext, hex
`--ibe-ciphertext-file`	None	Escrow IBE ciphertext from a file

`cowboy trading-post retire-artifact`

Flag	Default	Description
`--declaration-id`	Required	Declaration id, 32-byte hex
`--version`	Required	Declaration version
`--artifact-id`	Required	Artifact id

`cowboy trading-post hire`

Hire a declaration version. Behavior:

Parse the chosen --term spec and the payment (--asset, --amount, --token-id); print the parsed payment.
Sign and submit TradingPostHire.

Flags:

Flag	Default	Description
`--declaration-id`	Required	Declaration id, 32-byte hex
`--version`	None	Declaration version
`--grant-id`	None	Store grant to hire through
`--term`	Required	Pricing term spec chosen from the declaration’s terms
`--referral`	None	Referral `<address>:<bps>`
`--asset`	`cby`	`cby` or `cip20`
`--amount`	Required	Payment amount (CBY: up to 9 decimals; CIP-20: raw base units)
`--token-id`	None	32-byte token id; required for `--asset cip20` and rejected otherwise

Example:

$ cowboy trading-post hire --declaration-id 0x5d2a... --term per-call:cby:0.01 --amount 1.5
Payment: 1.5 CBY (1500000000 base units)
Transaction hash: 0xdef789...
Trading Post command submitted: <node response>

`cowboy trading-post deposit`

Deposit more funds into a hire.

Flag	Default	Description
`--hire-id`	Required	Hire id
`--asset`	`cby`	`cby` or `cip20`
`--amount`	Required	Payment amount
`--token-id`	None	32-byte token id; required for `--asset cip20`

`cowboy trading-post withdraw`, `renew`, `pause`, `resume`, `revoke`

Each takes a single flag:

Flag	Default	Description
`--hire-id`	Required	Hire id

withdraw returns unused prepaid funds; renew renews the hire; pause/resume toggle it; revoke ends it.

`cowboy trading-post set-renewal`

Enable or disable hire auto-renewal. Exactly one of --on or --off is required.

Flag	Default	Description
`--hire-id`	Required	Hire id
`--on`	`false`	Enable renewal. Conflicts with `--off`
`--off`	`false`	Disable renewal. Conflicts with `--on`

`cowboy trading-post settle`

Settle a per-call hire with a session receipt. The receipt is required and must be non-empty.

Flag	Default	Description
`--hire-id`	Required	Hire id
`--session-receipt-hex`	None	Receipt bytes, hex. Conflicts with `--session-receipt-file`
`--session-receipt-file`	None	Receipt bytes from a file. Conflicts with `--session-receipt-hex`

`cowboy trading-post attest`

Attest a manifest root.

Flag	Default	Description
`--manifest-root`	Required	32-byte manifest root, hex
`--verdict`	Required	`approved`, `rejected`, or `flagged`
`--policy-uri`	None	Policy URI as UTF-8 text
`--policy-uri-hex`	None	Policy URI as hex
`--policy-uri-file`	None	Policy URI from a file

Read subcommands

Each get-* subcommand issues a GET against the RPC URL and pretty-prints the JSON response. No private key is used.

Subcommand	Flags	Endpoint
`get-declaration`	`--declaration-id`	`/trading-post/declarations/0x<id>`
`get-version`	`--declaration-id`, `--version`	`/trading-post/declarations/0x<id>/versions/<n>`
`get-store`	`--store-id`	`/trading-post/stores/<id>`
`get-store-artifacts`	`--store-id`	`/trading-post/stores/<id>/artifacts`
`get-grant`	`--store-id`, `--declaration-id`	`/trading-post/grants/<store>/0x<id>`
`get-hire`	`--hire-id`	`/trading-post/hires/<id>`
`get-hirer-hires`	`--hirer`	`/trading-post/hirers/<address>/hires`
`get-attestations`	`--manifest-root`	`/trading-post/attestations/0x<root>`
`get-lease-authorize`	`--runner`, `--job`, `--hire`	`/trading-post/lease-authorize?runner=…&job=0x…&hire=…`

get-lease-authorize additionally prints allowed and reason fields before the JSON body. Example:

$ cowboy trading-post get-hire --hire-id 42
{
  "hire_id": 42,
  ...
}

Edge Cases

declare and version fail locally if --code-visibility private has no IBE ciphertext, or if public has one; register-artifact defers that check to consensus.
An IBE ciphertext consisting only of whitespace (for example a file holding a stray newline) is rejected.
--token-id with --asset cby is an error; --asset cip20 without --token-id is an error.
A CBY amount with more than 9 decimal places, or a CIP-20 amount containing a decimal point, is rejected.
set-renewal with neither or both of --on/--off is rejected before submission.
settle requires a non-empty session receipt.
A --term that does not match one of the documented formats fails with the expected format in the error.

Start Here

Build

How Cowboy Works

Reference

Synopsis

Shared argument formats

Subcommands

`cowboy trading-post declaration-id`

`cowboy trading-post declare`

`cowboy trading-post version`

`cowboy trading-post retire`

`cowboy trading-post register-store`

`cowboy trading-post grant`

`cowboy trading-post revoke-grant`

`cowboy trading-post register-artifact`

`cowboy trading-post retire-artifact`

`cowboy trading-post hire`

`cowboy trading-post deposit`

`cowboy trading-post withdraw`, `renew`, `pause`, `resume`, `revoke`

`cowboy trading-post set-renewal`

`cowboy trading-post settle`

`cowboy trading-post attest`

Read subcommands

Edge Cases

​Synopsis

​Shared argument formats

​Subcommands

​cowboy trading-post declaration-id

​cowboy trading-post declare

​cowboy trading-post version

​cowboy trading-post retire

​cowboy trading-post register-store

​cowboy trading-post grant

​cowboy trading-post revoke-grant

​cowboy trading-post register-artifact

​cowboy trading-post retire-artifact

​cowboy trading-post hire

​cowboy trading-post deposit

​cowboy trading-post withdraw, renew, pause, resume, revoke

​cowboy trading-post set-renewal

​cowboy trading-post settle

​cowboy trading-post attest

​Read subcommands

​Edge Cases

Synopsis

Shared argument formats

Subcommands

`cowboy trading-post declaration-id`

`cowboy trading-post declare`

`cowboy trading-post version`

`cowboy trading-post retire`

`cowboy trading-post register-store`

`cowboy trading-post grant`

`cowboy trading-post revoke-grant`

`cowboy trading-post register-artifact`

`cowboy trading-post retire-artifact`

`cowboy trading-post hire`

`cowboy trading-post deposit`

`cowboy trading-post withdraw`, `renew`, `pause`, `resume`, `revoke`

`cowboy trading-post set-renewal`

`cowboy trading-post settle`

`cowboy trading-post attest`

Read subcommands

Edge Cases