Migration Guide for Non-EVM and Prefills

There is a contract migration coming on January 23rd, 2025 that will cause breaking changes.

If you prefer to just understand the breaking changes for your application, please jump directly to one of the sub-pages:

Breaking Changes for Indexers Breaking Changes for API Users Breaking Changes for Relayers

Introduction

The changes detailed in this guide follow two primary goals:

• Extending the reach of the Across system to as many users and use cases as possible

• Ensuring that the user experience is consistent across all of those domains

A gzip of the contract artifacts can be found in the release. The file can be downloaded here: contract_artifacts.tar.gz. SpokePool artifact can be found at contracts/SpokePool.sol/SpokePool.json.

Summary of Breaking Changes

These changes will go into effect starting on January 23rd.

• Four core events emitted by the SpokePool are changing, so indexers and relayers will need to be updated to track the new events.

• Integrators must use the exclusiveRelayer , exclusivityDeadline and fillDeadline parameters returned by the API in their deposit or depositV3 transactions.

To aid in testing the Across migration, we have deployed two SpokePools and created sample deposits and fills to test against. See Testnet Environment for Migration.

Summary of Suggested Changes

• Integrators are strongly encouraged to begin using the /deposit/status endpoint rather than doing their own indexing of Across events. The delay between transaction being mined and returned in this API is roughly 60 seconds. We are actively optimizing.

• Integrators are encouraged to begin using the new deposit method over depositV3, as it will be able to support deposits going to non-EVM destinations in the future.

• Relayers are encouraged to begin using the new fillRelay method, as it will allow them to begin choosing the repayment address and to fill non-EVM deposits in the future.

Summary of Feature Additions

Deterministic Relay Hashes

Across is adding a new method, called unsafeDeposit:

function unsafeDeposit(
    bytes32 depositor,
    bytes32 recipient,
    bytes32 inputToken,
    bytes32 outputToken,
    uint256 inputAmount,
    uint256 outputAmount,
    uint256 destinationChainId,
    bytes32 exclusiveRelayer,
    uint256 depositNonce,
    uint32 quoteTimestamp,
    uint32 fillDeadline,
    uint32 exclusivityParameter,
    bytes calldata message
) external payable;

This function allows for prefills, where the fill comes at the same time or before the deposit.

To do this, this method guarantees that the timing of inclusion of a successful unsafeDeposit call on the origin chain will not impact the correctness of the fill on the destination. If a filler is sure that the unsafeDeposit function will be called with the correct parameters in the future, they can safely fill before the unsafeDeposit function is finalized or even initiated.

Enabling Non-EVM Expansion

Multiple SpokePool functions have been added to support bytes32 addresses, which will enable the Across deployments on EVM chains to be cross-compatible with future deployments on other chains.

A new deposit function has been introduced that will support both EVM and (in the future) non-EVM chains:

function deposit(
    bytes32 depositor,
    bytes32 recipient,
    bytes32 inputToken,
    bytes32 outputToken,
    uint256 inputAmount,
    uint256 outputAmount,
    uint256 destinationChainId,
    bytes32 exclusiveRelayer,
    uint32 quoteTimestamp,
    uint32 fillDeadline,
    uint32 exclusivityDeadline,
    bytes calldata message
) external payable;

Alternative Address Repayment for Relayers

Relayers can now request repayment to a different address than the one that performed the fill. This has been a long-requested feature. Relayers will need to use the new fillRelay function to take advantage of this:

struct V3RelayData {
    // The bytes32 that made the deposit on the origin chain.
    bytes32 depositor;
    // The recipient bytes32 on the destination chain.
    bytes32 recipient;
    // This is the exclusive relayer who can fill the deposit before the exclusivity deadline.
    bytes32 exclusiveRelayer;
    // Token that is deposited on origin chain by depositor.
    bytes32 inputToken;
    // Token that is received on destination chain by recipient.
    bytes32 outputToken;
    // The amount of input token deposited by depositor.
    uint256 inputAmount;
    // The amount of output token to be received by recipient.
    uint256 outputAmount;
    // Origin chain id.
    uint256 originChainId;
    // The id uniquely identifying this deposit on the origin chain.
    uint256 depositId;
    // The timestamp on the destination chain after which this deposit can no longer be filled.
    uint32 fillDeadline;
    // The timestamp on the destination chain after which any relayer can fill the deposit.
    uint32 exclusivityDeadline;
    // Data that is forwarded to the recipient.
    bytes message;
}

function fillRelay(
    V3RelayData calldata relayData,
    uint256 repaymentChainId,
    bytes32 repaymentAddress
) external;