> ## 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 watchtower

> Manage Watchtower data feeds on the Cowboy blockchain

## Synopsis

```bash theme={null}
# Admin (one-time per chain)
cowboy watchtower init

# Publisher flows
cowboy watchtower new feed --name <s> [--description <s>] [paid-mode flags...]
cowboy watchtower feed <id> pre-wrap-epochs --from <u64> --to <u64>
cowboy watchtower feed <id> wrap-daemon --depth <u64>
cowboy watchtower feed <id> publish --kind <s> --data <json> [--tags <k=v,...>]
cowboy watchtower feed <id> rotate-publisher-key
cowboy watchtower feed <id> rewrap-epochs --from <u64> --to <u64>
cowboy watchtower feed <id> set-policy public|private-allowlist
cowboy watchtower feed <id> allowlist add|remove <address>

# Subscriber flows
cowboy watchtower feed <id> subscribe --mode push|pull|push-fallback [filter/cursor flags...]
cowboy watchtower feed <id> unsubscribe
cowboy watchtower feed <id> get-since --cursor <u64> [--limit <u32>]
cowboy watchtower feed <id> get-head
cowboy watchtower feed <id> get-key-at-sequence <u64>

# Subscriber paid-mode flows
cowboy watchtower account register-key --scheme x25519
cowboy watchtower account list-keys
cowboy watchtower account revoke-key <key_id>
cowboy watchtower feed <id> acquire-access --to-epoch <u64> --account-key-id <u64> [--beneficiary <addr>] [--payer <addr>]
cowboy watchtower feed <id> fetch-keys --account-key-id <u64> --epochs <list>
cowboy watchtower feed <id> consume --account-key-id <u64> [--cursor <u64>] [--limit <u32>]

# Discovery
cowboy watchtower list
cowboy watchtower feeds [--owner <addr>]
cowboy watchtower feed <id> info
cowboy watchtower feed <id> subscribers
```

All write commands use [key auto-discovery](/cli-specs/key-auto-discovery) for the private key.

Spec reference: [CIP-7: Watchtower (Simple Stream Protocol)](/cips/cip-7-simple-stream-protocol). The CLI shape below mirrors the full CIP-7 v1 actor + Stream Key Manager surface.

## Admin

### `cowboy watchtower init`

Deploy and initialize the `WatchtowerRegistry` actor on the chain.

**Behavior:**

1. Load the private key using [key auto-discovery](/cli-specs/key-auto-discovery).
2. Deploy the `WatchtowerRegistry` actor.
3. Store the registry address in `.cowboy/config.json`.

Admin-only, used once per chain bootstrap.

***

## Publisher

### `cowboy watchtower new feed`

Create a new feed (StreamActor) and register it in `WatchtowerRegistry`.

**Flags:**

| Flag                     | Default   | Description                                                                        |
| ------------------------ | --------- | ---------------------------------------------------------------------------------- |
| `--name`                 | required  | Feed name                                                                          |
| `--description`          | `""`      | Feed description                                                                   |
| `--access-mode`          | `open`    | `open` (plaintext) or `subscriber-paid` (CBSS-routed ciphertext)                   |
| `--fee-per-epoch-cby`    | `0`       | Per-epoch publisher fee in CBY wei. Required when `--access-mode=subscriber-paid`. |
| `--protocol-fee-bps`     | `0`       | Protocol fee in basis points (0..=5000). Credited to system Treasury 0x08.         |
| `--key-epoch-blocks`     | `600`     | Blocks per key epoch (default 10 min at 1s blocks)                                 |
| `--ring-buffer-capacity` | `10000`   | Max retained messages                                                              |
| `--max-subscribers`      | `10000`   | Subscriber cap                                                                     |
| `--publisher-treasury`   | tx signer | Where publisher revenue is credited                                                |

For `--access-mode=subscriber-paid`, the publisher must follow up with `pre-wrap-epochs` (or run `wrap-daemon`) before subscribers can acquire access.

### `cowboy watchtower feed <id> pre-wrap-epochs`

Register a batch of per-epoch wrapped content keys, ready for subscriber pickup via CBSS committee delivery.

**Flags:**

| Flag           | Description                         |
| -------------- | ----------------------------------- |
| `--from <u64>` | First epoch in the batch            |
| `--to <u64>`   | Last epoch in the batch (inclusive) |

Calls `cbss-client::cip7::pre_wrap_batch` locally with the publisher's `stream_secret` (held in `~/.cowboy/watchtower-secrets/<stream_id>.key`), then submits a `register_content_keys` actor call to the Stream Key Manager. Batch size capped at `MAX_REGISTER_CONTENT_KEYS_BATCH = 10000` per call.

### `cowboy watchtower feed <id> wrap-daemon`

Long-running daemon: keeps the next N epochs pre-wrapped continuously by polling the chain for the current epoch and pre-wrapping ahead when the buffer drops below `--depth / 2`.

**Flags:**

| Flag            | Description                              |
| --------------- | ---------------------------------------- |
| `--depth <u64>` | Target lookahead in epochs (default 100) |

### `cowboy watchtower feed <id> publish`

Publish a new message to the feed.

**Flags:**

| Flag                    | Description                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `--kind <s>`            | Message kind (`news`, `price_batch`, `alert`, etc.)                                            |
| `--data <json>`         | Inline JSON payload. Max 16 KiB unencrypted; max 16,344 bytes plaintext for `subscriber-paid`. |
| `--tags <k=v,...>`      | Header tags for subscriber filter matching                                                     |
| `--content-type <mime>` | Default `application/json`                                                                     |

For `subscriber-paid` feeds, the CLI derives the per-epoch `content_key` locally using the publisher's `stream_secret`, encrypts the payload with XChaCha20-Poly1305 (PyNaCl), and submits the ciphertext envelope. The ed25519 signature over the canonical signing payload is also computed locally.

### `cowboy watchtower feed <id> rotate-publisher-key`

Allocate a new `signing_key_id` and switch the active publisher signing key. Past messages remain verifiable via `get-key-at-sequence`.

### `cowboy watchtower feed <id> rewrap-epochs`

Re-wrap a range of epochs (bumps each epoch's `generation` counter). Invalidates threshold signatures previously aggregated against the prior generation — subscribers must re-acquire access after a re-wrap.

### `cowboy watchtower feed <id> set-policy`

Set subscription policy: `public` (anyone can subscribe) or `private-allowlist`.

### `cowboy watchtower feed <id> allowlist add|remove <address>`

Manage the allowlist when policy is `private-allowlist`.

***

## Subscriber

### `cowboy watchtower feed <id> subscribe`

Create or update a subscription.

**Flags:**

| Flag                               | Description                                                                                         |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| `--mode push\|pull\|push-fallback` | Delivery mode                                                                                       |
| `--filter <json>`                  | JSON filter DSL (max depth 4, ≤16 predicates)                                                       |
| `--start-cursor <u64>`             | Initial cursor (omitted = subscribe at current head)                                                |
| `--account-key-id <u64>`           | Required for `subscriber-paid` feeds — selects which registered X25519 key receives CBSS deliveries |

### `cowboy watchtower feed <id> unsubscribe`

Cancel the subscription. Status → `CANCELLED`. Re-subscription requires a new `subscribe` call.

### `cowboy watchtower feed <id> get-since`

Pull messages with `sequence > cursor`.

**Flags:**

| Flag             | Description            |
| ---------------- | ---------------------- |
| `--cursor <u64>` | Last consumed sequence |
| `--limit <u32>`  | 1..=500                |

Returns ciphertext envelopes for `subscriber-paid` feeds (decryption is client-side via `cowboy watchtower feed <id> consume`).

### `cowboy watchtower feed <id> get-head`

Returns `head_sequence`, `floor_sequence`, and feed metadata.

### `cowboy watchtower feed <id> get-key-at-sequence`

Returns the publisher signing key effective at the given sequence (for subscriber-side signature verification across publisher-key rotations).

***

## Subscriber paid-mode

### `cowboy watchtower account register-key`

Register an X25519 public key as a CBSS recipient identity. The private key is stashed in the local keystore (`~/.cowboy/watchtower-keys/<key_id>.key`, 0600 perms) and never leaves the host.

**Flags:**

| Flag              | Description                  |
| ----------------- | ---------------------------- |
| `--scheme x25519` | Required (only scheme in v1) |

### `cowboy watchtower account list-keys`

List registered keys with their `account_key_id`, registration block, and `Active` / `Revoked` status.

### `cowboy watchtower account revoke-key <key_id>`

Revoke a previously registered key. In-flight SealRequests already on chain continue per CBSS rules; future `acquire-access` calls referencing this key\_id fail with `KEY_REVOKED`.

### `cowboy watchtower feed <id> acquire-access`

Purchase rolling stream access up through `--to-epoch`.

**Flags:**

| Flag                     | Description                                                                |
| ------------------------ | -------------------------------------------------------------------------- |
| `--to-epoch <u64>`       | Last epoch to cover                                                        |
| `--account-key-id <u64>` | Which registered X25519 key receives committee deliveries                  |
| `--beneficiary <addr>`   | Defaults to caller. Stream access accrues here.                            |
| `--payer <addr>`         | Defaults to caller. CBY debit comes from here. Allows sponsored purchases. |

Synchronous billing settles in the calling block. Async per-epoch SealRequest delivery follows over \~4–5 blocks per epoch.

### `cowboy watchtower feed <id> fetch-keys`

Block until CBSS committee delivers wrapped content keys for the listed epochs, then unwrap each to the local content-key cache.

**Flags:**

| Flag                     | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `--account-key-id <u64>` | X25519 key used to unwrap                                       |
| `--epochs <list>`        | Comma-separated epoch numbers or ranges (`100-110,200,300-305`) |

### `cowboy watchtower feed <id> consume`

Fetch ciphertext from the feed and decrypt locally using cached content keys.

**Flags:**

| Flag                     | Description                       |
| ------------------------ | --------------------------------- |
| `--account-key-id <u64>` | X25519 key for content-key lookup |
| `--cursor <u64>`         | Last consumed sequence            |
| `--limit <u32>`          | Max messages to fetch (1..=500)   |

Output is the verified, decrypted plaintext for each message in the range, with sequence numbers. AAD verification + ed25519 signature verification happen client-side; any mismatch is reported with the offending sequence.

***

## Discovery

### `cowboy watchtower list`

List all feeds registered in `WatchtowerRegistry`.

### `cowboy watchtower feeds [--owner <addr>]`

Alias for `list`, optionally filtered by owner.

### `cowboy watchtower feed <id> info`

Show feed metadata: owner, access-mode, fee config (if paid), current head/floor sequence, key epoch info, and subscription policy.

### `cowboy watchtower feed <id> subscribers`

List active subscribers.

***

## Notes

* All write commands use [key auto-discovery](/cli-specs/key-auto-discovery) for the publisher private key.
* For paid-mode subscriber flows, the X25519 private key is stored in `~/.cowboy/watchtower-keys/<key_id>.key`. Treat this as sensitive — compromise gives the holder access to every stream the account has acquired access to.
* Publisher `stream_secret` is stored at `~/.cowboy/watchtower-secrets/<stream_id>.key`. Loss of this secret breaks future re-wrapping (the publisher can rotate by generating a new secret + bumping each epoch's generation via `rewrap-epochs`).
* CBSS committee liveness is a hard dependency for paid-mode flows; `fetch-keys` and `acquire-access` will block / fail-fast if the committee is unavailable.