> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/developers/technical/contracts.md).

# Contracts

> **Status: Current for v0.5.10.** The contracts are deployed on test networks only (Base Sepolia and Gnosis Chiado, pre-audit) and released AgentLink versions use them for proofs since v0.2.0. There is no mainnet deployment; mainnet (Base, Gnosis) is planned for v1.0.0 (M3), after the external audit. The addresses below are for development and testing only. Source: [05 OCC v2 contracts](https://github.com/4thtech/agentlink/blob/v0.5.16/specs/05-contracts-occ-v2.md).

The contract source lives in a separate private repository until mainnet; it is then published under BUSL-1.1. This repository consumes only the exported ABI JSON, through the private in-repo package `@4thtech-io/occ-v2-abi` (see [Interface package](#interface-package)), and the shared test vectors.

## Contracts

| Contract      | Purpose                                                                                                                                                                                                                  | Status                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `OCCFeeVault` | Non-custodial credits (deposit, `depositFor`, EIP-3009 deposits (not enabled yet; see below), withdraw any time), fee configuration within on-chain caps, quotes, charging, treasury sweeps, integrator apps and payouts | Deployed on test networks; mainnet planned for M3 |
| `OCCNotary`   | Signature-based records and receipts; anyone can submit                                                                                                                                                                  | Deployed on test networks; mainnet planned for M3 |
| `OCCRegistry` | Verified agent cards (agent and owner binding) and revocation                                                                                                                                                            | M2                                                |
| `OCCAnchor`   | Batched Merkle roots                                                                                                                                                                                                     | M4                                                |
| `OCCDeals`    | Deal state machine                                                                                                                                                                                                       | M5                                                |

## Key interfaces

```solidity
// OCCNotary
function notarize(Record calldata r, bytes calldata sig) external returns (bytes32 recordId);
function notarizeDirect(Record calldata r) external payable returns (bytes32 recordId);
function acknowledge(Receipt calldata rc, bytes calldata sig) external;
function getRecord(bytes32 recordId) external view returns (RecordState memory);

// OCCFeeVault (credits)
function depositFor(address payer, address token, uint256 amount) external payable;
function withdraw(address token, uint256 amount, address to) external;
function creditsOf(address payer, address token) external view returns (uint256);
```

## Guarantees

The full trust model (what the contracts guarantee, what 4thTech can and cannot do, and how to check it without the source) is in [Payments, credits and trust](https://wiki.4thtech.io/protocols/occ-v2/payments-credits-and-trust.md); hands-on checks are in [Verify it yourself](https://wiki.4thtech.io/developers/technical/verify-it-yourself.md).

* No admin function can move, freeze or reduce a payer's credits; pausing blocks new charges, never withdrawals.
* Fees are bounded by on-chain caps; raising a cap has a 7-day delay; every record carries the signer's maximum fee.
* Governance by Safe multisigs through `AccessManager` with per-function delays; the Notary can be frozen against upgrades.
* Identical addresses on every chain where the contracts are deployed (CREATE3 via CreateX). Testnets and mainnets use separate deployer keys, so mainnet addresses differ from testnet addresses (owner decision D-71). Clients use only the addresses listed for each chain ID; the per-chain list is the source of truth.

## Interface package

`@4thtech-io/occ-v2-abi` (in `packages/occ-v2-abi`) is how this repository gets the contract interface. It is a private workspace package: bundled into the CLI and never published to npm on its own (D-83).

* **Where it comes from.** Each tagged release of the private contracts repository exports the interface ABIs (`IOCCNotary`, `IOCCFeeVault`, `IOCCManaged`, `IOCCErrors`, plus the OpenZeppelin errors and events the deployed contracts can raise), one address file per chain and a `manifest.json` with the SHA-256 of every file. The ABIs are generated from the Solidity interfaces, not the concrete contracts. No Solidity source is exported, and CI fails if a `.sol` file or a Solidity pragma appears anywhere in this repository.
* **How it is imported.** `node tools/occ-v2-abi/import.mjs --tag <tag> --manifest-sha256 <hash>` downloads the release assets, checks `manifest.json` against the hash printed in the release notes, checks that the tag's commit is the manifest's `sourceCommit`, checks every file against the manifest, and vendors the exact bytes of the manifest and the ABI files under `artifacts/<tag>/`. `release.json` pins the repository, tag, commit and manifest hash. The TypeScript in `src/generated/` adds only `as const` (so viem infers types) and is regenerated, never edited. The per-chain address files are not vendored verbatim: secret scanners flag a key such as `AccessManager` next to an address, so the import stores them in `src/addresses.generated.ts` with neutral field names and each address as its 40 hex digits without `0x`, and refuses unless the released bytes rebuild exactly from that form.
* **What CI checks.** On every pull request: the manifest hash equals the pin, every vendored file equals its manifest entry, no file is unlisted, only the pinned release is vendored, the generated TypeScript equals the JSON, the manifest lists address files for Base Sepolia (84532) and Gnosis Chiado (10200) only, and the generated addresses hold no `0x`-prefixed literal. `@4thtech-io/chain` rebuilds each `addresses/<chainId>.json` byte for byte from the package (sorted keys, two-space indent, final newline, as the exporter writes it) and checks its SHA-256 against the manifest; it also pins the same tag and manifest hash, pins the function selectors, event topics and error selectors of every ABI, and checks that the `Record` and `Receipt` structs the Notary takes match the EIP-712 types in `@4thtech-io/crypto`. The EIP-712 types are defined only there; the package does not repeat them. Its loader `loadOccV2Contracts(chainId)` applies viem's EIP-55 `getAddress` to every address and refuses one that is not in checksum form.
* **Client-safe subset.** The interfaces include governance, upgrade and module-only functions (all gated on chain). The package tags every function (`client`, `integrator`, `maintenance`, `admin`, `upgrade`, `module`, `relay`) and exports `occNotaryClientAbi` and `occFeeVaultClientAbi`, which hold only the `client` functions plus every event and error, for decoding. `occFeeVaultRelayAbi` holds only the `relay` function, for the submitter. Client code binds to these; the full ABIs are for decoding and review. A function added in a new release is a type error until it is tagged.
* **EIP-3009 deposits.** From `v0.1.0-testnet.4` the Base Sepolia vault accepts `depositWithAuthorization` (the gasless top-up): its address file says `depositWithAuthorization: true` and marks USDC `eip3009: true`. Gnosis Chiado says false. The function is tagged `relay`: only the submitter sends it, so it is in `occFeeVaultRelayAbi` and never in the client ABI. `@4thtech-io/chain` keeps the path off (`GASLESS_TOPUP_ENABLED = false`) until the owner-approved top-up flow ships (M3-4b-t-4); until then clients use `deposit` or `depositFor`.

Current import: `v0.1.0-testnet.4` of the contracts repository (commit `d4f4c79`), manifest SHA-256 `4d2bfc98e71da1ed3b60fed574c0333ee945a17e701e32bfab10d6cab5bb436e`.

## Addresses

**Testnet only.** These are the pre-audit Base Sepolia deployment (14 Oct 2026), for development and testing; they hold no real value and may be redeployed. The source of truth is the release's `addresses/84532.json`, carried by `@4thtech-io/occ-v2-abi` (`getDeployment(84532)`) and checked against the release manifest; there is no mainnet entry, and CI refuses one.

| Chain        | Chain ID | Contract              | Address                                      |
| ------------ | -------- | --------------------- | -------------------------------------------- |
| Base Sepolia | 84532    | `OCCNotary` (proxy)   | `0xB29dEdEe26D480105DAD5b90f549a09d376d855F` |
| Base Sepolia | 84532    | `OCCFeeVault` (proxy) | `0x91A40104553Bd1731c3fBe05209A908B40e50f8d` |
| Base Sepolia | 84532    | `AccessManager`       | `0x7B05B6C56E4f073df60da9Fa640b1f7ffCD9D3A2` |

Fee token on Base Sepolia: test USDC `0x036CbD53842c5426634e7929541eC2318f3dCF7e` (6 decimals; EIP-3009 deposits not enabled yet). On Gnosis Chiado the fee asset is native xDAI, at the same contract addresses (smoke test passed 21 Oct 2026); see [Networks and contract addresses](https://wiki.4thtech.io/deployments/networks-and-contracts.md). Mainnet addresses differ from testnet addresses (D-71) and are published with the mainnet release (M3).

## Outline (to come)

* Full ABI reference and events
* Addresses for mainnet (planned for M3)
* Roles, delays and governance
* Audit reports (after fixes)

**Planned for:** the mainnet release (M3).
