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

SameChainArbiter handles the core settlement logic for orders where both origin and execution occur on the same blockchain. It provides atomic settlement guarantees while supporting both Compact and Permit2 protocols with their respective validation and execution patterns.
SameChainArbiter is whitelisted as a trusted contract in the IntentExecutor, enabling gas optimization where target operations can be executed without additional signature validation.

​
Architecture

​
Same-Chain Settlement Processing

The arbiter implements the critical resource unlock and execution phase of same-chain settlement. It works in coordination with SameChainAdapter, which pre-funds recipients before calling the arbiter.
1

Signature validation

Verifies user signatures against order data and metadata.
2

Pre-claim execution

Handles pre-claim operations (approvals, setup) for Compact protocol.
3

Resource unlocking

Claims and unlocks user input tokens from the appropriate protocol.
4

Target execution

Executes user-specified operations (swaps, transfers) on target assets.

​
Dual Protocol Support

Compact Protocol Flow:
  • Validates complex signatures and metadata (otherElements, allocatorData)
  • Executes pre-claim operations with allocated gas stipends
  • Handles notarized chain validation and resource unlock
  • Supports multi-step operations and complex authorization patterns

​
Constructor

constructor(
    address router,
    address compact,
    address addressBook
)
​
router
address
required
The Router contract address that will call this arbiter. Used for access control to ensure only authorized settlement requests.
​
compact
address
required
The Compact protocol contract address for resource unlocking and validation. Handles the core authorization and token claim logic for Compact orders.
​
addressBook
address
required
The AddressBook contract containing protocol configuration and addresses. Provides centralized configuration for protocol contracts and parameters.
All three addresses are stored as immutable to prevent malicious redirection. The Router address specifically enforces that only authorized adapters can trigger settlement.

​
Compact Protocol Settlement

​
handleCompact_NotarizedChain

function handleCompact_NotarizedChain(
    Types.Order calldata order,
    Types.Signatures calldata sigs,
    bytes32[] calldata otherElements,
    bytes calldata allocatorData,
    address relayer
) external onlyRouter returns (address sponsor, uint256 nonce)
Handles complete Compact protocol same-chain settlement with full feature support.
This function assumes notarized chain execution for all multichain intents that require same-chain settlement. Exogenous chain claims are not implemented for simplicity.

​
Settlement Flow

1

Pre-claim validation and execution

Validates order signatures and metadata using _compactPreClaimOps. Executes any pre-claim operations (approvals, setup calls) with allocated gas stipend. Generates mandate hash for subsequent resource unlock validation.
bytes32 mandateHash = _compactPreClaimOps(
    order,
    sigs,
    otherElements,
    0,
    block.chainid
);
2

Resource unlock and depositing

Calls _unlockNotarizedChain to validate signatures against mandate hash. Unlocks user’s input tokens from the Compact protocol contracts. Transfers input tokens to the specified relayer (solver’s recipient address).
_unlockNotarizedChain({
    order: order,
    otherElements: otherElements,
    originChainSig: sigs.notarizedClaimSig,
    allocatorData: allocatorData,
    depositor: relayer,
    mandateHash: mandateHash
});
3

Target operation execution

Executes user-specified target operations using SmartExecutionLib. Operations run without requiring additional signatures (mandate-based execution). Typically includes swaps, transfers, or other token operations on user’s behalf.
Target operations are only executed when ALL conditions are met:
  1. Target operations are specified (non-empty)
  2. Recipient equals sponsor (self-execution pattern)
  3. Target operations are NOT using execution emissary pattern
  4. Signature mode match: target ops sig mode equals pre-claim ops sig mode, OR pre-claim ops are empty
if (order.targetOps.data.length != 0) {
    address recipient = order.recipient;
    SmartExecutionLib.SigMode targetOpsSigMode = order.targetOps.extractSigMode();
    bool sigModeMatch = (order.preClaimOps.data.length == 0 || 
                         targetOpsSigMode == order.preClaimOps.extractSigMode());
    if (recipient == sponsor && 
        !targetOpsSigMode.isExecutionEmissary() && 
        sigModeMatch) {
        EXECUTOR.executeOpsWithoutSignature(recipient, order.targetOps);
    }
}

​
Parameters

​
order
Types.Order
required
Complete order specification including tokens, operations, deadlines, and metadata. Contains all information needed for settlement validation and execution.
​
sigs
Types.Signatures
required
Container for required signatures including notarized claim sig and optional pre-claim sig. Used to validate user authorization for the settlement.
​
otherElements
bytes32[]
required
Array of additional order element hashes for complex multi-element orders. Typically empty for single-element same-chain settlements.
​
allocatorData
bytes
required
Protocol-specific data for the Compact allocator contract. Contains parameters needed for resource allocation and validation.
​
relayer
address
required
Address where input tokens will be deposited after successful unlock. Typically the solver’s address or a solver-controlled withdrawal contract.

​
Returns

​
sponsor
address
The address of the order sponsor who authorized this settlement.
​
nonce
uint256
The nonce value from the order used for replay protection and tracking.
Trusted Execution Model: SameChainArbiter’s trusted status in IntentExecutor allows target operations to execute without signature validation after successful permit2/compact transfers, saving gas while maintaining security through the initial validation gate.

​
Permit2 Protocol Settlement

​
handlePermit2

function handlePermit2(
    Types.Order calldata order,
    Types.Signatures calldata sigs,
    address relayer
) external onlyRouter returns (address sponsor, uint256 nonce)
Handles streamlined Permit2 protocol same-chain settlement with optimized efficiency.
The Permit2 flow is optimized for straightforward token operations where the complexity of pre-claim operations and gas stipends is unnecessary, providing significant gas savings.

​
Settlement Flow

1

Pre-claim validation

Validates order signatures using _permit2PreClaimOps for Permit2-specific requirements. Generates mandate hash for subsequent resource unlock without complex pre-claim operations. Skips gas stipend allocation and complex setup operations for efficiency.
bytes32 mandateHash = _permit2PreClaimOps(order, sigs);
2

Resource unlock and depositing

Calls _unlockPermit2 with simplified signature validation against mandate hash. Unlocks user’s input tokens directly from Permit2 protocol contracts. Transfers input tokens to the specified relayer address without intermediate steps.
_unlockPermit2({
    order: order,
    sig: sigs.notarizedClaimSig,
    depositor: relayer,
    mandateHash: mandateHash
});
3

Target operation execution

Executes user-specified target operations using the same SmartExecutionLib as Compact. Operations typically simpler for Permit2 (direct transfers, basic swaps). Maintains atomic execution guarantees despite simplified flow.
Target operations are only executed if:
  1. Recipient equals sponsor AND
  2. Target operations are NOT using execution emissary pattern
If conditions not met, execution is skipped to maintain security.

​
Parameters

​
order
Types.Order
required
Complete order specification including tokens, operations, and metadata. Same structure as Compact but typically with simpler target operations.
​
sigs
Types.Signatures
required
Container for required signatures, primarily the notarized claim signature. Permit2 typically requires fewer signatures than full Compact protocol.
​
relayer
address
required
Address where input tokens will be deposited after successful unlock. Receives tokens directly from Permit2 unlock without intermediate processing.

​
Returns

​
sponsor
address
The address of the order sponsor who authorized this settlement.
​
nonce
uint256
The nonce value from the order used for replay protection and tracking.
More gas-efficient than Compact due to simplified validation and unlock process. Optimized for simple token operations rather than complex multi-step settlements.

​
Security Model

Only Router can call arbiter functions via the onlyRouter modifier. This prevents unauthorized settlement attempts and ensures proper validation flow.
All user signatures validated before any asset movements or operations occur. Maintains cryptographic proof of user authorization throughout settlement.
Either entire settlement succeeds or reverts completely. If validation fails, the entire transaction reverts including pre-funding.
SameChainArbiter is whitelisted as a trusted contract in the IntentExecutor. This enables target operations to execute without additional signature validation after successful resource unlock, reducing gas costs while maintaining security.

​
Errors

​
OrderExpired

error OrderExpired();
Thrown when an order has expired based on its fillDeadline. Settlement operations validate that order.fillDeadline >= block.timestamp before processing.

​
Events

​
SameChainTargetOpsNotHandled

event SameChainTargetOpsNotHandled();
Emitted when target operations are not executed due to recipient/sponsor mismatch or emissary pattern. This event helps track when operations are skipped for security reasons.

​
Source Code Reference

Location: /src/arbiters/samechain/SameChainArbiter.sol:81

Build docs developers (and LLMs) love

Get started for freeTalk to us