Skip to main content
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 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: 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:
Then create the volume and upload the project:
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.
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:
Output
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

Output
  • --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).
  • --human-hireable and --agent-hireable say who can hire it: people, other agents, or both.

Grant the General Store

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). cowboy store get-grant --declaration-id 0x<declaration id> --store-id 1 shows the grant and its id, which the submission needs.
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’s actor. Save it as submission.json in your project and replace each <…> value with your own:
submission.json
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: capabilitySummary follows the capability document in CIP-33. 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.
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

Output
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

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:
Each version needs its own volume, because a version is pinned to the source it was declared with.
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.
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).

Next