Core Interfaces

Last modified: April 16, 2026

The Compact protocol is composed of several key interfaces.

ITheCompact

The primary interface for deposits, transfers, registration, and management.

Deposit functions

Basic deposits

// Deposit native tokens
function depositNative(
    bytes12 lockTag,
    address recipient
) external payable returns (uint256 id);
 
// Deposit ERC20 tokens
function depositERC20(
    address token,
    bytes12 lockTag,
    uint256 amount,
    address recipient
) external returns (uint256 id);
 
// Batch deposits (native + ERC20)
function batchDeposit(
    uint256[2][] calldata idsAndAmounts,
    address recipient
) external payable returns (bool);

Permit2 deposits

// Single deposit via Permit2
function depositERC20ViaPermit2(
    ISignatureTransfer.PermitTransferFrom calldata permit,
    address depositor,
    bytes12 lockTag,
    address recipient,
    bytes calldata signature
) external returns (uint256 id);
 
// Batch deposit via Permit2
function batchDepositViaPermit2(
    address depositor,
    ISignatureTransfer.TokenPermissions[] calldata permitted,
    DepositDetails calldata details,
    address recipient,
    bytes calldata signature
) external payable returns (uint256[] memory ids);

Deposit + register combinations

// Native deposit and register
function depositNativeAndRegister(
    bytes12 lockTag,
    bytes32 claimHash,
    bytes32 typehash
) external payable returns (uint256 id);
 
// Native deposit and register for another
function depositNativeAndRegisterFor(
    address recipient,
    bytes12 lockTag,
    address arbiter,
    uint256 nonce,
    uint256 expires,
    bytes32 typehash,
    bytes32 witness
) external payable returns (uint256 id, bytes32 claimHash);
 
// ERC20 deposit and register
function depositERC20AndRegister(
    address token,
    bytes12 lockTag,
    uint256 amount,
    bytes32 claimHash,
    bytes32 typehash
) external returns (uint256 id);
 
// ERC20 deposit and register for another
function depositERC20AndRegisterFor(
    address recipient,
    address token,
    bytes12 lockTag,
    uint256 amount,
    address arbiter,
    uint256 nonce,
    uint256 expires,
    bytes32 typehash,
    bytes32 witness
) external returns (uint256 id, bytes32 claimHash, uint256 registeredAmount);
 
// Batch deposit and register multiple
function batchDepositAndRegisterMultiple(
    uint256[2][] calldata idsAndAmounts,
    bytes32[2][] calldata claimHashesAndTypehashes
) external payable returns (bool);
 
// Batch deposit and register for another
function batchDepositAndRegisterFor(
    address recipient,
    uint256[2][] calldata idsAndAmounts,
    address arbiter,
    uint256 nonce,
    uint256 expires,
    bytes32 typehash,
    bytes32 witness
) external payable returns (bytes32 claimHash, uint256[] memory registeredAmounts);
 
// Deposit via Permit2 and register
function depositERC20AndRegisterViaPermit2(
    ISignatureTransfer.PermitTransferFrom calldata permit,
    address depositor,
    bytes12 lockTag,
    bytes32 claimHash,
    CompactCategory compactCategory,
    string calldata witness,
    bytes calldata signature
) external returns (uint256 id);
 
// Batch deposit via Permit2 and register
function batchDepositAndRegisterViaPermit2(
    address depositor,
    ISignatureTransfer.TokenPermissions[] calldata permitted,
    DepositDetails calldata details,
    bytes32 claimHash,
    CompactCategory compactCategory,
    string calldata witness,
    bytes calldata signature
) external payable returns (uint256[] memory ids);

Allocated transfers

// Transfer single ID to multiple recipients with allocator approval
function allocatedTransfer(
    AllocatedTransfer calldata transfer
) external returns (bool);
 
// Transfer multiple IDs
function allocatedBatchTransfer(
    AllocatedBatchTransfer calldata transfer
) external returns (bool);

Registration functions

function register(
    bytes32 claimHash,
    bytes32 typehash
) external returns (bool);
 
function registerMultiple(
    bytes32[2][] calldata claimHashesAndTypehashes
) external returns (bool);
 
function registerFor(
    bytes32 typehash,
    address arbiter,
    address sponsor,
    uint256 nonce,
    uint256 expires,
    bytes12 lockTag,
    address token,
    uint256 amount,
    bytes32 witness,
    bytes calldata sponsorSignature
) external returns (bytes32 claimHash);
 
function registerBatchFor(
    bytes32 typehash,
    address arbiter,
    address sponsor,
    uint256 nonce,
    uint256 expires,
    bytes32 idsAndAmountsHash,
    bytes32 witness,
    bytes calldata sponsorSignature
) external returns (bytes32 claimHash);
 
function registerMultichainFor(
    bytes32 typehash,
    address sponsor,
    uint256 nonce,
    uint256 expires,
    bytes32 elementsHash,
    uint256 notarizedChainId,
    bytes calldata sponsorSignature
) external returns (bytes32 claimHash);

Forced withdrawals

function enableForcedWithdrawal(
    uint256 id
) external returns (uint256 withdrawableAt);
 
function disableForcedWithdrawal(
    uint256 id
) external returns (bool);
 
function forcedWithdrawal(
    uint256 id,
    address recipient,
    uint256 amount
) external returns (bool);

Management functions

// Emissary management
function assignEmissary(
    bytes12 lockTag,
    address emissary
) external returns (bool);
 
function scheduleEmissaryAssignment(
    bytes12 lockTag
) external returns (uint256 emissaryAssignmentAvailableAt);
 
// Allocator management
function __registerAllocator(
    address allocator,
    bytes calldata proof
) external returns (uint96 allocatorId);
 
// Consume nonces (for allocators)
function consume(
    uint256[] calldata nonces
) external returns (bool);
 
// Benchmark withdrawal costs
function __benchmark(bytes32 salt) external payable;

View functions

function getLockDetails(uint256 id) external view returns (
    address token,
    address allocator,
    ResetPeriod resetPeriod,
    Scope scope,
    bytes12 lockTag
);
 
function isRegistered(
    address sponsor,
    bytes32 claimHash,
    bytes32 typehash
) external view returns (bool isActive);
 
function getForcedWithdrawalStatus(
    address account,
    uint256 id
) external view returns (
    ForcedWithdrawalStatus status,
    uint256 forcedWithdrawalAvailableAt
);
 
function getEmissaryStatus(
    address sponsor,
    bytes12 lockTag
) external view returns (
    EmissaryStatus status,
    uint256 emissaryAssignmentAvailableAt,
    address currentEmissary
);
 
function hasConsumedAllocatorNonce(
    uint256 nonce,
    address allocator
) external view returns (bool consumed);
 
function getRequiredWithdrawalFallbackStipends() external view returns (
    uint256 nativeTokenStipend,
    uint256 erc20TokenStipend
);
 
function DOMAIN_SEPARATOR() external view returns (bytes32);
 
function name() external pure returns (string memory);

ITheCompactClaims

Endpoints for arbiters to settle compacts.

Single-chain claims

function claim(Claim calldata claimPayload) external returns (bytes32 claimHash);
 
function batchClaim(BatchClaim calldata claimPayload) external returns (bytes32 claimHash);

Multichain claims

// Notarized chain
function multichainClaim(
    MultichainClaim calldata claimPayload
) external returns (bytes32 claimHash);
 
// Exogenous chain
function exogenousClaim(
    ExogenousMultichainClaim calldata claimPayload
) external returns (bytes32 claimHash);
 
// Batch — notarized chain
function batchMultichainClaim(
    BatchMultichainClaim calldata claimPayload
) external returns (bytes32 claimHash);
 
// Batch — exogenous chain
function exogenousBatchClaim(
    ExogenousBatchMultichainClaim calldata claimPayload
) external returns (bytes32 claimHash);

Claim struct

struct Claim {
    bytes allocatorData;
    bytes sponsorSignature;
    address sponsor;
    uint256 nonce;
    uint256 expires;
    bytes32 witness;
    string witnessTypestring;
    uint256 id;
    uint256 allocatedAmount;
    Component[] claimants;
}

Component struct

struct Component {
    uint256 claimant; // The lockTag + recipient
    uint256 amount;   // The amount of tokens
}

The claimant field encodes the recipient address (lower 160 bits) and a bytes12 lockTag (upper 96 bits). The lockTag determines processing:

Lock tag	Behaviour
Matches claimed lock's tag	Direct ERC6909 transfer.
Non-zero, different	Convert to a new resource lock.
`bytes12(0)`	Withdraw underlying tokens.

IAllocator

Interface that all allocators must implement.

interface IAllocator {
    function attest(
        address operator,
        address from,
        address to,
        uint256 id,
        uint256 amount
    ) external returns (bytes4);
 
    function authorizeClaim(
        bytes32 claimHash,
        address arbiter,
        address sponsor,
        uint256 nonce,
        uint256 expires,
        uint256[2][] calldata idsAndAmounts,
        bytes calldata allocatorData
    ) external returns (bytes4);
 
    function isClaimAuthorized(
        bytes32 claimHash,
        address arbiter,
        address sponsor,
        uint256 nonce,
        uint256 expires,
        uint256[2][] calldata idsAndAmounts,
        bytes calldata allocatorData
    ) external view returns (bool);
}

Return values:

attest must return IAllocator.attest.selector
authorizeClaim must return IAllocator.authorizeClaim.selector

IEmissary

Fallback claim verification for sponsors.

interface IEmissary {
    function verifyClaim(
        address sponsor,
        bytes32 digest,
        bytes32 claimHash,
        bytes calldata signature,
        bytes12 lockTag
    ) external view returns (bytes4);
}

Must return IEmissary.verifyClaim.selector on success.

Key events

event Claim(
    address indexed sponsor,
    address indexed allocator,
    address indexed arbiter,
    bytes32 claimHash,
    uint256 nonce
);
 
event NonceConsumedDirectly(
    address indexed allocator,
    uint256 nonce
);
 
event ForcedWithdrawalStatusUpdated(
    address indexed account,
    uint256 indexed id,
    bool activating,
    uint256 withdrawableAt
);
 
event CompactRegistered(
    address indexed sponsor,
    bytes32 claimHash,
    bytes32 typehash
);
 
event AllocatorRegistered(
    uint96 allocatorId,
    address allocator
);
 
event EmissaryAssigned(
    address indexed sponsor,
    bytes12 indexed lockTag,
    address indexed emissary
);
 
event EmissaryAssignmentScheduled(
    address indexed sponsor,
    bytes12 indexed lockTag,
    uint256 assignableAt
);

Key errors

error InvalidToken(address token);
error Expired(uint256 expiration);
error InvalidSignature();
error PrematureWithdrawal(uint256 id);
error ForcedWithdrawalFailed();
error ForcedWithdrawalAlreadyDisabled(address account, uint256 id);
error UnallocatedTransfer(address operator, address from, address to, uint256 id, uint256 amount);
error InvalidBatchAllocation();
error InvalidRegistrationProof(address allocator);
error InvalidBatchDepositStructure();
error AllocatedAmountExceeded(uint256 allocatedAmount, uint256 providedAmount);
error InvalidScope(uint256 id);
error InvalidDepositTokenOrdering();
error InvalidDepositBalanceChange();
error Permit2CallFailed();
error ReentrantCall(address existingCaller);
error InconsistentAllocators();
error InvalidAllocation(address allocator);
error ChainIndexOutOfRange();
error InvalidEmissaryAssignment();
error EmissaryAssignmentUnavailable(uint256 assignableAt);
error InvalidLockTag();

ERC6909 metadata

function name(uint256 id) external view returns (string memory);
function symbol(uint256 id) external view returns (string memory);
function decimals(uint256 id) external view returns (uint8);
function tokenURI(uint256 id) external view returns (string memory);