annon
Start · Overview

Annon

Pay, friend, and enter.
Annon lets people and agents sell client-encrypted files, with payment verification and key release coordinated on NEAR.

Demo · Quick start · Docs · Specification · Security · annon.dev


Status: alpha on NEAR mainnet. We ran the main paths on mainnet with our own small funds: buying over NEAR, Base and 1Click, selling from the browser and from the CLI, and stopping a listing. Not every edge case is tested as deeply as we want, and some steps still take more clicks than they should. We know where: the open items are in ROADMAP.md and docs/what-can-go-wrong.md. Use small amounts, keep your backup secret, and tell us what breaks: hello@annon.dev or a GitHub issue.

What it is

Selling a digital file usually means trusting a platform. The platform stores the file, holds the buyer's money and decides who gets the download link. If it disappears, changes its rules or leaks the file, the seller and the buyer have no recourse.

Annon is an open protocol, SDK, CLI and MCP server that removes that middle role:

  • The seller encrypts the file on their own machine and registers its terms on a NEAR contract: the price, who is paid and in what shares, and a commitment to the encrypted file. The encrypted file can be hosted anywhere. The host cannot read it.
  • The buyer pays in USDC on NEAR, on Base through x402, or from a supported source chain through NEAR Intents (1Click). The contract checks the payment on chain, Base included.
  • NEAR's MPC network then derives the secret that unlocks the file key and encrypts it to a one-time key that only the buyer holds. The buyer decrypts locally. No host, relayer or shop sees the file key.
  • The money follows the registered split. If the buyer moves to another device, the same wallet gets the file again without paying twice.

People and agents buy the same way: an Annon file is an ordinary URL that answers HTTP 402 with its offers.

Status: alpha. The contract runs on NEAR mainnet, can still be upgraded by defdone and has no independent audit yet. See Encryption and trust.

Why we built it

We are not aware of another open file-selling protocol that combines NEAR MPC key release, NEAR Intents 1Click payments and client-side file encryption. We built Annon to make that combination usable by people, shops and agents.

We wanted three things at once. The file should be encrypted before any server sees it. The key should be released by a contract that checked the payment itself, not by a server that says it did. And an agent should be able to buy a file with the same URL a person opens, under limits its owner sets.

What it can become

Annon is small today: one contract, one SDK, a demo shop. These follow from how it already works:

  • Files that are not tied to one shop. The terms live on NEAR. The same encrypted file can be served by any host that implements the download protocol, and shops describe themselves in a manifest at /.well-known/annon-shop.json, so clients and agents can find them. Wherever the file is sold, the registered split decides who gets paid.
  • Agents that pay for data. An agent buys a file the way it would call a paid API: through an HTTP 402 offer, with a price cap and a daily budget. It can also sell its own output, such as a report or a dataset, with the same tools.
  • Payouts to collaborators. A file pays up to eight recipients in fixed shares. NEAR payments are credited to NEAR Intents accounts, from which recipients can withdraw to other chains.
  • Access without accounts. There is no shop login. The buyer's wallet is the proof of purchase, on any device and in any client that speaks the protocol.

What we plan next is in ROADMAP.md.

How it works

mermaid
flowchart LR
    S[Seller client] -->|Encrypt file locally| H[Ciphertext host]
    S -->|Register terms and ciphertext commitment| C[Annon contract on NEAR]
    B[Buyer client] --> P[Payment: NEAR, Base x402, or 1Click]
    P -->|Finalized payment evidence| C
    C -->|Authorize key derivation| M[NEAR MPC]
    M -->|Answer encrypted to buyer's one-time key| B
    H -->|Checked encrypted file| B
    B --> D[Unwrap file key and decrypt locally]

Three payment routes, named the same in the SDK, the CLI and the MCP server:

Route The buyer pays with Where the money goes
near USDC on NEAR, from a NEAR account The contract holds it until anyone calls settle, which credits every recipient's NEAR Intents account
base USDC on Base, through x402 Straight to the file's split contract on Base (0xSplits), which pays the same shares
1click A supported token on another chain, swapped by NEAR Intents into USDC on NEAR As for near

Not every payment passes through NEAR. A Base payment stays on Base; the contract only verifies it, by asking the MPC network to check the Base transaction (verify_foreign_transaction) instead of trusting a relayer or an oracle. Direct base payments need a Base payee in the file's on-chain terms. Files from EVM sellers can have one. Files from NEAR and Solana sellers do not, and a buyer with USDC on Base pays those through 1click with Base as the source chain.

What NEAR does, step by step:

Step On NEAR
Listing The contract stores the terms, signed by the seller, and a commitment that covers the hash of every encrypted chunk.
Payment on NEAR USDC arrives through ft_transfer_call; the contract checks the amount against the terms.
Payment on Base The contract asks the MPC network to verify the Base transaction.
Payment from another chain NEAR Intents (1Click) swaps and delivers USDC to the contract, which accepts it like a direct payment.
Key release The MPC network runs confidential key derivation (CKD) for the buyer's one-time key. Only that key can read the answer.
Payout For payments received on NEAR, anyone can call settle. Underpayments are refunded in full; overpayments are accepted and the excess is refunded.
Recovery The buyer's wallet signs for a new one-time key on a new device. No second payment.

Encryption and trust

How a file is protected:

  • The seller's client creates a random 32-byte file key. The PAY2 format derives one key per chunk from it and encrypts each chunk with AES-256-GCM. The registered commitment binds the whole encrypted body, so a buyer can check every byte against the registration.
  • The file key is wrapped with a secret that only NEAR MPC confidential key derivation produces for this contract and file.
  • After the contract accepts a payment, the buyer receives an MPC answer encrypted for their one-time key. The buyer's client unwraps the file key and decrypts locally.

What this rests on:

  • The cryptography is correct, and the seller's and buyer's clients are not compromised.
  • The NEAR MPC network's threshold security holds, and the contract requests keys only under its access rules.
  • During the alpha defdone can upgrade the contract. That is the largest trust we ask for. There is no independent audit yet. We plan one, then we remove the upgrade key and lock the contract.

What it does not do:

  • It is not DRM. The seller knows the content, and a buyer can share what they decrypted.
  • Listing terms, titles, descriptions and file sizes are public. Only the content is encrypted.
  • Encryption and key release do not prove the content is useful, and do not keep a host online. Keep your own copy of what you buy.
  • A preview inside a PAY2 file is not checked for buyers in this release.

The full trust model and the known limits are in SECURITY.md. The formats are in specs/pay2.md and specs/near-settlement.md.

Quick start

Try it in a browser

A shop can build a browser purchase screen on the SDK. The SDK supports the file's available payment routes, local decryption and saved purchase records. The demo shop is at annon.dev/demo.

You pay with your own funds. On Base you need only USDC, no ETH: you sign an authorization and the host pays the gas. On NEAR you also need a little NEAR for gas. Through 1Click you fund the quoted amount of the source token plus that chain's gas; the quote includes the swap fees. The demo's open pool allows up to 10 upload admissions and 2 sponsored listings per wallet and per IP bucket per UTC day. Listed sellers have a separate allowance of 20 per wallet per day. Hosted files normally expire seven days after publication; keep your own copy. All limits: docs/shops-and-limits.md. Questions, or a file to report: hello@annon.dev.

Buy a file

You need Node.js 22.22.2 or newer, and either a NEAR wallet with a little USDC and NEAR, or an EVM wallet with USDC on Base. Install the CLI from the npm alpha tag:

Shell
npm install -g @defdone/annon@alpha

Run annon init --deployment defdone once. It writes ~/.config/annon/config.json for the deployment run by defdone when you have none (or write your own for another deployment) and creates the backup secret that encrypts your local records. Back that file up (how) and sign in with your wallet: docs/quickstart.md has each command. Then:

Shell
annon verify https://demo.annon.dev/f/what-we-are-building --trust-contract
annon buy https://demo.annon.dev/f/what-we-are-building --route near
annon status 0xPURCHASE_ID
annon open 0xPURCHASE_ID --output what-we-are-building.pdf

You see the price and the recipients before you approve. The demo file costs 0.10 USDC and splits 69/31: the relayer's fee for a sponsored listing is 0.03 USDC plus 1% per sale, which is 31% of 0.10 USDC but only 4% of a 1 USDC file (fees). Then you get a purchase ID, a status of accepted, and the decrypted file. Your purchase is saved, encrypted, before you pay. If status says pending, wait and check again; resume the same purchase with annon status and annon open instead of starting a new one. While it is live or accepted, a second annon buy of the same file is refused with purchase_open unless you pass --force. To pay with USDC on Base or from another chain, follow Pay on Base or Pay from another chain with 1Click. Opening the file on another computer: docs/quickstart.md.

Sell a file

The simplest path is hosted selling through a shop, with a NEAR, EVM or Solana wallet. The demo shop is already in the quickstart configuration, with its deployment profile approved, so you can sell on it right away:

Shell
annon share report.pdf --price 0.10 --shop demo --title "Q3 report"

For another shop, add it with annon shop add https://shop.example --id SHOP_ID and approve its deployment profile in your configuration (docs/selling.md) before the first share.

The CLI encrypts the file locally and shows the final terms: the price, the split with any fee share, and for a NEAR seller the storage it pays. After you type yes it saves a backup, uploads the encrypted file to the shop's host, registers the terms and prints the purchase URL with the hosting expiry. EVM and Solana sellers need no NEAR: the shop's relayer pays and takes its fee share. If the shop publishes rules in its manifest, the CLI prints them with the result. If a sale stops, resume it with annon share report.pdf --resume 0xFILE_ID --shop SHOP_ID; never start a new one.

To host the file yourself, annon sell writes a .pay2 file and registers its terms. You serve the file from a server built on the SDK's serveFile (apps/demo-host is a complete example). A NEAR account pays its own storage and gas, and no protocol fee is added:

Shell
annon sell report.pdf --wallet near --price 1.00 --split near:YOUR_ACCOUNT.near:10000 --storage-budget 0.05 --output report.pay2

Splits are in basis points, total 10000, and pay up to eight recipients. Routes, storage, splits and resuming: docs/selling.md.

Run an agent with MCP

JSON
{
  "mcpServers": {
    "annon": {
      "command": "npx",
      "args": ["-y", "@defdone/annon-mcp@alpha"],
      "env": {
        "ANNON_CONFIG": "/absolute/annon-agent.json",
        "ANNON_BACKUP_SECRET_FILE": "/absolute/private/backup-secret"
      }
    }
  }
}

The owner writes the configuration file it points to: the trusted contract, maxPrice per purchase, dailyBudget per UTC day, the workDir the agent may use, and the wallet. The agent's key stays in a file, an environment variable, the macOS Keychain or a remote signer. Tools never see it and cannot change any limit. The agent runs annon_catalog or annon_verify, then annon_buy, then annon_status until accepted, then annon_open. The result is a structured status and the decrypted file inside workDir. Discovery tools are read-only and cannot approve a deployment or a payment. An agent can also sell with annon_share or annon_sell, under the same owner policy. Full setup: docs/agents.md.

Agents should buy the 0.10 USDC demo file with near or base: 1Click sets its own minimum per route (about 0.15 USDC from Base when we checked), and below it 1Click refuses the quote before any payment is sent (details).

For developers

TypeScript
import { Annon } from '@defdone/annon';
import {
  BrowserPurchaseController,
  browserEvmWallet,
  browserPurchaseStorage,
} from '@defdone/annon/browser';

The SDK runs in Node.js and in browsers. The browser entry has a purchase controller that survives reloads and works across tabs, encrypted local receipts, downloads with in-browser decryption, a seller controller for hosted selling from a page (createBrowserSeller), and adapters for injected EVM, Solana and NEAR wallets. There is no hosted checkout: a shop builds its own screen on the SDK. To run a shop, see apps/demo-host, apps/relayer and docs/shops-and-limits.md. SDK reference: packages/annon.

Documentation for people and agents

Every document is plain Markdown, so an agent can read it directly.

Document Covers
annon.dev/llms.txt Index of the public docs, for agents
docs/quickstart.md Install, configure, buy, open, recover
docs/selling.md Hosted and self-hosted selling, routes, splits
docs/agents.md MCP setup, owner limits, the tool sequence
docs/shops-and-limits.md Fees, shop limits, shop rules
docs/near-accounts.md NEAR storage costs for sellers and recovery
docs/what-can-go-wrong.md Errors, retries, refunds and other failure cases
packages/annon/CLI.md Every CLI command and option
packages/annon-mcp MCP tools, configuration, safety model
skills/annon/SKILL.md Agent skill: the whole flow, when to wait
ARCHITECTURE.md Code map: module layout, where each flow lives, how to check it
SECURITY.md Trust model, known limits, reporting

Specifications, with test vectors checked in CI, so anyone can build a compatible implementation:

Document Defines
specs/pay2.md PAY2, the encrypted file format
specs/near-settlement.md Listing, purchase, routes, key release, payouts, refunds
specs/x402-annon.md The x402 offer and the Base payment
specs/download.md Serving the file to the buyer who proves the purchase
specs/nonce.md Purchase and payment nonces
specs/vectors/ Test vectors

Build and test

You need Node.js 22.22.2 or newer (on Node 23, 23.6 or newer), pnpm 12 (corepack enable picks the pinned version) and Rust. rust-toolchain.toml pins the Rust version, so run rustup toolchain install in the repository first. From the repository root:

Shell
rustup toolchain install
pnpm install --frozen-lockfile
pnpm build
pnpm test
contracts/annon/build.sh
cargo test

These run locally and send no transactions. build.sh builds the contract's wasm, which the sandbox tests use. CI runs the same steps, plus formatting, lint, a dependency audit, the spec-vector check and container tests of the relayer and the demo host. CI builds the contract with build.sh --release instead: the same commit gives the same wasm on macOS arm64 and Linux x86-64 with Docker, in the pinned linux/amd64 NEAR image.

Path Contents
contracts/annon The NEAR contract (Rust, near-sdk)
packages/annon @defdone/annon: SDK and annon CLI
packages/annon-mcp @defdone/annon-mcp: local MCP server
apps/relayer Relayer: sponsors NEAR transactions and runs the settlement keeper
apps/demo-host File host with hosted uploads and its own x402 facilitator on Base
specs Specifications and test vectors
skills/annon Agent skill

Project status

Stage Alpha, on NEAR mainnet
Payment routes 3: near, base, 1click, as each file's terms allow
Direct payment chains 2: NEAR and Base. Other source chains through 1Click, as its routes and liquidity allow
Wallets NEAR, EVM and Solana, for sellers and buyers
File size Up to 50,000,000 bytes of plaintext per file
Split recipients Up to 8
Tests About 3,100 automated JavaScript tests in CI (pnpm test), plus the contract's Rust unit and sandbox tests
Fees None for the protocol, SDK, CLI or MCP server on your own infrastructure (details)
Deployment Mainnet
Contract v1.annon.defdone.near
Relayer https://relayer.mainnet.annon.dev
Demo shop https://annon.dev/demo
Demo files https://demo.annon.dev
MPC network v1.signer
USDC NEAR native USDC and Base USDC

To report a vulnerability, use GitHub's private reporting on this repository (SECURITY.md).

License

Apache-2.0. Created by defdone.

Synced from README.md at commit e649de1. Also asMarkdown.