Documentation
Architecture
Profile v1Contract v0.5
Components, trust boundaries and the independent verification path.
Layers
| Layer | Responsibility | Status |
|---|---|---|
| Agent runtime | Your code; calls the SDK at steps and actions | Yours |
| SDK | Serialize, encrypt, upload, commit, verify, gate actions, recover | Tested on Robinhood Chain testnet |
| Storage | Encrypted artifacts and manifests (IPFS, Arweave; a local adapter for development) | IPFS tested live (Filebase); Arweave against a mock gateway |
| Contract | Commitments, lineage, executors and guardians, recovery proposals, pause | Deployed on Robinhood Chain; internal review, audit planned |
| Services (API, indexer) | Convenience: history, analytics, verification and recovery jobs. Never the authority | Hosted |
What is recorded where
On-chain, each checkpoint stores its hash, parent, stateHash, traceHash and the hash of its locator. The traceHash is the keccak-256 of a canonical manifest that names the execution, checkpoint type, policy, runtime versions, actions and the encrypted artifact's digest. The exact mapping is the checkpoint profile (docs/CHECKPOINT-PROFILE.md).
Off-chain, storage holds the public manifest (hashes and identifiers only) and the encrypted artifact (state, context, execution status). The operation journal stays with the agent.
Trust boundaries
- The contract decides lineage and who may submit or recover; nothing off-chain can override it.
- Storage is untrusted: every object read is checked against its committed digest.
- The encryption key holder can read the agent's context. Revoking access later cannot erase plaintext already read.
- A checkpoint proves which bytes an authorised key committed to, not that the agent computed them correctly.
Independent verification
With only an RPC endpoint and storage access, no Upoch service:
- Read the checkpoint and its
CheckpointSubmittedevent. - Check that the event's locator hashes to
dataURIHashand that the checkpoint hash recomputes. - Fetch the manifest and check it against
traceHash; fetch the artifact and check its digest. - If authorised to decrypt, check the state and context hashes.
shell (Python SDK)
python -m epoch_sdk verify --rpc $RPC_URL --ledger $EPOCH_ADDRESS \
--workflow 1 --from-block 96839623 --ipfs-gateway https://ipfs.filebase.ioA missing object is reported as unavailable, never as a mismatch.