Architecture

Pinecode is intentionally layered. Each layer exposes a clean primitive that the layer above can compose without knowing the internals of the one below. This makes the system forkable, auditable, and replaceable in pieces.

The seven layers

┌─────────────────────────────────────────────────────────────┐
│  7. Governance      Quadratic voting · delegation · vetoes   │  Planned Q3
├─────────────────────────────────────────────────────────────┤
│  6. Rewards         Mining emissions · recall-fee split      │  Live
├─────────────────────────────────────────────────────────────┤
│  5. Curation        Staking · slashing · quality oracle      │  Live
├─────────────────────────────────────────────────────────────┤
│  4. Recall          Query API · x402 paywall · MCP server    │  Live
├─────────────────────────────────────────────────────────────┤
│  3. Registry        UUPS contracts · seed metadata            │  Live
├─────────────────────────────────────────────────────────────┤
│  2. Index           HNSW vector search · Postgres mirror      │  Live
├─────────────────────────────────────────────────────────────┤
│  1. Storage         IPFS · content addressing · pinning       │  Live
└─────────────────────────────────────────────────────────────┘

1. Storage

Seeds are immutable blobs. Content is serialized to a canonical JSON shape, hashed, and pinned to IPFS. The CID is the seed's stable identifier. Pinning is redundant across at least three providers (Pinata, Filecoin via web3.storage, and the Pinecode foundation's own cluster).

Because content is hash-addressed, anyone can verify the bytes they receive match what was registered on-chain — there is no need to trust the gateway delivering them.

2. Index

On-chain registries are not searchable. Layer 2 mirrors every on-chain seed into a Postgres database, computes embeddings, and indexes them with HNSW for sub-50ms semantic search.

The default embedding model is text-embedding-3-large (3072 dim), but contributors can register seeds with their own embeddings against any registered model. Each model has its own HNSW graph.

Layer 3 — Registry

Layer 3 is a set of UUPS-upgradeable Solidity contracts on Base. The canonical entry point is PinecodeRegistry, which stores:

• Pinecode metadata (contributor, CID, embedding model, tags, created-at)
• Live recall counters (incremented per epoch)
• Decommission flags and challenge state
• Pointers to staking, payments, and reward contracts

function register(
    string calldata cid,
    bytes32 contentHash,
    uint16 embeddingModelId,
    bytes calldata tags,
    bytes calldata signature
) external returns (uint256 seedId) {
    address contributor = _verify712(cid, contentHash, signature);
    _bondFrom(contributor, BOND_AMOUNT);
    seedId = ++_nextId;
    _seeds[seedId] = Seed({
        contributor: contributor,
        cid: cid,
        contentHash: contentHash,
        embeddingModelId: embeddingModelId,
        createdAt: uint64(block.timestamp),
        tags: tags,
        decommissioned: 90">false
    });
    emit Registered(seedId, contributor, cid);
}

Layer 4 — Recall

Recall is the consumer-facing layer. A query becomes:

1. The SDK embeds the query against the chosen model
2. It POSTs to a gateway's /recall endpoint
3. The gateway returns HTTP 402 with an x402 challenge: required USDC amount, contract, chainId, recipient routing
4. The SDK signs an EIP-712 payment authorization and replays the request with the payment header
5. The gateway verifies the payment on-chain (or against a pre-funded balance), runs the HNSW query, returns results

Subsequent recalls within a window can be batched against a pre-funded balance to avoid round-trip settlement.

Layer 5 — Curation

Curators stake PINE on specific seeds. Stake-weighted quality is the signal the indexer uses to rank ties and the rewards layer uses to distribute fees.

If a curator believes a seed is low-quality, fraudulent, or violates content rules, they can submit a challenge. Challenges enter a 72-hour stake-weighted vote. Losing side is slashed; winning side splits the slashed amount.

Layer 6 — Rewards

Two reward streams flow to participants:

• Recall fees (USDC) — split per recall: 70% contributor, 20% curators (pro-rata to stake), 10% treasury
• Mining emissions (PINE) — fixed weekly issuance distributed by recall-weighted quality score, halving every 2 years

See Tokenomics for the full emission curve.

Layer 7 — Governance

Governance launches in Q3 2026. The plan: a quadratic-voting governor over upgrade proposals, parameter changes, and treasury allocation. Delegation supported; veto powers for the security council during the first 18 months.

End-to-end flow

What actually happens when an agent calls pinecode.recall(…):

Agent              SDK                 Gateway            Indexer           Registry
  │                  │                     │                  │                 │
  ├─ recall(query) ─▶│                     │                  │                 │
  │                  ├── embed(query) ─────│                  │                 │
  │                  ├─ POST /recall ─────▶│                  │                 │
  │                  │                     ├─ HNSW query ────▶│                 │
  │                  │                     │                  ├─ Merkle proof ─▶│
  │                  │                     │                  │◀─── proof ──────┤
  │                  │                     │◀── results ──────┤                 │
  │                  │◀── 402 challenge ───┤                  │                 │
  │                  ├── sign EIP-712 ─────│                  │                 │
  │                  ├─ POST + payment ───▶│                  │                 │
  │                  │                     ├─ settle USDC ──────────────────────▶
  │                  │                     │                  │                 │
  │◀── results ──────┤◀── results ─────────┤                  │                 │

Trust assumptions

Performance

Current observed numbers (rolling 7-day median, base-mainnet):

• Recall p50: 47ms (end-to-end, includes x402 settlement)
• Recall p99: 218ms
• Contribute confirmation: ~2.1s (Base block time + 1 confirmation)
• Index freshness: under 5s from registration to recallable
• Settled queries: 142 / second sustained