RPC Reference

All Cocoon RPC methods are available via the standard JSON-RPC 2.0 interface at the backend proxy endpoint (http://localhost:8546 by default). Every method follows the same envelope format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "namespace_methodName",
  "params": [...]
}

Standard Ethereum namespaces (eth_, net_, web3_) are also available and behave as per the Ethereum JSON-RPC specification.

All addresses are checksummed hex strings (0x...). All amounts are QUANTITY values (hex-encoded integers) unless otherwise noted. All hashes are DATA values (hex-encoded byte arrays).

---

token_ — Permissioned Tokens

The token_ namespace provides the full lifecycle for ERC-3643 permissioned tokens: deployment, minting, transfers, compliance, NAV publishing, and document management.

Most write methods on this namespace require an authenticated session. Pass a valid bearer token in the Authorization header when calling the backend proxy, or set AUTH_MODE=advisory for development.

Deployment

token_deploy

Deploy a new ERC-3643 permissioned token contract.

Field	Value
Params	[deployParams: TokenDeployParams]
Returns	{ address: ADDRESS, txHash: HASH }

// TokenDeployParams
{
  "name": "string",
  "symbol": "string",
  "decimals": "QUANTITY",
  "owner": "ADDRESS",
  "identityRegistry": "ADDRESS",
  "compliance": "ADDRESS"
}

---

Minting and Burning

token_mint

Mint tokens to a single address. Requires the caller to have the Operator or Admin role.

Field	Value
Params	[token: ADDRESS, to: ADDRESS, amount: QUANTITY]
Returns	{ txHash: HASH }

token_batchMint

Mint tokens to multiple addresses in a single transaction.

Field	Value
Params	[token: ADDRESS, recipients: ADDRESS[], amounts: QUANTITY[]]
Returns	{ txHash: HASH }

token_burn

Burn tokens from an address. The caller must own the tokens or have an approved allowance.

Field	Value
Params	[token: ADDRESS, from: ADDRESS, amount: QUANTITY]
Returns	{ txHash: HASH }

---

Token Controls

token_pause

Pause all transfers on a token. Only callable by the token owner.

Field	Value
Params	[token: ADDRESS]
Returns	{ txHash: HASH }

token_freeze

Freeze transfers to or from a specific address.

Field	Value
Params	[token: ADDRESS, address: ADDRESS, frozen: boolean]
Returns	{ txHash: HASH }

token_forcedTransfer

Execute a forced transfer between two addresses, bypassing standard compliance checks. Requires Admin role. Used for regulatory recovery scenarios.

Field	Value
Params	[token: ADDRESS, from: ADDRESS, to: ADDRESS, amount: QUANTITY]
Returns	{ txHash: HASH }

token_recovery

Recover tokens from a lost wallet by transferring the full balance to a new address. Both the old and new addresses must have verified identities linked to the same investor record.

Field	Value
Params	[token: ADDRESS, lostWallet: ADDRESS, newWallet: ADDRESS, investorOnchainId: ADDRESS]
Returns	{ txHash: HASH }

token_canTransfer

Dry-run a transfer to check whether compliance rules permit it, without submitting a transaction.

Field	Value
Params	[token: ADDRESS, from: ADDRESS, to: ADDRESS, amount: QUANTITY]
Returns	{ allowed: boolean, reason: string | null }

---

Investor Onboarding

token_onboardInvestor

Register an investor address against the token's identity registry. The investor must already have an on-chain identity (see id_createIdentity).

Field	Value
Params	[token: ADDRESS, investor: ADDRESS, identity: ADDRESS]
Returns	{ txHash: HASH }

token_getHolders

Return a paginated list of current token holders with their balances.

Field	Value
Params	[token: ADDRESS, offset?: QUANTITY, limit?: QUANTITY]
Returns	{ holders: [{ address: ADDRESS, balance: QUANTITY }], total: QUANTITY }

token_getHolder

Return detailed information for a single holder.

Field	Value
Params	[token: ADDRESS, address: ADDRESS]
Returns	{ address: ADDRESS, balance: QUANTITY, frozen: boolean, identity: ADDRESS | null }

token_getTokenInfo

Return static and dynamic metadata for a token.

Field	Value
Params	[token: ADDRESS]
Returns	{ name: string, symbol: string, decimals: QUANTITY, totalSupply: QUANTITY, paused: boolean, owner: ADDRESS, compliance: ADDRESS, identityRegistry: ADDRESS }

---

NAV and Pricing

token_publishNAV

Publish a new Net Asset Value for a fund token. The NAV is stored on-chain and used by subscription/redemption calculations.

Field	Value
Params	[token: ADDRESS, navPerShare: QUANTITY, timestamp: QUANTITY]
Returns	{ txHash: HASH }

token_publishPrice

Publish a generic price feed entry for a token (used for non-NAV instruments such as bonds or stablecoins with FX rates).

Field	Value
Params	[token: ADDRESS, price: QUANTITY, currency: string, timestamp: QUANTITY]
Returns	{ txHash: HASH }

token_getFeedHistory

Retrieve historical NAV or price feed entries.

Field	Value
Params	[token: ADDRESS, fromTimestamp: QUANTITY, toTimestamp: QUANTITY, limit?: QUANTITY]
Returns	{ entries: [{ value: QUANTITY, currency: string, timestamp: QUANTITY, txHash: HASH }] }

---

Compliance Modules

token_addComplianceModule

Attach a compliance module contract to a token. Modules are called on every transfer and can block or modify it.

Field	Value
Params	[token: ADDRESS, module: ADDRESS]
Returns	{ txHash: HASH }

token_setCountryAllowList

Configure the country allow-list compliance module. Only investors with identity claims matching an allowed country code can hold the token.

Field	Value
Params	[token: ADDRESS, allowedCountryCodes: QUANTITY[]]
Returns	{ txHash: HASH }

token_setMaxBalance

Set the maximum token balance any single investor may hold.

Field	Value
Params	[token: ADDRESS, maxBalance: QUANTITY]
Returns	{ txHash: HASH }

---

Document Management

token_publishDocument

Attach a document to a token. The document content is stored via the torrent layer; only the content hash and metadata are stored on-chain.

Field	Value
Params	[token: ADDRESS, name: string, docType: string, uri: string, contentHash: HASH]
Returns	{ txHash: HASH, docId: HASH }

token_getDocument

Retrieve a document record by ID.

Field	Value
Params	[token: ADDRESS, docId: HASH]
Returns	{ name: string, docType: string, uri: string, contentHash: HASH, publishedAt: QUANTITY }

token_listDocuments

List all documents attached to a token.

Field	Value
Params	[token: ADDRESS]
Returns	{ documents: [{ docId: HASH, name: string, docType: string, uri: string, publishedAt: QUANTITY }] }

---

Subscriptions and Redemptions

token_subscribe

Subscribe to a fund token by exchanging a stablecoin amount for token shares at the current NAV.

Field	Value
Params	[token: ADDRESS, stableAmount: QUANTITY]
Returns	{ txHash: HASH, sharesIssued: QUANTITY }

token_redeem

Redeem token shares for the underlying stablecoin at the current NAV.

Field	Value
Params	[token: ADDRESS, shares: QUANTITY]
Returns	{ txHash: HASH, stableReturned: QUANTITY }

---

id_ — Identity

The id_ namespace manages on-chain identities, claims, and claim access control using the OnchainID / ERC-734/735 standard.

id_createIdentity

Deploy a new on-chain identity contract for an investor address.

Field	Value
Params	[owner: ADDRESS, managementKeys?: HASH[]]
Returns	{ identity: ADDRESS, txHash: HASH }

id_issueClaim

Issue a signed claim to an identity. The caller must be a trusted claim issuer registered in the TrustedIssuersRegistry.

Field	Value
Params	[identity: ADDRESS, topic: QUANTITY, scheme: QUANTITY, data: DATA, uri: string]
Returns	{ claimId: HASH, txHash: HASH }

The topic field uses the ERC-735 claim topic registry. Common topics:

Topic (decimal)	Meaning
1	KYC/AML verification
2	Accredited investor status
3	Country of residence
4	Professional investor classification
101	Specific token eligibility

id_getClaim

Retrieve a claim by its ID.

Field	Value
Params	[identity: ADDRESS, claimId: HASH]
Returns	{ claimId: HASH, topic: QUANTITY, scheme: QUANTITY, issuer: ADDRESS, data: DATA, uri: string, signature: DATA }

id_grantClaimAccess

Grant a third party (e.g. a regulator or auditor) read access to an encrypted claim document stored via the torrent layer.

Field	Value
Params	[identity: ADDRESS, claimId: HASH, grantee: ADDRESS, encryptedKey: DATA]
Returns	{ txHash: HASH }

id_revokeClaim

Revoke a previously issued claim.

Field	Value
Params	[identity: ADDRESS, claimId: HASH]
Returns	{ txHash: HASH }

id_getIdentity

Look up the on-chain identity address for a wallet address.

Field	Value
Params	[address: ADDRESS]
Returns	{ identity: ADDRESS | null, owner: ADDRESS | null }

---

auth_ — Authorization

The auth_ namespace exposes the UCAN capability system. UCAN delegations are encoded as JWTs and attached to transactions via EIP-8141 frame envelopes.

auth_createDelegation

Create a UCAN capability delegation, granting an audience address the ability to invoke specified methods on behalf of the issuer.

Field	Value
Params	[issuer: ADDRESS, audience: ADDRESS, capabilities: Capability[], expiration?: QUANTITY]
Returns	{ delegation: string, cid: HASH }

// Capability
{
  "with": "cocoon:token/0xTokenAddress",
  "can": "token/transfer"
}

auth_verify

Verify that a delegation JWT is valid, unexpired, and not revoked.

Field	Value
Params	[delegation: string]
Returns	{ valid: boolean, issuer: ADDRESS, audience: ADDRESS, capabilities: Capability[], expiration: QUANTITY | null }

auth_inspect

Decode and return the contents of a delegation JWT without verifying chain or revocation status.

Field	Value
Params	[delegation: string]
Returns	{ issuer: ADDRESS, audience: ADDRESS, capabilities: Capability[], expiration: QUANTITY | null, notBefore: QUANTITY | null }

auth_revoke

Revoke a previously issued delegation. Writes the delegation CID to the on-chain revocation registry.

Field	Value
Params	[cid: HASH]
Returns	{ txHash: HASH }

---

qm_ — QMTree State

The qm_ namespace exposes the QMTree Merkle state commitment. QMTree is the core data structure used to generate ZK proofs and verify state transitions.

qm_getRoot

Return the current QMTree root hash at a given block.

Field	Value
Params	[blockNumber?: QUANTITY]
Returns	{ root: HASH, blockNumber: QUANTITY, txNum: QUANTITY }

qm_getLeaf

Return the value and position of a leaf node in the QMTree.

Field	Value
Params	[key: DATA, blockNumber?: QUANTITY]
Returns	{ key: DATA, value: DATA, leafIndex: QUANTITY, twig: HASH }

qm_getProof

Return a Merkle inclusion proof for a leaf node.

Field	Value
Params	[key: DATA, blockNumber?: QUANTITY]
Returns	{ proof: HASH[], root: HASH, leafIndex: QUANTITY, value: DATA }

qm_call

Execute a read-only contract call against the QMTree state at a given root (without requiring the full chain state). Used for off-chain verification workflows.

Field	Value
Params	[to: ADDRESS, data: DATA, root: HASH]
Returns	{ result: DATA }

qm_callProof

Execute a contract call and return both the result and a proof of correct execution against the given QMTree root.

Field	Value
Params	[to: ADDRESS, data: DATA, root: HASH]
Returns	{ result: DATA, proof: ExecutionProof }

qm_verifyProof

Verify an execution proof against a given QMTree root without re-executing the call.

Field	Value
Params	[root: HASH, proof: ExecutionProof]
Returns	{ valid: boolean }

qm_getKeyProof

Return a proof of the current value bound to a key, suitable for use in a SNARK circuit.

Field	Value
Params	[key: DATA, blockNumber?: QUANTITY]
Returns	{ proof: HASH[], root: HASH, key: DATA, value: DATA }

qm_getExclusionProof

Return a proof that a key does not exist in the QMTree (non-membership proof).

Field	Value
Params	[key: DATA, blockNumber?: QUANTITY]
Returns	{ proof: HASH[], root: HASH, key: DATA }

---

proof_ — ZK Proofs

The proof_ namespace manages ZK proof generation, batching, and status queries. Proofs are generated by the Zilkworm prover and posted to Ethereum by the proof pipeline.

proof_getProof

Return the ZK proof for a specific block.

Field	Value
Params	[blockNumber: QUANTITY]
Returns	{ blockNumber: QUANTITY, proof: DATA, status: ProofStatus, postedAt: QUANTITY | null, ethTxHash: HASH | null }

ProofStatus values: pending, generating, ready, posted, failed.

proof_getProofStatus

Return only the status of a proof, without the proof data itself.

Field	Value
Params	[blockNumber: QUANTITY]
Returns	{ blockNumber: QUANTITY, status: ProofStatus, generatedAt: QUANTITY | null }

proof_getBatchProof

Return the aggregate ZK proof for a batch of blocks.

Field	Value
Params	[fromBlock: QUANTITY, toBlock: QUANTITY]
Returns	{ fromBlock: QUANTITY, toBlock: QUANTITY, proof: DATA, root: HASH, status: ProofStatus }

proof_getLatestProved

Return the block number and state root of the most recently proved (and Ethereum-posted) block.

Field	Value
Params	[]
Returns	{ blockNumber: QUANTITY, stateRoot: HASH, ethTxHash: HASH, postedAt: QUANTITY }

---

erigon_ — Storage and WebF Extensions

The erigon_ namespace exposes Cocoon's extended storage and web hosting capabilities: torrent-backed document storage and on-chain web site publishing via WebF.

Torrent Storage

erigon_resolveTorrent

Resolve a torrent-ccip content reference to its current download metadata.

Field	Value
Params	[infoHash: HASH]
Returns	{ infoHash: HASH, name: string, files: [{ name: string, size: QUANTITY, path: string }], trackers: string[], magnetURI: string }

erigon_publishTorrent

Publish a new torrent and write its on-chain content reference. The file data must be accessible to the node's torrent storage backend.

Field	Value
Params	[files: [{ name: string, data: DATA }], announce?: string[]]
Returns	{ infoHash: HASH, magnetURI: string, txHash: HASH }

erigon_getInscription

Retrieve an on-chain inscription (small content blob written directly into a transaction's calldata via EIP-8141 frame).

Field	Value
Params	[txHash: HASH]
Returns	{ txHash: HASH, contentType: string, data: DATA, size: QUANTITY }

WebF — On-Chain Web Hosting

erigon_publishWebSite

Publish a static web site by bundling its files into a torrent and writing the content root on-chain. The site is then accessible via the WebF gateway.

Field	Value
Params	[name: string, files: [{ path: string, data: DATA, contentType: string }], owner: ADDRESS]
Returns	{ siteId: HASH, infoHash: HASH, txHash: HASH, gatewayURL: string }

erigon_getWebSite

Retrieve metadata for a published web site.

Field	Value
Params	[siteId: HASH]
Returns	{ siteId: HASH, name: string, owner: ADDRESS, infoHash: HASH, publishedAt: QUANTITY, lastUpdated: QUANTITY, gatewayURL: string }

erigon_listWebSites

List all published web sites, optionally filtered by owner.

Field	Value
Params	[owner?: ADDRESS, offset?: QUANTITY, limit?: QUANTITY]
Returns	{ sites: [{ siteId: HASH, name: string, owner: ADDRESS, publishedAt: QUANTITY }], total: QUANTITY }

---

Error Codes

All methods return standard JSON-RPC errors. Cocoon-specific error codes:

Code	Name	Description
-32001	TransferNotAllowed	A token_* write was blocked by a compliance rule. The message field contains the reason.
-32002	IdentityNotFound	The target address has no registered on-chain identity.
-32003	ClaimMissing	A required claim (KYC, accreditation, etc.) is absent or expired.
-32004	DelegationInvalid	A UCAN delegation is malformed, expired, or revoked.
-32005	ProofNotReady	The requested ZK proof has not been generated yet.
-32006	TorrentUnavailable	The requested torrent content is not available from any peer.
-32007	Unauthorized	The request lacks a valid session token and AUTH_MODE=strict is set.