Skip to main content

Permit3 Developer Guide: Install to First Approval

Permit3 developer guide: install contracts, sign EIP-712 cross-chain permits, submit Merkle proofs, add ERC-7702 and witness functionality end-to-end.

Written by Eco

Permit3 is an open-source token approval protocol for cross-chain token approvals and transfers with a single signature. Per the Permit3 README, it uses Unbalanced Merkle Trees and non-sequential nonces while keeping Permit2 compatibility. This guide walks through installing the contracts, building and signing your first permit, and extending it to a cross-chain permit, using only the interfaces documented in the Permit3 repository.
​

By the end you will know the core data structure, how the EIP-712 signature is built, how cross-chain proofs work, and where to go in the repo for multi-token permits, witnesses, and ERC-7702. If you need the conceptual overview first, read our full Permit3 guide.
​

Prerequisites

  • A Solidity toolchain. The Permit3 repository uses Foundry.

  • A JavaScript or TypeScript client environment for signing. The repo's quick-start examples use ethers.js.

  • RPC access to the EVM chains you plan to use.

  • Baseline familiarity with EIP-2612 permits or Permit2 helps but is not required.

Install the Contracts

The Permit3 README documents a Foundry workflow. Clone the repository, then install dependencies and run the test suite:
​

forge install
forge test

To use the interfaces from your own Foundry project, add the repository as a dependency with forge install eco/permit3. The README documents only this Foundry workflow, so import interfaces such as IPermit3 from the installed library.
​

Per the README, Permit3 is deployed through the ERC-2470 Singleton Factory at a deterministic address, 0xEc00030C0000245E27d1521Cc2EE88F071c2Ae34, so the same address applies on every supported network.
​

One setup step is easy to miss. Permit3 moves tokens with the allowance the owner has granted to the Permit3 contract, so each token needs a one-time ERC-20 approval to the Permit3 address before signed permits can move it.
​

Your First Single-Chain Permit

Every Permit3 operation is an AllowanceOrTransfer entry. The README defines it as:
​

struct AllowanceOrTransfer {
uint48 modeOrExpiration; // Operation mode/expiration
address token; // Token address
address account; // Approved spender/recipient
uint160 amountDelta; // Amount change/transfer amount
}

The modeOrExpiration field selects the operation. In the README's examples, 0 executes a transfer, 1 decreases an allowance, 2 locks the account, and a future timestamp increases an allowance that expires at that time.
​

The spender contract

Your contract receives the signed permit and forwards it to Permit3. This shape follows the Permit3 quick-start guide:
​

function executePermit(
address owner,
bytes32 salt,
uint48 deadline,
uint48 timestamp,
IPermit3.ChainPermits calldata chainPermits,
bytes calldata signature
) external {
permit3.permit(owner, salt, deadline, timestamp, chainPermits, signature);
}

For Permit2-style integrations, the README shows the compatibility path: cast the Permit3 address to IPermit and call transferFrom(from, to, amount, token). Contracts already built on Permit2's basic transfer interface can point at the Permit3 address.
​

Signing the permit client-side

The client builds EIP-712 typed data and asks the wallet to sign it. The quick-start guide uses this domain:
​

const domain = {
name: 'Permit3',
version: '1',
chainId: 1, // ALWAYS 1 (CROSS_CHAIN_ID) for cross-chain compatibility
verifyingContract: permit3Address
};

The guide states that the domain chainId must always be 1, regardless of which chain the permit is for. The chain where the permit executes is set in the permit data itself (chainPermits.chainId), and changing the domain chainId causes signature verification to fail.
​

A single transfer permit then looks like this:
​

const permit = {
modeOrExpiration: 0, // TransferERC20 mode
token: tokenAddress,
account: recipientAddress,
amountDelta: ethers.utils.parseUnits('10', 18)
};
const chainPermits = { chainId: 1, permits: [permit] };

The signed message also carries the owner, a random 32-byte salt, a deadline, and a timestamp. The quick-start guide lists the full EIP-712 type definitions to copy.
​

Submitting the permit

Call your spender contract with the owner, salt, deadline, timestamp, chain permits, and signature. If the single-chain path works, you have the baseline integration. Now for the cross-chain path.
​

Your First Cross-Chain Permit

The cross-chain flow hashes each chain's permits into a leaf, builds a Merkle tree, and has the user sign the root once. Each chain then receives the signature plus a proof for its own leaf. The README describes the structure as an Unbalanced Merkle Tree that orders chains so proofs stay small on expensive chains.
​

Build the permission set

const ethPermits = { chainId: 1, permits: [/* permits for Ethereum */] };
const arbPermits = { chainId: 42161, permits: [/* permits for Arbitrum */] };

const ethLeaf = permit3.hashChainPermits(ethPermits);
const arbLeaf = permit3.hashChainPermits(arbPermits);
const leaves = [ethLeaf, arbLeaf];
const merkleRoot = buildMerkleRoot(leaves);

hashChainPermits is a Permit3 contract function. The README notes that building the tree is typically done off-chain, and the quick-start guide recommends a Merkle library in production rather than a hand-rolled builder. Proofs use OpenZeppelin's MerkleProof library.
​

Sign the root

The user signs the Merkle root with the same domain (chainId 1). The signed fields are the owner, salt, deadline, timestamp, and the Merkle root.
​

Execute on each chain

On each chain, submit that chain's permits, the proof for its leaf, and the signature to Permit3 at the same deterministic address. The quick-start guide troubleshooting list is worth keeping open: the same salt and deadline must be used across chains, each chain's proof must contain the correct hashes, and the chainId in each leaf must match the chain it executes on.
​

Multi-Token and Multi-Permit Batches

One signature can carry several AllowanceOrTransfer entries. The README example combines an allowance increase, an account lock, and a transfer in a single permits array. Permit3 also supports ERC-721 and ERC-1155 tokens, with direct functions such as transferFromERC721, transferFromERC1155, and batchTransferMultiToken for callers that already have authority.
​

ERC-7702 Integration

The repo ships an ERC7702TokenApprover contract. Per the ERC-7702 integration guide, it lets an EOA batch approve infinite allowances to Permit3 for several ERC-20 tokens and execute permit operations in a single transaction. Its two functions are approve(address[] tokens) and permit(IPermit3.AllowanceOrTransfer[] permits), and the guide shows combining them in one multicall. This is the cleanest way to handle the per-token approval step for EOAs.
​

Witness Functionality

Witness data lets the signer attach application context, such as order parameters, that the spender verifies onchain. The quick-start guide hashes the order data into a bytes32 witness, signs it with a witness type string, and has the spender check the hash before calling permit3.permitWitness(owner, salt, deadline, timestamp, chainPermits, witness, witnessTypeString, signature). The guide notes the witness type string must end with a closing parenthesis.
​

Testing Your Integration

A solid test harness for a Permit3 integration covers these cases:

  • A single-chain transfer permit: confirms your spender forwards the call correctly.

  • A cross-chain permit with a valid proof: confirms the verification path works.

  • A cross-chain permit with an invalid proof: confirms bad proofs are rejected.

  • An expired permit: confirms deadline enforcement.

  • A replay attempt: confirms a reused salt is rejected.

The Permit3 repository includes its own Foundry test suite (forge test) as a reference.
​

Deployment and Production Concerns

  • Security audit: the README links a Cantina audit report. Your spender contract is a separate audit target.

  • Approvals: plan the one-time ERC-20 approval to Permit3 for every token you support, or use the ERC-7702 approver for EOAs.

  • Emergency controls: the README lists cross-chain revocation, account locking, and time-bound permissions. A locked account cannot change allowances or transfer until it submits an unlock.

  • Vulnerability reports: the repository's security policy asks for private reports through GitHub's Security tab, not public issues.

What Permit3 Pairs Well With

Permit3 is a permission primitive. For a complete cross-chain stablecoin flow, it pairs with an execution layer. Eco's docs describe funding a Routes quote with a signed Permit3 authorization. For background, see What is Eco Routes?, Permit3 vs Permit2, and the stablecoin API developer guide.
​

FAQ

Do I need to deploy anything to use Permit3?

Not the Permit3 contract itself. Per the README, it is deployed at 0xEc00030C0000245E27d1521Cc2EE88F071c2Ae34 on supported networks. You deploy your own spender contract, and token owners grant a one-time ERC-20 approval to Permit3.
​

What is the chainId in the EIP-712 domain?

Always 1. The quick-start guide explains that the domain chainId stays 1 so one signature works across chains, while the execution chain is set in the permit data.
​

How do I avoid nonce collisions when minting permits in parallel?

Use a fresh random 32-byte salt for each signature. The README describes non-sequential, bitmap-tracked nonces built for concurrent operations.
​

Can I combine Permit3 with ERC-4337?

Permit3 verifies a signature from the token owner, so the question is whether your smart account's signing path produces a signature Permit3 accepts. Test it against the repo's signature guide before relying on it in production.
​

What packages should I use?

Use the Solidity contracts and interfaces from the eco/permit3 repository via Foundry. The README documents only a Foundry install and lists no npm package; sign with your usual EIP-712 tooling (ethers.js or viem) using the types in the quick-start guide.
​

Did this answer your question?