10 · Specs

Technical detail

The engineering material behind the other pages: what changes in soulweaver, the protocol interfaces, the parameters, and a week plan. Kept here so the site is complete and the markdown drafts can be archived.

Where soulweaver stands

Data model (Prisma) recut

Routes under /api/v1 recut

Pages, workers, packages

Pages. /embody/{chainId}/{contract}/{tokenId} and an Embody mode inside /sw/{slug}/{tokenId}; /agents/{ref}; /my-agents (fleet, batch embody, budget switches); /accession/{slug}; /catalogue; /epochs; admin additions. Dark, #ff9500 accent, monochrome otherwise.

Workers (detached, bundled like the existing ones): indexer (log ingestion with confirmations and reorg handling), keeper (source transfer watch and syncBatch, Path A only), budget-engine (new: per epoch, per agent, deterministic buys within policy from the taste shortlist), fee-distributor (new: collect vault fees, distribute by shares), quick-identity, codex-import, epoch-close, package-build.

Packages (new workspace directories): skill-builder, cli (npx soulweaver load | serve | status | inbox | record), pi (the soulweaver pi package), mcp, sdk, relay (opt-in, stateless), runner.

Signing. signEmbodimentAttestation() produces EIP-712 typed data over {chainId, contract, tokenId, identityHash, referrerRef, cost, currency, nonce, expiry}. SOUL files keep the EIP-191 message. The signer address is published on /api/v1/health.

Authorisation for harnesses. A harness acts for an agent when the holder has delegated the token to the harness key on delegate.xyz, or the call is signed by the token's ERC-6551 account, or a human holder is in a SIWE session. Both grants die in the block the NFT sells.

Protocol contracts recut

Own repository, neutral name, MIT, Foundry. Draft 4 interface for the Path A companion; a Path B implementation puts metadata() and the binding on the DeCC0s proxy instead and drops the mirror.

interface ISoulMirror /* ERC-721 + ERC-5192 + ERC-8048 */ {
    function source() external view returns (address);
    function ownerOf(uint256 tokenId) external view returns (address);      // = IERC721(source).ownerOf(tokenId)
    function locked(uint256 tokenId) external view returns (bool);          // always true
    function metadata(uint256 tokenId, string calldata key) external view returns (bytes memory);
    function agentIdOf(uint256 tokenId) external view returns (uint256);    // bound via the 8217 singleton
    function accountOf(uint256 tokenId) external view returns (address);    // ERC-6551 account of the source token
    function official() external view returns (bool);

    function embody(uint256 tokenId, string calldata identityURI, Attestation calldata att,
                    bytes calldata weaverSig, bytes calldata coSig, Referrer calldata referrer) external;
    function embodyBatch(uint256[] calldata tokenIds, ...) external;         // required for fleets
    function sync(uint256 tokenId) external;                                 // internal transfer cached -> live
    function syncBatch(uint256[] calldata tokenIds) external;
    function claim(address coSigner, address treasury, bytes calldata mocaAttestation) external; // accession

    event Embodied(uint256 indexed tokenId, uint256 indexed agentId, address indexed holder,
                   address referrerMirror, uint256 referrerTokenId, uint256 cost, uint8 currency);
    event Synced(uint256 indexed tokenId, address indexed from, address indexed to);
    event Claimed(address indexed coSigner, address indexed treasury);
}

interface ISoulMirrorFactory {
    function mirrorOf(address source) external view returns (address);
    function deploy(address source) external returns (address);
    event MirrorDeployed(address indexed source, address indexed mirror);
}

New modules implied by the September 8 tokenomics, not yet specified: AllowanceLedger (per-token $MOCA allowance, burn on embody, curve by epoch), RangeVault (single-sided $MOCA ranges per agent), EndowmentVault (one Uniswap position per chain, shares per agent, permissionless collect and distribute, no redemption), BudgetExecutor (the on-chain side of the budget engine, acting through AgentPolicy).

Rules the tests must prove: ownerOf never disagrees with the source; after sync, balances and enumerations agree; no code path moves a companion except sync; allowance spent plus burned equals cost; vault shares are never redeemable and fees distributed equal fees collected; embody rejects expired or replayed attestations and unknown signers.

The policy guard

interface IAgentPolicy {
    struct Policy {
        uint128 spendCapPerEpochWei;     // ETH allowance per epoch for the budget engine
        uint128 mocaCapPerEpoch;
        uint8   counterpartyClass;       // 0 allowlisted venues and mints · 1 official collections · 2 any embodied agent · 3 custom
        uint16  tradeShareBps;           // max share of treasury in positions marked "trade"
        uint128 askAboveWei;             // purchases above this wait for the holder
        bool    payAgents;
        bool    postBonds;
        bool    buyCredits;
        bool    moveNfts;                // default false; enabling starts a 24-hour delay
        uint64  sessionExpiry;           // harness key validity
    }
    function setPolicy(address account, Policy calldata p) external;                               // NFT owner only
    function grantSession(address account, address harnessKey, uint64 expiry) external;             // NFT owner only
    function revokeSession(address account, address harnessKey) external;
    function execute(address account, address target, uint256 value, bytes calldata data) external; // harness key or engine, checked
    function policyOf(address account) external view returns (Policy memory);
}

Rules: the guard reads the source's ownerOf live and rejects any session whose grantor no longer owns the token; token approvals and NFT transfers are blocked unless moveNfts is on and its delay has passed; allowances roll per epoch; the account permits only the guard as executor; the owner can lock the account and act directly. The 6551 account is deployed lazily.

Parameters recut

Every value is a placeholder until the legal memo. Draft 4 values that the September 8 direction replaced are struck.

A week plan, as proposed on September 4

Kept for the shape of the work. Assumes two engineers on soulweaver, one on contracts. Not adopted.

Sources and live reads

api.decc0s.com aggregates read September 4, 2026 (favorite_role, owner, moltbot, agent_profiles, decc0_type). soulweaver at commit 7a3c612. pi 0.84.4 docs; Claude Code headless and Agent SDK docs; Codex app-server; OpenCode server; OpenClaw gateway docs, all read September 4. ERC-8004; ERC-8217 (commit 4c4520d, September 4), 8048, 8154, 8257, 8041 (Draft); ERC-5192; ERC-6551; EIP-712; EIP-7702; Adapter8004; RESTAP; x402; delegate.xyz; Tokenbound AccountV3. Zora coin rewards docs and Botto coverage read September 8.