Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rhinestonewtf/warp-router/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Permit2Arbiter serves as the integration layer with Uniswap’s Permit2 protocol, enabling arbiters to execute token transfers using cryptographic signatures instead of traditional allowances.
Permit2 is a token approval management protocol that allows users to grant token spending permissions through signatures rather than on-chain approvals, providing better UX and gas efficiency.

​
Key Benefits

  • Eliminates approval transactions: No need for separate approval transactions before token transfers
  • Batch token transfers: Transfer multiple tokens with a single signature
  • Fine-grained control: Precise permissions with nonces and deadlines
  • Gas efficiency: Signature-based transfers eliminate separate approval gas costs
  • Enhanced security: Battle-tested signature validation with time-bounded permissions

​
Integration with Router Ecosystem

  • Processes token inputs from cross-chain orders using signature-based permissions
  • Converts order token data into Permit2-compatible permission structures
  • Handles witness-based transfers where mandate hashes serve as additional validation
  • Enables seamless token unlocking as part of cross-chain settlement flows

​
Constructor

constructor(address permit2)
​
permit2
address
required
The address of the Permit2 SignatureTransfer contract on the current network. Must be the canonical Permit2 deployment to ensure signature compatibility and security.
The permit2 address cannot be changed after deployment. Verify it matches the official Permit2 deployment for the target network. The address is different on each network but maintains the same interface.

​
State Variables

​
PERMIT2

ISignatureTransfer internal immutable PERMIT2;
Permit2 signature transfer interface for executing signature-based token transfers.
This immutable interface provides access to Permit2’s signature transfer functionality, enabling secure token transfers through cryptographic signatures rather than allowances. Used for all signature-based token unlocking operations in the arbiter system.

​
Token Unlocking

​
_unlockPermit2

function _unlockPermit2(
    Types.Order calldata order,
    bytes calldata sig,
    bytes32 mandateHash,
    address depositor
) internal
Unlocks tokens using Permit2 signature-based transfers with mandate witness validation.
Processes token inputs from a cross-chain order by converting them into Permit2-compatible permission structures and executing signature-authorized transfers. The mandate hash serves as a witness to provide additional validation that the transfer is part of a valid cross-chain settlement operation.

​
Execution Flow

1

Convert token data

Converts order token data (id/amount pairs) into Permit2 TokenPermissions. This transforms [token_id, amount] pairs into proper token addresses and amounts.
(
    ISignatureTransfer.TokenPermissions[] memory tokenPermission,
    ISignatureTransfer.SignatureTransferDetails[] memory signatureTransferDetails
) = order.tokenIn.toTokenPermissions(depositor);
2

Create permit structure

Creates SignatureTransferDetails specifying the depositor as recipient. Constructs a PermitBatchTransferFrom with order nonce and expiry.
ISignatureTransfer.PermitBatchTransferFrom memory permit =
    ISignatureTransfer.PermitBatchTransferFrom({
        permitted: tokenPermission,
        nonce: order.nonce,
        deadline: order.expires
    });
3

Execute transfer

Executes permitWitnessTransferFrom with mandate hash as witness data. The mandate hash proves the transfer is part of a valid cross-chain order.
PERMIT2.permitWitnessTransferFrom({
    permit: permit,
    transferDetails: signatureTransferDetails,
    owner: order.sponsor,
    witness: mandateHash,
    witnessTypeString: Permit2Lib.WITNESS_TYPESTRING,
    signature: sig
});

​
Parameters

​
order
Types.Order
required
The cross-chain order containing token inputs, sponsor, nonce, and expiry details. The tokenIn array contains [token_id, amount] pairs that get converted to token addresses.
​
sig
bytes
required
The signature from the order sponsor authorizing the Permit2 token transfer. Must be a valid EIP-712 signature over the permit data and mandate witness.
​
mandateHash
bytes32
required
The hash of the cross-chain mandate serving as witness data for additional validation. This proves the transfer is part of a legitimate cross-chain settlement operation.
​
depositor
address
required
The address that will receive the transferred tokens. Typically the settlement contract or final recipient depending on the settlement flow.

​
Security Features

The function enables secure token transfers where:
The mandate hash proves the transfer is part of a valid cross-chain order, providing an additional layer of security beyond basic token permissions.
The depositor receives the tokens as specified in the settlement, ensuring funds go to the intended recipient.
Nonce prevents replay attacks and expiry ensures time-bounded permissions, protecting against stale or reused signatures.

​
Permit2 Data Structures

​
TokenPermissions

struct TokenPermissions {
    address token;
    uint256 amount;
}
Defines the token address and amount for a single token permission.

​
SignatureTransferDetails

struct SignatureTransferDetails {
    address to;
    uint256 requestedAmount;
}
Specifies the recipient address and amount for the transfer.

​
PermitBatchTransferFrom

struct PermitBatchTransferFrom {
    TokenPermissions[] permitted;
    uint256 nonce;
    uint256 deadline;
}
Contains the complete permit structure for batch transfers:
  • permitted: Array of token permissions
  • nonce: Unique identifier preventing replay attacks
  • deadline: Expiration timestamp for the permit

​
Witness Type String

The witness type string is used for EIP-712 signature validation with additional witness data: 
string constant WITNESS_TYPESTRING = "Mandate mandate)Mandate(...)";
The witness mechanism provides additional validation beyond basic token permissions. The mandate hash is included in the EIP-712 signature, cryptographically linking the token transfer to the specific cross-chain settlement operation.

​
Example Usage

Here’s how Permit2Arbiter is used in a typical settlement flow: 
// 1. Generate mandate hash from order
bytes32 mandateHash = _permit2PreClaimOps(order, sigs);

// 2. Unlock tokens using Permit2 with mandate witness
_unlockPermit2({
    order: order,
    sig: sigs.notarizedClaimSig,
    depositor: relayer,
    mandateHash: mandateHash
});

// 3. Tokens are now transferred to depositor (relayer)
// 4. Continue with target operation execution

​
Gas Optimization

Batch operations: Uses batch operations when multiple tokens are present for optimal gas efficiency. Multiple tokens are processed in a single permitWitnessTransferFrom call.Immutable storage: Immutable Permit2 interface minimizes storage costs for repeated operations.No approval costs: Signature-based transfers eliminate the gas cost of separate approval transactions.

​
Security Considerations

Signature validation: All transfers require valid signatures from token owners (sponsors). The signature must be a properly formatted EIP-712 signature that includes both the permit data and the mandate witness.Mandate witness: Mandate hashes provide additional witness-based validation for cross-chain operations, ensuring transfers are part of legitimate settlement flows.Time bounds: Nonce and deadline parameters prevent replay attacks and ensure time-bounded permissions.Permit2 dependency: Signature validation relies on Permit2’s implementation - ensure the Permit2 address is the canonical deployment.

​
Comparison with CompactArbiter

Best for:
  • Simple token transfers
  • Gas-optimized flows
  • Straightforward settlement operations
Characteristics:
  • Signature-based permissions
  • No pre-claim operation complexity
  • Lower gas overhead
  • Direct token transfers

​
Source Code Reference

Location: /src/base/arbiter/Permit2Arbiter/Permit2Arbiter.sol:42

Build docs developers (and LLMs) love

Get started for freeTalk to us