How Atrium works

Agent runtimes such as Hermes and OpenClaude generate reusable skills — self-contained capabilities written as Markdown with structured metadata. On their own those skills are trapped locally: no portable authorship, no integrity guarantee, no way to pay the author. Atrium supplies three missing primitives — provenance, integrity, and settlement — as a thin layer that composes with any runtime via MCP.

The stack:

• A non-upgradeable Solidity contract on Base (the registry + settlement).
• A CLI that signs, pins to IPFS, and registers skills.
• An MCP server so agents can discover and invoke skills as tools.
• A read-only indexer (SQLite + REST) and this web app.

A skill is a Markdown file with YAML frontmatter; the body below is the prompt or procedure the agent reads. The frontmatter is a superset of the agentskills.io format:

---
name: pdf-toolkit
version: 0.1.0
author_did: did:key:z6Mk…
description: Read, merge, split, OCR and fill PDF files.
tags: [pdf, extraction, ocr]
categories: [document-processing]
runtime: prompt-only
price_per_call_usdc: '0.004'
parent_skills: []          # or [{ skill_id: 0x…, royalty_bps: 1500 }]
created_at: '2026-05-31T00:00:00Z'
derivation_method: imported   # hermes-loop | manual | openclaude | imported
---

# PDF Toolkit
…the skill body the agent reads…

Prices are decimal USDC strings (USDC has 6 decimals). Each parent is a (skill_id, royalty_bps) pair; combined parent royalties cannot exceed 50%.

Authors are identified by a W3C did:key over an Ed25519 keypair — durable across wallet rotations. The skill body is pinned to IPFS, so its CID is a hash of its bytes: identity equals integrity. The author signs a canonical hash of the manifest; anyone can verify the signature against the DID without touching the chain.

The on-chain skill id is deterministic and predictable before you register:

skillId = keccak256(abi.encodePacked(cid, didHash, creator))
didHash = SHA-256(did)

A ~300-line non-upgradeable contract records skills and routes payments. On invokeSkill it pulls the USDC price once, takes the protocol fee, pays declared parent royalties, and credits the remainder to the creator — all to an internal ledger that recipients later withdraw (the pull-payment pattern):

protocolCut   = price * protocolFeeBps / 10000   // 250 bps = 2.5%
distributable = price - protocolCut
for each declared parent i:
    parentCut = distributable * parentBps[i] / 10000
    withdrawable[parent.creator] += parentCut       // credit, don't send
withdrawable[skill.creator] += remainder            // sum of credits == price

No funds are sent during invocation; recipients pull their balance. The sum of credits equals the price exactly (conservation of funds), and re-entry yields no double-spend.

A derived skill declares its direct parents with basis-point shares. Royalties are paid only to declared, direct parents — never propagated up an inferred ancestry. That keeps each author's revenue predictable and the per-call cost gas-bounded (O(parents), not O(depth)).

Worked example. A→B→C; Dave prices C at P, declaring B as a parent at 15%. On invoke(C) with a 2.5% fee: treasury gets 0.025P; Alice (author of B) gets 0.146P; Dave gets the remaining 0.829P. Carol (author of A) earns nothing unless Dave also declares A. The protocol fee is 2.5%, hard-capped at 5%; settlement is USDC, and there is no protocol token.

Via the CLI (signs with your DID, pins to IPFS, registers on-chain):

atrium init                      # generate DID + wallet (~/.atrium)
# fund the wallet with Base Sepolia ETH + USDC; set PINATA_JWT
atrium publish ./my-skill        # → skillId, IPFS CID, tx hash

Or from the web: the publisher parses your skill.md, pins it to IPFS with your Pinata JWT, and calls registerSkill from your browser wallet.

A consumer approves the USDC price and calls invokeSkill(skillId); the contract splits the payment in one transaction. From an agent, the MCP server exposes discovery + invocation as tools, so any MCP-capable runtime can search Atrium and run a skill the same way it calls any other tool. In the web app, the Invoke button on a skill page runs approve → pay → unlock.

The web app reads everything from a read-only REST indexer (never a chain RPC per page load):

A skill can be published with --encrypt: the body is sealed with AES-256-GCM and only the ciphertext is pinned to IPFS. The content key is held by a key-service that releases it to a wallet only after verifying that wallet has an on-chain SkillInvoked (i.e. paid). The consumer then decrypts in their own browser. This removes the free-riding-via-public-fetch gap.

Honest trust note: the MVP key-service is trust-minimized, not trustless — the operator could leak a key. The trustless upgrade is threshold decryption (a committee / network like Lit) keyed on the same on-chain payment receipt; the envelope and the pay-to-decrypt flow stay identical.

Content addressing prevents body substitution; the Ed25519 signature proves authorship; the pull-payment pattern prevents griefing and re-entrancy gain; the owner can only adjust the fee (within the cap) and the treasury — nothing touches user funds. Open issues: IPFS availability, free-riding via public fetch, and sybil attestations.

Provenance tells you who wrote a skill and that it is unchanged — not that it is safe to run. Sandboxing and capability control belong to the runtime, not the marketplace.

# 1. deploy the contract to Base Sepolia
forge script scripts/DeployAtrium.s.sol --rpc-url base_sepolia --broadcast

# 2. indexer (REST API on :3001)
cd indexer && cp .env.example .env   # set ATRIUM_REGISTRY + deploy block
npm run dev

# 3. web app (:3000)
cd frontend && cp .env.example .env.local
npm run dev