Skip to main content

​
Synopsis

cowboy relay registers CBFS relay nodes in the Relay Registry system actor (0x0B) defined by CIP-9 (Runner Attached Storage). Registration is owner-authorized: the operator wallet first registers an ed25519 owner delegation, and that delegated key then co-signs the relay registration. Both subcommands sign with the operator wallet found by key auto-discovery, with limits from the node’s POST /estimate_gas. Global flags:

​
Subcommands

​
cowboy relay register-delegation

Register a RasOwnerDelegation binding an ed25519 delegation key to the operator wallet. Run this before relay register. Behavior:
  1. Load the operator wallet and the ed25519 delegation key (a file path, or 64 hex chars inline).
  2. Fetch the chain id and network name, and the current storage epoch (the /health/detailed height over the /chain-info storage epoch length); the delegation is valid from that epoch through current + valid_epochs (minimum window 1).
  3. Sign the delegation hash with the wallet (recoverable secp256k1) and wrap it in a Ras system instruction.
  4. Print the operator address, delegated pubkey, scopes, service class, chain, epoch window, nonce, and transaction hash.
  5. Submit via the node’s general POST /submit endpoint (there is no dedicated route).
Flags: Example:

​
cowboy relay register

Register a CBFS relay into the 0x0B relay registry via a RegisterRelay RAS transaction. Behavior:
  1. Load the operator wallet, the relay identity ed25519 key, and the owner-delegation ed25519 key.
  2. Fetch the current storage epoch; authorizations are valid from it through current + valid_epochs. This must not exceed the on-chain delegation’s own valid_until_epoch.
  3. Build RegisterRelay with two authorizations over the same payload hash: one signed by the relay identity key (proving control of the node id) and one signed by the delegation key (owner authorization). Both carry random 16-byte nonces.
  4. Read the stake top-up the registration debits (the governed cbfs.min_relay_stake from GET /fees/pricing, less any stake this node id already holds), sign the transaction with the wallet, and POST /ras/relays/register.
  5. Print the operator address, node id, both public keys, epoch window, endpoint, capacity, region, nonce, and transaction hash, then a reminder to verify the relay in the registry after inclusion.
Re-registering a node id that is already in the registry, for example to re-activate a relay after it was disabled, needs authorizations that start after the relay’s last change: the chain refuses either authorization when its valid_from_epoch is not later than the row’s updated_epoch. A captured registration therefore cannot be resubmitted by anyone to re-activate an exited relay, cancel a pending unstake, or debit the owner’s stake again. Because the CLI starts the window at the current storage epoch, a relay that changed during the current epoch can be re-registered from the next one. Flags: Example:

​
Edge Cases

  • register requires the delegation key to already be registered on chain with scopes covering both cbfs and REGISTER_RELAY (or *); the executor rejects the registration otherwise.
  • Ed25519 keys are accepted as a file containing a 64-hex-char secret, or the secret inline; an inline secret is refused on a terminal and in non-interactive mode.
  • --node-id must be exactly 64 hex characters (32 bytes, 0x optional).
  • The epoch window is stamped from the node’s own block height, not a local clock; register-delegation defaults to a longer window (60) than register (30) so the delegation outlives the authorizations it bounds.
  • register posts to /ras/relays/register; register-delegation posts to /submit.