Allocators

Allocators are crucial infrastructure components in The Compact protocol that ensure resource lock integrity and prevent double-spending.

Role and Responsibilities

Each resource lock is mediated by an allocator with four primary responsibilities:

Registration

Allocators must be registered with The Compact before they can be assigned to locks.

Registration requirements

Anyone can register an allocator if one of three conditions is met:

Registration function

function __registerAllocator(
    address allocator,
    bytes calldata proof
) external returns (uint96 allocatorId)

Create2 proof format

When registering an allocator that does not yet exist but will be deployed via CREATE2, provide an 85-byte proof:

0xff ++ factory ++ salt ++ initcode hash

This allows pre-registration of deterministic addresses.

IAllocator Interface

All allocators must implement the IAllocator interface:

attest

Called on standard ERC6909 transfers to validate them:

Function signature

function attest(
    address operator,
    address from,
    address to,
    uint256 id,
    uint256 amount
) external returns (bytes4)

Requirements

attest must verify that the transfer is safe and return IAllocator.attest.selector on success.

authorizeClaim

Called by The Compact during claim processing for onchain authorization:

Function signature

function authorizeClaim(
    bytes32 claimHash,
    address arbiter,
    address sponsor,
    uint256 nonce,
    uint256 expires,
    uint256[2][] calldata idsAndAmounts,
    bytes calldata allocatorData
) external returns (bytes4)

Parameters

Requirements

authorizeClaim must return IAllocator.authorizeClaim.selector on success.

isClaimAuthorized

Offchain view function to check if a claim would be authorized:

Function signature

function isClaimAuthorized(
    bytes32 claimHash,
    address arbiter,
    address sponsor,
    uint256 nonce,
    uint256 expires,
    uint256[2][] calldata idsAndAmounts,
    bytes calldata allocatorData
) external view returns (bool)

Should perform the same authorization checks as authorizeClaim but as a view function.

Allocator Data

The allocatorData parameter allows allocators to implement custom authorization logic:

It can contain signatures from offchain systems, merkle proofs, or other authorization evidence. The format is entirely defined by each allocator implementation.

Nonce Management

Allocators can directly consume nonces to invalidate compacts:

function consume(uint256 nonce) external

This emits a NonceConsumedDirectly event and prevents any compact using that nonce from being claimed.

Check if a nonce has been consumed:

function hasConsumedAllocatorNonce(
    address allocator,
    uint256 nonce
) external view returns (bool)

Implementation Patterns

Onchain allocators

Purely onchain allocators can:

Hybrid allocators

Combine onchain and offchain components:

Sample implementations

Two basic sample implementations are available:

Trust Assumptions

For sponsors

Sponsors assume allocators will not unduly censor valid requests against fully funded locks, and that forced-withdrawal flows remain available if allocators become unresponsive.

For claimants

Claimants assume allocators are sound, do not allow resource locks to become underfunded, and properly track and enforce balance constraints.

Forced Withdrawal Mechanism

To protect sponsors from unresponsive or malicious allocators, The Compact implements a forced withdrawal mechanism that allows sponsors to bypass allocator authorization after a waiting period.

How it works

A sponsor can call disableForcedWithdrawal(uint256 id) at any time before execution to cancel the process. Once their withdrawal status has been set as enabled, that state will persist until it is explicitly disabled; should they wish to utilize the underlying resource lock again, the withdrawal status will first need to be disabled.

Functions

// Enable forced withdrawal for a resource lock
function enableForcedWithdrawal(uint256 id) external

// Disable a pending forced withdrawal
function disableForcedWithdrawal(uint256 id) external

// Execute forced withdrawal after timelock expires
function forcedWithdrawal(
    uint256 id,
    address recipient,
    uint256 amount
) external

Security considerations

Checking withdrawal status

function getForcedWithdrawalStatus(
    address account,
    uint256 id
) external view returns (ForcedWithdrawalStatus status, uint256 withdrawableAt)

Status can be:

Events

event AllocatorRegistered(
    uint96 allocatorId,
    address allocator
)

event NonceConsumedDirectly(
    address indexed allocator,
    uint256 nonce
)

Error Handling

Common allocator-related errors: