Protocol

Seeds

The atomic unit of memory in the network. What a seed is, how it's structured, and how it's verified.

Anatomy

Every seed has two parts: an off-chain payload stored on IPFS, and on-chain metadata stored in the Registry.

seed-payload.json

typescript

{
  class="text-success/90">"version": class="text-success/90">"1.0.0",
  class="text-success/90">"title": class="text-success/90">"ERC-4337 Paymaster Lifecycle",
  class="text-success/90">"content": class="text-success/90">"The Paymaster contract sponsors gas for UserOperations…",
  class="text-success/90">"source": class="text-success/90">"https:class="text-fg-subtle italicclass="text-success/90">">//eips.ethereum.org/EIPS/eip-4337",
  class="text-success/90">"embedding": {
    class="text-success/90">"model": class="text-success/90">"openai/text-embedding-3-large",
    class="text-success/90">"dim": 3072,
    class="text-success/90">"vectorCid": class="text-success/90">"bafybeihfbgks5q8wnxhk7m3rqfg…"
  },
  class="text-success/90">"tags": [class="text-success/90">"ethereum", class="text-success/90">"account-abstraction", class="text-success/90">"erc-4337"],
  class="text-success/90">"license": class="text-success/90">"CC-BY-4.0",
  class="text-success/90">"contributor": class="text-success/90">"0xa12b…",
  class="text-success/90">"signature": class="text-success/90">"0xabc…"
}

The on-chain record is much smaller:

solidity

struct Seed {
    address contributor;
    string  cid;             class=class="text-success/90">"text-fg-subtle italic">// IPFS CID of the payload
    bytes32 contentHash;     class=class="text-success/90">"text-fg-subtle italic">// keccak256 of canonical bytes
    uint16  embeddingModelId;
    uint64  createdAt;
    bytes   tags;            class=class="text-success/90">"text-fg-subtle italic">// packed bytes32 tag IDs
    bool    decommissioned;
}

iWhy split?

Storing full content on-chain would be wildly expensive. Splitting lets us anchor proof on-chain (cheap) while keeping bytes on IPFS (cheap, addressable, verifiable).

Lifecycle

Compose. Contributor writes content, picks tags, signs the payload.
Pin. Payload is uploaded to IPFS via the gateway's pinning service.
Register. Gateway relays a meta-tx to PinecodeRegistry.register(…).
Index. Indexer nodes pick up the event, fetch the payload, embed, insert into HNSW.
Recall. Agents query, your seed surfaces, contributor and curators earn.
(Optional) Challenge. Anyone can challenge a seed; stake-weighted vote decides.
Decommission. Contributor (or governance) retires the seed; bond returned.

Verifying a seed

You can verify a seed entirely client-side, without trusting any gateway:

typescript

import { verifySeed } from class="text-success/90">"@pinecode/sdk";
const ok = await verifySeed({
  seedId: 418293,
  payload, class=class="text-success/90">"text-fg-subtle italic">// the bytes fetched from any IPFS gateway
  rpcUrl: class="text-success/90">"https:class="text-fg-subtle italicclass="text-success/90">">//mainnet.base.org",
});
if (!ok) throw new Error(class="text-success/90">"seed tampered");

The verify function:

Hashes the payload bytes
Reads contentHash and contributor from the registry
Recovers the signer from the EIP-712 signature in the payload
Confirms all three match

Size limits

Field	Limit
`title`	200 chars
`content`	32 KB (encoded UTF-8)
`tags`	16 tags max, 32 chars each
Payload total	48 KB
Embedding vectors	any (stored as separate CID)

For longer documents, split into multiple seeds and link via the source field.

Edit this page on GitHub →

Docs v0.6.2