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

# Package and submit a listing

> Publish your actor's source, declare it in the General Store, send it for review, and ship new versions

By the end of this page, a deployed actor of yours is in review for the General Store, and you'll know what each review state means and how to ship a new version later. The [walkthrough](https://docs.cowboy.inc/sell/social-metrics-walkthrough.md#8-publish-the-source) runs these steps with a real actor; this page explains them.

## What a listing is made of

Three records turn a deployed actor into something people can hire:

| Record | What it says | Command |
| - | - | - |
| Declaration | This actor, this exact source, these terms, and who gets paid | `cowboy store declare` |
| Grant | The General Store may sell it | `cowboy store grant` |
| Submission | What it does, for the reviewers and the listing | `cowboy store submit` |

The first two are on the public record, like the actor itself. The submission goes to Cowboy's review.

## Publish the source

The declaration points at the source your actor was deployed from, and reviewers read that exact source. It lives in a public storage volume, one volume per version.

Storage commands sign with your wallet's key file and keep their own working files, which include a key that can write to your volumes. Give every `cowboy cbfs` command the same four things:

* `--wallet-key`, the path to your wallet's key file. `cowboy wallet create` keeps it at `~/.cowboy/keys/default`, or `~/.cowboy/keys/<name>` with `--name`. `cowboy wallet create --output <file>` writes the key somewhere else instead, but refuses any path in a `.cowboy` folder, a project's included. Keep such a file in a private folder outside every project and repository, such as `~/cowboy-keys/`, and pass that path here and as `--private-key` below.
* `--state-dir`, a private folder for those working files, outside every project and repository.
* `--spend-ledger` and `--spend-limit-wei`, a file that records the most each storage transaction's fee may be, and a limit on their total. `1000000000` wei is 1 CBY. A command whose fee would go past the limit stops before it signs anything. The limit covers fees only: `volume create` also moves a small storage deposit from your wallet into the volume.

Make the private folder once:

```bash theme={"system"}
mkdir -m 700 ~/.cbfs-social-pulse
```

Then create the volume and upload the project:

```bash theme={"system"}
cowboy cbfs --env cloud --wallet-key ~/.cowboy/keys/default \
  --state-dir ~/.cbfs-social-pulse \
  --spend-ledger ~/.cbfs-social-pulse/spend.json --spend-limit-wei 1000000000 \
  volume create --name social_pulse_v1 --public
cowboy cbfs --env cloud --wallet-key ~/.cowboy/keys/default \
  --state-dir ~/.cbfs-social-pulse \
  --spend-ledger ~/.cbfs-social-pulse/spend.json --spend-limit-wei 1000000000 \
  put social_pulse_v1 actors/social_pulse/main.py actors/social_pulse/main.py
```

Upload every file a reviewer needs to build and test it: the actor, its tests, `cowboy.toml`, `pyproject.toml` and the manifest. When you're done, delete the private folder: nothing else needs it, and it holds a key that can write to your volumes.

> [!WARNING]
>
> **Uploads to Cloud storage can fail from outside the Cowboy network.** Cloud's storage relays aren't publicly reachable yet, so `put` can time out, or stop with an error that asks for a trusted checkpoint. If it does, stop there. Don't declare the actor against a volume your files never reached: its source would be empty, and the declaration can't be changed to point at other files. Report the error to Cowboy and wait for uploads to work.

Then read back the volume's id and its **root**, a hash of everything in it. `cowboy volume list` shows the id of each volume your wallet owns, and `cowboy volume info` shows one volume's id and the root recorded on chain:

```bash theme={"system"}
cowboy volume list --env cloud --private-key ~/.cowboy/keys/default
cowboy volume info --name social_pulse_v1 --env cloud \
  --private-key ~/.cowboy/keys/default | python3 -c 'import json, sys
v = json.load(sys.stdin)
print("volume id: 0x" + v["volume_id"])
print("root:      0x" + bytes(v["commitment"]["manifest_root"]).hex())'
```

```text Output theme={"system"}
volume id: 0x7cd6…e0f0
root:      0xac1d…ee62
```

`volume info` prints JSON with the root as a list of 32 numbers under `commitment.manifest_root`, and the Python lines turn it and the id into the hex the next steps take. A root of all zeros means nothing reached the volume, so don't declare it. `cowboy cbfs volume info` and `cowboy cbfs root` don't work on Cloud yet, so use `cowboy volume info`.

Once the declaration names the root, don't change the volume, or the source stops matching.

## Declare it

```bash theme={"system"}
cowboy store declare --actor <actor address> --salt 0x<salt> \
  --manifest-root 0x<root> --claimed-root 0x<root> \
  --volume-id 0x<volume id> --code-visibility public \
  --term free --split <your address>:10000 \
  --human-hireable --agent-hireable
```

```text Output theme={"system"}
Declaration ID: 0x1546…6f64
Transaction hash: 0xaf61…1ed
```

* `--salt` is any 32 random bytes in hex, from `openssl rand -hex 32` for example. It makes the declaration's id unique.
* `--manifest-root` and `--claimed-root` are both the volume's root.
* `<your address>` is your wallet's address, which `cowboy wallet address --private-key ~/.cowboy/keys/default` prints. It isn't the actor's address.
* `--code-visibility public` says anyone may read the source.
* `--term` and `--split` set the price and who's paid ([Pricing](https://docs.cowboy.inc/sell/pricing.md)).
* `--human-hireable` and `--agent-hireable` say who can hire it: people, other agents, or both.

## Grant the General Store

```bash theme={"system"}
cowboy store grant --declaration-id 0x<declaration id> --store-id 1 \
  --split <your address>:10000 --lease-epoch-blocks 1800
```

The General Store's id on Cloud is `1`. The grant repeats the split. `--lease-epoch-blocks` is required, but it matters only for private code ([CIP-33](https://docs.cowboy.inc/cips/cip-33-actor-hiring-and-distribution.md#25-key-leases-private-code-actors)). `cowboy store get-grant --declaration-id 0x<declaration id> --store-id 1` shows the grant and its id, which the submission needs.

> [!NOTE]
>
> **Coming soon:** `store declare`, `store grant` and `store version` waiting for their transaction to commit and reporting the result. Until then, confirm each one with `cowboy store get-declaration` or `cowboy store get-grant`.

## The submission package

The submission is a JSON file that points at the records above and describes the actor for review. This is the complete one for Social Pulse, the [walkthrough](https://docs.cowboy.inc/sell/social-metrics-walkthrough.md)'s actor. Save it as `submission.json` in your project and replace each `<…>` value with your own:

```json submission.json theme={"system"}
{
  "declarationId": "0x<declaration id>",
  "declarationVersion": 1,
  "sourceVolumeId": "0x<source volume id>",
  "sourceManifestRoot": "0x<manifest root>",
  "builderAccount": "0x<your wallet address>",
  "codeVisibility": "public",
  "grantId": "<grant id>",
  "reviewReadCap": {
    "reference": "social-pulse source v1",
    "volumeId": "0x<source volume id>",
    "ownerAccount": "0x<your wallet address>",
    "granteeOrg": "cowboy-review",
    "accessMode": "ReadOnly",
    "expiresAtMs": 1830000000000,
    "canDelegate": false
  },
  "requestedCategory": "Social",
  "requestedTags": [
    "bluesky",
    "social",
    "metrics",
    "followers"
  ],
  "pricingSuggestion": {
    "kind": "free"
  },
  "capabilitySummary": {
    "cip33_schema": 1,
    "name": "Social Pulse",
    "description": "Track a Bluesky handle's followers, follows and posts. Refresh a handle to take a snapshot; read the latest one or the last 10.",
    "category": "Social",
    "methods": [
      {
        "name": "refresh",
        "description": "Fetch a handle's public profile and store a snapshot",
        "params": {
          "type": "string",
          "description": "Bluesky handle, e.g. bsky.app"
        },
        "result": {
          "type": "object",
          "properties": {
            "handle": {
              "type": "string"
            },
            "did": {
              "type": "string"
            },
            "display_name": {
              "type": "string"
            },
            "followers": {
              "type": "integer"
            },
            "follows": {
              "type": "integer"
            },
            "posts": {
              "type": "integer"
            },
            "at_ms": {
              "type": "integer"
            }
          }
        }
      },
      {
        "name": "latest",
        "description": "Most recent snapshot for a handle",
        "params": {
          "type": "string",
          "description": "Bluesky handle, e.g. bsky.app"
        },
        "result": {
          "type": "object",
          "properties": {
            "handle": {
              "type": "string"
            },
            "did": {
              "type": "string"
            },
            "display_name": {
              "type": "string"
            },
            "followers": {
              "type": "integer"
            },
            "follows": {
              "type": "integer"
            },
            "posts": {
              "type": "integer"
            },
            "at_ms": {
              "type": "integer"
            }
          }
        }
      },
      {
        "name": "history",
        "description": "Up to 10 snapshots for a handle, oldest first",
        "params": {
          "type": "string",
          "description": "Bluesky handle, e.g. bsky.app"
        },
        "result": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "handle": {
                "type": "string"
              },
              "did": {
                "type": "string"
              },
              "display_name": {
                "type": "string"
              },
              "followers": {
                "type": "integer"
              },
              "follows": {
                "type": "integer"
              },
              "posts": {
                "type": "integer"
              },
              "at_ms": {
                "type": "integer"
              }
            }
          }
        }
      },
      {
        "name": "handles",
        "description": "Handles with snapshots",
        "result": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    ],
    "egress": {
      "allowedDomains": [
        "public.api.bsky.app"
      ]
    },
    "rateLimits": {
      "refresh": {
        "perCaller": 20,
        "every": "1h",
        "pending": 2
      }
    },
    "humanHireable": true,
    "agentHireable": true
  },
  "reviewNotes": "Free. Source is in the public volume above. It calls Bluesky's public API, which needs no key."
}
```

| Field | What it holds |
| - | - |
| `declarationId`, `declarationVersion` | The declaration, and which version of it to review |
| `sourceVolumeId`, `sourceManifestRoot` | The volume and root that version was declared with, each `0x` and 64 hex digits |
| `builderAccount` | Your wallet address. It must be the wallet that signs the submission |
| `codeVisibility`, `grantId` | `public`, and the grant's id as a string of digits, such as `"240"` |
| `reviewReadCap` | Read-only access for the reviewers to the source volume, below |
| `requestedCategory`, `requestedTags` | Where you'd like it to appear |
| `pricingSuggestion` | The price you're asking for, such as `{"kind": "free"}` |
| `capabilitySummary` | What the actor does, for review and the listing |
| `reviewNotes` | Anything that helps a reviewer, such as how to try it |

`store submit` refuses a field it doesn't know, at the top level or in `reviewReadCap`. Its error names only where the unknown field is, `input` for the top level or `reviewReadCap`, so check the spelling of every key there.

`reviewReadCap` says who may read the source volume during review, and until when:

| Field | What it holds |
| - | - |
| `reference` | A label for this access, such as `"social-pulse source v1"`. Any text but empty |
| `volumeId` | The same value as `sourceVolumeId` |
| `ownerAccount` | The same value as `builderAccount` |
| `granteeOrg` | Who reviews it: `"cowboy-review"` |
| `granteeAccount` | Leave it out. If present, it must be the review account Cowboy configured, or the submission fails |
| `accessMode` | `"ReadOnly"`, exactly |
| `expiresAtMs` | When the access ends, in milliseconds since 1 January 1970. It must be in the future when you submit, and should leave time for review. `1830000000000` is 28 December 2027 |
| `canDelegate` | `false`, exactly |

`capabilitySummary` follows the capability document in [CIP-33](https://docs.cowboy.inc/cips/cip-33-actor-hiring-and-distribution.md#261-capability-schema). Give it `"cip33_schema": 1`, a `name` and `description`, each handler hirers call under `methods` with its parameter and result types, and the hosts it reaches under `egress`. A summary without those fields fails the automated checks.

`rateLimits` is optional. The automated checks only require it to be an object, and its fields aren't fixed yet. The example lists each handler's `@limit` under the handler's name, as `perCaller`, `every` and `pending`.

> [!NOTE]
>
> **Coming soon:** a command that writes this file from your declaration, a published list of every capability summary field, and listing artwork and a long description.

## Submit it

```bash theme={"system"}
cowboy store submit --input submission.json
cowboy store submissions --match-input submission.json
```

```text Output theme={"system"}
Recent submissions: 1
Submission: 2a02e41c-bef4-43f6-bb5c-3c6a8cf77673
state: "Queued"
reviewState: "Queued"
publicationState: "Not started"
exact_matches: ["2a02e41c-bef4-43f6-bb5c-3c6a8cf77673"]
```

Your wallet signs the submission, so there's no login. `store submissions` lists your recent submissions, and `--match-input` finds the one this file created.

## Review states

| State | What it means |
| - | - |
| Draft | Not sent yet |
| Submitted | Received |
| Scanning | The automated checks are running |
| Scan failed | An automated check failed. Fix it in a new version |
| Queued | The checks passed, and it's waiting for a reviewer |
| In review | A reviewer is looking at it |
| Changes requested | The reviewer wants something fixed |
| Rejected | It won't be listed |
| Approved | It passed review, and Cowboy publishes it to the General Store |

> [!NOTE]
>
> **Coming soon:** the reason a scan failed, shown with the submission.

## What reviewers check

Automated checks run first. They check the capability summary, look for keys or tokens written into the source, review the code, and flag categories that need extra care.

Then a person reads the exact source in your volume and compares it with what the listing claims: what the actor does, which hosts it reaches, which keys it needs, and what it does with a hirer's data. Expect questions about claims the code doesn't back, hosts it doesn't need, and anything sensitive kept in its state.

## Respond to review

A submission is frozen once sent, so a fix means sending something new. What you send depends on whether the fix changes the actor's code.

A declaration names one deployed actor, and that actor's code can't change. A fix to its code means deploying a new actor with `cowboy deploy --new`, which gets a new address, and listing that actor from the start: publish its source, declare it, grant it and submit it, as above. A new version of the old declaration would still point hires at the old actor.

When the deployed actor stays the same, and the fix is to the published source or the terms, publish the source to a new volume, declare a new version, and submit a new package with the new `declarationVersion`:

```bash theme={"system"}
cowboy store version --declaration-id 0x<declaration id> \
  --manifest-root 0x<root> --claimed-root 0x<root> \
  --volume-id 0x<new volume id> --code-visibility public \
  --term free --split <your address>:10000
```

Each version needs its own volume, because a version is pinned to the source it was declared with.

> [!NOTE]
>
> **Coming soon:** withdrawing a submission, and sending the same version again after a fix to the package.

## After it goes live

Hires stay on the version they hired. A new version goes through the same review, and changed code goes out as a new listing, as above.

To stop offering it for good, `cowboy store retire --declaration-id 0x<declaration id>` retires the declaration. That can't be undone.

> [!NOTE]
>
> **Coming soon:** unlisting a listing, and stopping or resuming sales, from your listing on Cloud.

Keep the actor funded while people use it, since it pays for its own work ([Keep it funded](https://docs.cowboy.inc/build/deploy.md#keep-it-funded)).

## Next

* [Pricing](https://docs.cowboy.inc/sell/pricing.md)
* [Walkthrough: sell a social metrics product](https://docs.cowboy.inc/sell/social-metrics-walkthrough.md)
* [`cowboy store`](https://docs.cowboy.inc/cli-specs/cowboy-store) lists every store command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.