> ## Documentation Index > Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt > Use this file to discover all available pages before exploring further. # cowboy relay > Register CBFS relay nodes and RAS owner delegations ## Synopsis ```bash theme={"system"} cowboy relay [--rpc-url ] cowboy relay register-delegation --delegation-key [--scopes ] [--service-class ] [--valid-epochs ] [--private-key ] [--nonce ] cowboy relay register --node-id --relay-identity-key --delegation-key --endpoint --capacity-bytes [--region ] [--valid-epochs ] [--private-key ] [--nonce ] ``` `cowboy relay` registers CBFS relay nodes in the Relay Registry system actor (`0x0B`) defined by [CIP-9](https://docs.cowboy.inc/cips/cip-9-runner-storage.md) (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](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md), with limits from the node's `POST /estimate_gas`. **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`) | ## 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:** | Flag | Default | Description | | - | - | - | | `--private-key` | Auto-discovered | Operator wallet key file (global flag) | | `--delegation-key` | Required | Delegated ed25519 secret key (file path or 64-char hex) | | `--scopes` | `cbfs,REGISTER_RELAY` | Comma-separated delegation scopes | | `--service-class` | `mount-capable-v1` | `mount-capable-v1` or `non-mount-service-v1` | | `--valid-epochs` | `60` | Storage-epoch validity window | | `--nonce` | `0` (auto-fetch) | Transaction nonce | **Example:** ```bash theme={"system"} $ cowboy relay register-delegation --delegation-key ./relay-delegation.key Registering RAS owner delegation... Operator address: 0x7a3B...F92E Delegated pubkey: 0x4c1d... Scopes: cbfs,REGISTER_RELAY Service class: MountCapableV1 Chain: id=... network=... Delegation epoch window: [12, 72] Nonce: 7 Transaction hash: 0xabc123... Owner-delegation registration transaction submitted successfully. ``` *** ### `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:** | Flag | Default | Description | | - | - | - | | `--private-key` | Auto-discovered | Operator wallet key file (global flag); becomes the relay's `owner_address` | | `--node-id` | Required | Relay node id, 32-byte hex | | `--relay-identity-key` | Required | Relay identity ed25519 secret key (file path or 64-char hex) | | `--delegation-key` | Required | Owner-delegation ed25519 secret key registered via `register-delegation` | | `--endpoint` | Required | Public endpoint URL the relay serves | | `--capacity-bytes` | Required | Advertised relay capacity, in bytes | | `--region` | None | Region hint (e.g. `na-east`) | | `--valid-epochs` | `30` | Storage-epoch validity window for the authorizations | | `--nonce` | `0` (auto-fetch) | Transaction nonce | **Example:** ```bash theme={"system"} $ cowboy relay register \ --node-id 0x1f2e... \ --relay-identity-key ./relay-identity.key \ --delegation-key ./relay-delegation.key \ --endpoint https://relay-01.example.com \ --capacity-bytes 1099511627776 --region na-east Registering CBFS relay... Operator address: 0x7a3B...F92E Node id: 0x1f2e... Relay identity pubkey: 0x88aa... Owner delegation pubkey: 0x4c1d... Authorization epoch window: [12, 42] Endpoint: https://relay-01.example.com Capacity: 1099511627776 bytes Region: na-east Nonce: 8 Transaction hash: 0xdef789... Submitting relay registration to http://localhost:4000... Relay registration transaction submitted successfully. ``` ## 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`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.