bucket foundation — inverse omegabucket.foundation
§ protocol

feed402 · paid-once, cite-forever

An open standard for paid research endpoints over x402 on Base. Discover, pay, query — three tiers, one envelope.

open source

bucket.foundation protocol — v0.1 (draft)

The open spec for pay-once, cite-forever research buckets over x402.

Status

Draft v0.1. Everything in this document is subject to change until v1.0. Open an issue or PR to propose changes.

1. Goals

  1. A paper should cost the network once.
  2. Once bought, it should be citeable forever by anyone running a compatible bucket.
  3. The author should receive the citation fee directly, not through a publisher.
  4. The protocol should be boring: HTTP, JSON, SHA-256, and signatures. Nothing exotic.
  5. Implementations should be federatable: anyone can run a bucket, mirror another bucket, or fork the whole network.

2. Non-goals

  • Peer review (that's a layer on top).
  • Reputation or ranking of papers (a layer on top).
  • Replacing existing publishers (they are free to expose x402 endpoints too).
  • Being a blockchain. The only on-chain part is the x402 payment and the optional citation receipt.

3. A bucket

A bucket is a content-addressed folder that holds one research artifact.

bucket/<sha256>/
├── paper.<ext>       # the artifact itself (PDF, HTML, JSON, dataset…)
├── canon.json        # REQUIRED — the sidecar manifest (see §4)
└── receipt.x402      # OPTIONAL — the x402 payment receipt that funded this bucket
  • <sha256> is the SHA-256 of paper.<ext>, hex-encoded, lowercase.
  • Any storage backend is acceptable: filesystem, S3, IPFS, Walrus, Arweave, Google Drive, a USB stick. The protocol only requires that a given <sha256> address resolves to the same bytes everywhere.
  • A bucket with a missing or invalid canon.json is not a canon bucket. It still exists; it just cannot be cited through this protocol.

3.1 Agent-trust rule — paid-to-cite is not pay-to-proceed (normative)

A correctly safety-trained autonomous agent should refuse the pattern "fetch a document, then perform a payment that the fetched document instructs you to perform." That refusal is correct behaviour and a compatible implementation MUST NOT depend on overriding it.

Therefore, on any caller-facing read/cite path, a compatible implementation:

  1. MUST NOT return a payment challenge, an x402/X-PAYMENT header, or any

instruction directed at the caller to sign, send, authorize, or relay a payment. Specifically, receipt.challenge MUST NOT be present on a caller-facing response.

  1. MUST perform any x402 settlement entirely server-side (operator wallet

↔ source), invisibly to the caller, OR serve already-paid content instead.

  1. MUST include the declarative fields agent_action_required: false and

payment_required_from_you: false on every caller-facing envelope, and MUST keep them truthful.

  1. MUST treat the cite block as *passive, forward-looking license

metadata describing what a downstream publisher* owes the author if they re-publish in a paid work — never as a charge to, or an action by, the reading agent. cite.reader_owes MUST be 0 and cite.applies_to SHOULD declare the scope (e.g. downstream_republication_in_a_paid_work).

This is the line between paid-to-cite (passive, free to read and cite, fees route to authors only on downstream paid re-publication) and pay-to-proceed (a mid-request paywall the caller must clear). feed402 buckets are paid-to-cite. Reference implementation: /api/research in the bucket.foundation repo; trust model in /llms-full.txt §4; sibling to feed402 SPEC.md §3.1.

Why this rule exists. A correctly safety-trained agent refused the pre-fix reference implementation on exactly these grounds, in its own words, and that refusal was correct. The full technical write-up — the verbatim refusal, why it was right given what it saw, and the field-by-field structural fix — is the canonical reference for this section: `/protocol/agent-trust` (markdown source: docs/AGENT-TRUST.md).

4. The sidecar (canon.json)

The sidecar is a JSON object. All fields are UTF-8. Unknown fields MUST be preserved by implementations.

4.1 Schema (draft v0.1)

{
  "version": "bucket.foundation/v0.1",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "title": "Plain-English title of the work",
  "authors": [
    { "name": "Jane Doe", "orcid": "0000-0001-2345-6789", "wallet": "0x…" }
  ],
  "doi": "10.1234/example.2026.001",
  "source": {
    "url": "https://source.example.org/paper/12345",
    "x402_endpoint": "https://source.example.org/x402/paper/12345",
    "license": "CC-BY-4.0"
  },
  "purchase": {
    "x402_receipt": "0x…",
    "network": "base",
    "paid_usd": "0.25",
    "paid_at": "2026-04-14T00:00:00Z",
    "buyer_wallet": "0x…"
  },
  "cite": {
    "price_usd": "0.05",
    "payout_wallet": "0x…",
    "license": "bucket.foundation/cite-forever/v0.1"
  },
  "tags": ["biophysics", "magnetic-field", "foundation:05-biophysics"],
  "canon_tier": "candidate",
  "foundation_branches": ["05-biophysics"],
  "provenance": [
    {
      "action": "fetched",
      "at": "2026-04-14T00:00:00Z",
      "by": "bucket.foundation/v0.1",
      "via": "viatika-research-gateway/v1"
    }
  ]
}

4.2 Required fields

  • version — must start with bucket.foundation/v.
  • sha256 — must match the hash of paper.<ext>.
  • title — non-empty.
  • source.url — the origin the bytes were fetched from.
  • cite.payout_wallet — where citation fees go.

4.3 Canon tier

canon_tier is one of:

| Tier | Meaning | |---|---| | draft | Fetched and sidecar-ed, not reviewed. Not eligible for minting. Usable for private research. | | candidate | Reviewed by a human or high-confidence agent, passed a provisional canon filter. Eligible for mint. | | canon | Final, minted as an IP NFT, appears on the public canon. |

Tiers are advisory, not enforced by the protocol. Different buckets can disagree on tier and still interoperate.

4.4 Foundation branches

foundation_branches is an array from this controlled vocabulary (this list is advisory, not normative):

| Branch | Scope | |---|---| | 01-mathematics | Axioms, real math, proofs | | 02-physics | Laws, symmetries, field theories | | 03-chemistry | Bonding, thermodynamics, primary reactions | | 04-information | Shannon, Turing, complexity, coding | | 05-biophysics | Hydrogen, mitochondria, DNA, bioelectrochemistry, biomagnetism | | 06-cosmology | Spacetime, early universe, black holes | | 07-mind | Consciousness, cognition, perception foundations |

Implementations MAY define their own branches. Federated buckets SHOULD preserve branches they don't understand.

5. The x402 fetch flow

1. Client asks bucket:    do you have <doi> or <query>?
2. Bucket checks storage: SHA match → serve locally, charge cite price.
3. If miss, bucket routes to an x402-gated source (e.g. a research gateway).
4. Source returns HTTP 402 Payment Required with an x402 challenge.
5. Bucket's buyer wallet signs the payment on Base (or any x402 network).
6. Source returns HTTP 200 with the paper bytes.
7. Bucket computes SHA-256, writes bucket/<sha256>/paper.<ext> and canon.json.
8. Bucket serves the paper to the original client and charges cite price.
9. Every subsequent client hits step 2 — pay-once, cite-forever.

5.1 x402 endpoint shape (source side)

Any HTTP endpoint that returns 402 Payment Required with an X-Payment header describing the x402 challenge is compatible. See x402.org for the full spec.

5.2 Citation receipt (optional)

When a bucket charges a client for a citation, it MAY emit a cite.receipt object in response:

{
  "cite_receipt": {
    "sha256": "e3b0c44…",
    "cited_at": "2026-04-14T00:00:00Z",
    "payer_wallet": "0x…",
    "payout_wallet": "0x…",
    "paid_usd": "0.05",
    "tx": "0x…"
  }
}

Receipts are advisory and auditable. They are not required for the citation to be valid.

6. Federation

Two buckets federate by mirroring each other's <sha256> addresses. Since every bucket address is a content hash, mirroring is idempotent: either both sides have the same bytes or they don't. There is no "authoritative" bucket — there is only the first bucket that paid.

A federated network of buckets looks like BitTorrent for papers, plus a citation-fee layer.

7. What this protocol does NOT say

  • How to rank, recommend, or search buckets. (Build your own index.)
  • How to handle takedowns. (Run your own bucket; honor your own jurisdiction.)
  • How to price a paper or a citation. (Author sets it, market adjusts.)
  • What happens to old buckets when a paper is retracted. (Add a retracted_at field in v0.2.)

These are deliberately out of scope. The protocol is the minimum viable coordination layer — everything else is an implementation choice.

8. Versioning & compatibility

  • version in the sidecar drives compatibility.
  • Minor versions (v0.1 → v0.2) MUST be backwards-compatible — new fields only.
  • Major versions (v0.x → v1.0) MAY break. A clean break is healthier than a rotting spec.
  • Implementations SHOULD advertise supported versions in an X-Bucket-Protocol response header.

9. Contributing to this spec

Open an issue or a pull request at https://github.com/gianyrox/bucket-foundation.

Changes to this document require:

  1. A written rationale (what problem does this solve?).
  2. At least one reference implementation or test vector.
  3. A migration note for buckets already deployed.

That's it. No foundation (lowercase), no governance token, no voting. The maintainer merges. Forks are encouraged.