Pacto Protocol Contract Address Book and Configuration

Pacto’s on-chain contracts are tracked in a single JSON file — src/lib/evm/pacto-protocol-addresses.json — that serves as the canonical address book for both the Rust backend and the TypeScript frontend. The backend embeds the file at compile time; the frontend imports it via src/lib/evm/pacto-protocol-addresses.ts. This single-source approach prevents the address skew that arises when contract addresses are duplicated across environment files, components, and configuration layers.

Source of truth

Concern	Where
Address book (JSON)	`src/lib/evm/pacto-protocol-addresses.json`
Rust embed	`include_str!` in `src-tauri/src/evm/pacto_chain_config.rs`
Frontend import	`src/lib/evm/pacto-protocol-addresses.ts`
Runtime override	`PACTO_*` environment variables (see Environment Variables)

The Rust module exposes three address-resolution helpers used by all deploy and read commands:

pacto_gov_deploy_addresses(net_key)
squad_sponsor_deploy_addresses(net_key)
safe_factory_addresses(net_key, chain_id)

Resolution order for each field: PACTO_* env override → JSON address book → error (required fields) or safe-global defaults (Safe factory only).

Because the address book is embedded at compile time with include_str!, any change to pacto-protocol-addresses.json requires a rebuild of the Tauri backend (cargo check or cargo build in src-tauri/) before the new addresses are active. Runtime PACTO_* env overrides are the exception — they take effect without a rebuild.

Example: Sepolia address book

The file ships with the covenant-gov Sepolia deployment (chain ID 11155111). Below is the full current content of pacto-protocol-addresses.json as a concrete reference:

{
  "$comment": "Pacto protocol deploy infra per network. Rust Alloy UX reads this at compile time; optional PACTO_* env vars override for local experiments. Sepolia bundle: covenant-gov deploy (chainId 11155111).",
  "version": 1,
  "networks": {
    "sepolia": {
      "chainId": 11155111,
      "meta": {
        "deployer": "0x6522cE18D0098A2f98fB6E4a40C081F16d9a71e7"
      },
      "squadSponsor": {
        "factory": "0x3994B38f9A0Cf542241FD9C959F94386e6733D6e",
        "paymaster": "0x42C76dEbCF45507532B22Ca890C9091240311bD8",
        "entryPoint": "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
        "navePirataRegistry": "0x45127C1c92741C0dA38e1A73fbb97a8a2C46770f"
      },
      "pactoGov": {
        "navePirataFactory": "0x44E42cf7b2DadDe6D5fc27B57625EaF3e3D41316",
        "navePirataRegistry": "0x45127C1c92741C0dA38e1A73fbb97a8a2C46770f",
        "masterQuartermaster": "0xE9C111428E23bd68C892785A6566DFc160358af1",
        "masterMutiny": "0xeA647c49a3594EEb3Cf0f38f705F34e036d3733B",
        "masterTreasuryAuthority": "0x3AfD425EEFC54d4d97f610C47D4a3cEAE0FeC298",
        "masterSquadAdminImpl": "0x85A7B39ED76b84efd85619F6df939c711b14DB54",
        "masterSquadAdminExtImpl": "0x55B4e8df8DC23e4f414025e252Db26cbA22e25F1",
        "hats": "0x3bc1A0Ad72417f2d411118085256fC53CBdDd137",
        "roleHatClonesFactory": "0xB240e490980b3EF11c30d7476a40f43B3311Ad58",
        "roleHatUpgrader": "0x327f1B3cdcabe6F1BC934bed768032B7b42906f7"
      },
      "safe": {
        "proxyFactory": "0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67",
        "singleton": "0x41675C099F32341bf84BFc5382aF534df5C7461a",
        "fallbackHandler": "0x017062a1dE2FE6b99BE3d9d37841FeD19F573804"
      }
    }
  }
}

Contract ecosystem

The following sections describe each contract system tracked in the address book.

pacto-gov — governance contract

pacto-gov implements the Nave Pirata governance framework: modular voting, SquadAdmin executor roles, and hat-governed permissions. Sources are not vendored in this repo.

Detail	Value
Source repository	github.com/covenant-gov/pacto-gov (`dev` branch)
Alloy bindings	`src-tauri/src/evm/contracts/pacto_gov/mod.rs`
Address section	`pactoGov` in `pacto-protocol-addresses.json`

Address fields (per network):

Field	Description
`navePirataFactory`	Deploys new Nave Pirata governance instances
`navePirataRegistry`	Registry of all deployed Nave Pirata instances
`masterQuartermaster`	Master copy for the Quartermaster executor role
`masterMutiny`	Master copy for the Mutiny module
`masterTreasuryAuthority`	Master copy for the TreasuryAuthority module
`masterSquadAdminImpl`	Master copy for the SquadAdmin implementation
`masterSquadAdminExtImpl`	Master copy for the extended SquadAdmin implementation
`hats`	Hats Protocol contract (see Hats Protocol below)
`roleHatClonesFactory`	Factory for role-hat clone contracts
`roleHatUpgrader`	Upgrader utility for role-hat contracts

When upstream interfaces change, update the hand-maintained sol! bindings in evm/contracts/pacto_gov/ against the reviewed commit on GitHub. An optional pacto_gov_revision field on governance rows records the upstream git commit SHA as an audit trail without requiring a submodule pin. pacto-squad-sponsor provides a per-squad paymaster clone factory built on ERC-4337. Each squad gets its own paymaster clone; gas sponsorship is scoped to the squad that funds it.

Detail	Value
Source repository	github.com/covenant-gov/pacto-squad-sponsor (`dev` branch)
Alloy bindings	`src-tauri/src/evm/contracts/pacto_sponsor/mod.rs`
Deploy / read commands	`squad_sponsor_deploy.rs`, `squad_sponsor_deposit.rs`, `squad_sponsor_read.rs`
Address section	`squadSponsor` in `pacto-protocol-addresses.json`
Persistence	`squad_infra` SQLite rows (`infra_type: sponsor`)

Address fields (per network):

Field	Description
`factory`	`ISquadSponsorFactory` — deploys per-squad paymaster clones
`paymaster`	Shared paymaster implementation used by clones
`entryPoint`	ERC-4337 EntryPoint contract (canonical singleton)
`navePirataRegistry`	Shared with `pactoGov` — links sponsor to governance registry

Squad ID derivation: The on-chain squad key is derived deterministically from the app-level squad identifier:

squadId = keccak256(utf8(parent_id))

where parent_id is the squad or network root ID used within the Pacto app. First-ship path: ISquadSponsorFactory.createSquadSponsorExt(squadId) — deploys an address-list Ext clone with no hat-tree dependency.

Gnosis Safe — multi-sig treasury

Gnosis Safe contracts provide the multi-sig treasury backing for squad funds. Pacto uses Safe 1.4.x.

Detail	Value
Alloy bindings	`src-tauri/src/evm/contracts/safe/mod.rs`
Address section	`safe` in `pacto-protocol-addresses.json`
Used for	Squad treasury management, Safe proposal signing flows

Address fields (per network):

Field	Description
`proxyFactory`	Safe proxy factory — deploys new Safe instances
`singleton`	Safe 1.4.x singleton (implementation contract)
`fallbackHandler`	Default fallback handler for new Safe proxies

For networks not explicitly listed in the JSON, safe_factory_addresses() falls back to canonical safe-global defaults. These are the only fields with a built-in fallback; all pactoGov and squadSponsor fields are required.

Hats Protocol — on-chain role management

Hats Protocol provides on-chain role NFTs used for SquadAdmin permissions and executor gates in the pacto-gov system.

Detail	Value
Alloy bindings	`src-tauri/src/evm/contracts/hats/mod.rs`
Address in JSON	`pactoGov.hats` (per network)
Used for	SquadAdmin role enforcement, executor gates, hat-governed permissions

The hats address lives inside the pactoGov block because it is deployed as part of the pacto-gov bundle. The same address is referenced by roleHatClonesFactory and roleHatUpgrader.

ERC-20 tokens — USDC and USDT per network

Token addresses are not part of pacto-protocol-addresses.json. They are defined in src/lib/wallet/wallet-assets.json, which is the canonical source for per-network token contract addresses, decimals, and display metadata. The Rust backend mirrors this via src-tauri/src/evm/wallet_chain_config.rs (embedded with include_str!).

Detail	Value
Alloy bindings	`src-tauri/src/evm/contracts/erc20/mod.rs`
Address source	`wallet-assets.json` → `wallet_chain_config.rs` (backend) / `assets.ts` (frontend)
Tokens	USDC, USDT (per supported network)

Do not duplicate token addresses in components. Use the WALLET_ASSETS helpers from assets.ts on the frontend and the wallet_chain_config asset table in Rust.

Supported networks

Arbitrum

Production default. Recommended for all squad governance and wallet operations. Set ALCHEMY_RPC_KEY for reliable access.

Ethereum Mainnet

Supported for treasury operations. Arbitrum is preferred for lower gas costs.

Optimism

Supported network. RPC via Alchemy opt-mainnet host.

Gnosis Chain

Supported network. RPC via Alchemy gnosis-mainnet host.

Sepolia Testnet

Used for operator smoke testing. The shipped pacto-protocol-addresses.json contains Sepolia addresses from the covenant-gov deploy bundle.

Local Anvil (dev only)

Chain ID 31337. Dev builds only — gated by #[cfg(debug_assertions)] in Rust. Requires manual contract deployment and local JSON block.

Sepolia addresses differ from every other network. The app routes contract calls through network-keyed entries in the JSON address book. Deploying governance contracts using Sepolia addresses on mainnet (or vice versa) will fail or produce unintended behaviour. Always verify the chainId field in each network block matches the chain you are targeting.

Address book sections reference

JSON section	Used by	Rust helper
`squadSponsor`	Squad sponsor deploy, deposit, summary reads	`squad_sponsor_deploy_addresses(net_key)`
`pactoGov`	Nave Pirata deploy, Hats reads, squad admin deploy	`pacto_gov_deploy_addresses(net_key)`
`safe`	Standalone Safe deploy (pacto-gov 1.4.x bundle)	`safe_factory_addresses(net_key, chain_id)`
`meta.deployer`	Audit reference only — not a runtime signer	—

Updating addresses

Follow these steps when deploying upgraded contracts or adding a new network:

Edit the JSON file — Add or update the relevant network block in src/lib/evm/pacto-protocol-addresses.json. Match the network key (mainnet, arbitrum, optimism, gnosis, sepolia) to the keys used in wallet-assets.json.

{
  "networks": {
    "arbitrum": {
      "chainId": 42161,
      "meta": { "deployer": "0x..." },
      "pactoGov": { ... },
      "squadSponsor": { ... },
      "safe": { ... }
    }
  }
}

Validate the Rust embed — Run cargo check in src-tauri/ to exercise the compile-time JSON parse. A malformed or missing required field will produce a Rust compile error, not a silent runtime failure.
```
cd src-tauri
cargo check
```
Run the TypeScript tests — Verify the frontend address module still resolves correctly:
```
npm test -- pacto-protocol-addresses
```
Update deployment environment variables — If you are using PACTO_* env overrides in any deployment environment, update those values to match the new addresses.
Record the upstream revision — Optionally include the upstream git commit SHA as an audit trail, either in the JSON $comment field or in the commit message.

For local experiments where you do not want to edit the JSON, you can export PACTO_* env vars before starting the Tauri app. See Environment Variables — PACTO_* overrides for the full list of override variable names.

Tauri Commands

Wire Formats

Configuration

Pacto Protocol Contract Address Book and Configuration

Source of truth

Example: Sepolia address book

Contract ecosystem

pacto-gov — governance contract

Gnosis Safe — multi-sig treasury

Hats Protocol — on-chain role management

ERC-20 tokens — USDC and USDT per network

Supported networks

Arbitrum

Ethereum Mainnet

Optimism

Gnosis Chain

Sepolia Testnet

Local Anvil (dev only)

Address book sections reference

Updating addresses

Build docs developers (and LLMs) love

Tauri Commands

Wire Formats

Configuration

Documentation Index

​Source of truth

​Example: Sepolia address book

​Contract ecosystem

​pacto-gov — governance contract

​pacto-squad-sponsor — ERC-4337 gas sponsorship factory

​Gnosis Safe — multi-sig treasury

​Hats Protocol — on-chain role management

​ERC-20 tokens — USDC and USDT per network

​Supported networks

Arbitrum

Ethereum Mainnet

Optimism

Gnosis Chain

Sepolia Testnet

Local Anvil (dev only)

​Address book sections reference

​Updating addresses

Build docs developers (and LLMs) love

Source of truth

Example: Sepolia address book

Contract ecosystem

pacto-gov — governance contract

pacto-squad-sponsor — ERC-4337 gas sponsorship factory

Gnosis Safe — multi-sig treasury

Hats Protocol — on-chain role management

ERC-20 tokens — USDC and USDT per network

Supported networks

Address book sections reference

Updating addresses