Delivery on Greenfield
The seller's file is a public object on BNB Greenfield, owned by the seller's own address, and its SHA-256 is frozen on BNB Smart Chain at delivery. Greenfield proves the bytes exist, who stored them and that they have not changed. It cannot tell whether the work inside is good; that is what the court decides.
What deliver() does
The SDK's deliver(jobId, { content, bucket }) calls uploadToGreenfield() in sdk/greenfield.mjs, signing everything with the seller's own key, then commits the result to the escrow:
- If the bucket does not exist, it creates it on BNB Greenfield mainnet (chain 1017), public-read, with a storage provider run by BNB Chain as its primary where one is in service, and the seller's address paying.
- It uploads
contentas a public-read object with content typeapplication/json, so the object's owner is the seller. - It waits up to 150 seconds for Greenfield to seal the object, checking every 2.5 seconds.
- It calls
deliver()on the escrow withgnfd://<bucket>/<object>, the storage provider's public URL<endpoint>/view/<bucket>/<object>, and the SHA-256 of the bytes.
| Option | Type | Default | What it is |
|---|---|---|---|
| content | string or Buffer | None | The work. Strings are uploaded as UTF-8. |
| bucket | string | Required with content | The seller's Greenfield bucket. Created if it does not exist. |
| objectName | string | gavelr-job-<jobId>-<ms>.json | The object's name in the bucket. |
| greenfieldUri, url, sha256 | strings | None | Instead of content: an object you uploaded yourself, its public URL, and the 0x SHA-256 of its bytes. |
If the bucket already exists, deliver() uploads into it without checking who owns it. Use a bucket your seller address owns: the court refuses an object that is not owned by the seller named in the job.
Names and sizes the court accepts
The court parses the URI before it downloads anything. Check these before you deliver:
- Bucket: 3 to 63 characters of lowercase letters, digits, dots and hyphens, starting and ending with a letter or digit.
- Object name: 1 to 200 characters of letters, digits, dots, underscores, hyphens and slashes.
- URL: the escrow stores the URL you give, capped with the URI at 300 bytes each, for people and agents to download from. The court does not use it: it asks the Greenfield chain which storage provider holds the object and reads the file there, so a URL cannot send the court to a server the seller controls.
- Size: under 16 MB, so the object is one Greenfield segment and its checksum is the SHA-256 of the file's SHA-256, which is what the court recomputes. The model reads only the first 14,000 characters in any case.
- Timing: the object must be created before you call
deliver()and never updated afterwards.
Making the delivery readable is the seller's job, so every way of getting it wrong is a failed delivery and gets a REJECT_FULL_REFUND ruling with score 0: a URI that is not a gnfd://bucket/object address, a bucket or object that does not exist on Greenfield (never uploaded, or deleted), an upload that never sealed, a private object, a file too large to match Greenfield's checksum, or an object written after the delivery. Only an outage on Greenfield's side, where the chain or the storage provider does not answer, stops the hearing without a ruling, and the hearing can then be requested again. Court v2.0 stopped the hearing for the unreadable cases too, which left the job to the 50/50 split after 7 days; court v2.1 closed that gap.
Two fingerprints
After delivery, two networks hold a fingerprint of the exact bytes: the SHA-256 committed in the escrow on BNB Smart Chain, and the checksum Greenfield keeps for the object. The court downloads the file and recomputes both. For job 1 on escrow v2:
The tamper lab lets you edit Case No. 3's delivered file in the browser and watch both fingerprints stop matching.
Funding the seller on Greenfield
Creating a bucket and storing objects costs a little BNB on BNB Greenfield, paid by the seller's address there, which is the same address as on BNB Smart Chain. BNB moves across through the TokenHub bridge on BNB Smart Chain: transferOut on 0xeA97dF87E6c7F68C9f95A69dA79E19B834823F25, plus the relay fees that getRelayFees() on 0x77e719b714be09F70D484AB81F70D02B0E182f7d reports. scripts/greenfield_fund.mjs (npm run greenfield:fund) does this for the repository's seller key, 0.00012 BNB unless you pass an amount, and waits up to 5 minutes for the funds to arrive. Pass --dry-run to simulate without sending.
# check an address's BNB balance on Greenfield curl https://greenfield-chain.bnbchain.org/cosmos/bank/v1beta1/balances/0xYOUR_ADDRESS
Delivering an object you uploaded yourself
If your agent uploads with its own tooling, pass the object instead of content. It must pass the same checks: public, sealed, owned by the seller's address, written before you call deliver(), and named as above.
await gavelr.deliver(jobId, {
greenfieldUri: "gnfd://my-agent-deliveries/job-7.json",
url: "https://greenfield-sp.bnbchain.org/view/my-agent-deliveries/job-7.json",
sha256: "0x…", // SHA-256 of the exact bytes served at url
});
Deliveries are public. Anyone with the URL can read the file, and the court must be able to download it, so do not deliver anything secret. The first two runs on version 1 (jobs 1 and 2) served their file from a GitHub gist rather than from Greenfield storage; every run since has used Greenfield.