​

Intent Contract Design

The IntentSource contract is responsible for managing the publishing of intents, the funding of intent vaults, and the withdrawal of intent rewards. This section describes the IntentSource contract and the functions it contains, to give developers a reference for how to interact with the contract. Before reading this section, please refer to the Primary Data Structures section to understand the data structures used in the IntentSource contract.

All code snippets in this section reference this specific commit.

​

Intent Origination

Intents are fully originated through two steps: intent publishing and intent funding. These are broken up into two separate functions to allow for flexibility in how intents are published and funded.

​

Publishing an Intent

Publishing an intent is done through the publish method, which calls _validateAndPublishIntent to ensure the intent is valid and then emits an IntentCreated event. Publishing an intent alerts all the participants on the network that the intent has been, or will be shortly, funded on the specified origin chain.

    function publish(
        Intent calldata intent
    ) external returns (bytes32 intentHash) {
        (intentHash, , ) = getIntentHash(intent);
        VaultState memory state = vaults[intentHash].state;

        _validateAndPublishIntent(intent, intentHash, state);
    }

    function _validateAndPublishIntent(
        Intent calldata intent,
        bytes32 intentHash,
        VaultState memory state
    ) internal {
        if (
            state.status == uint8(RewardStatus.Claimed) ||
            state.status == uint8(RewardStatus.Refunded)
        ) {
            revert IntentAlreadyExists(intentHash);
        }

        emit IntentCreated(
            intentHash,
            intent.route.salt,
            intent.route.source,
            intent.route.destination,
            intent.route.inbox,
            intent.route.tokens,
            intent.route.calls,
            intent.reward.creator,
            intent.reward.prover,
            intent.reward.deadline,
            intent.reward.nativeValue,
            intent.reward.tokens
        );
    }

You can think of Publishing an Intent as roughly analogous to posting calldata in a rollup. The intent is posted to a single location that all participants in the network can index and react to.

​

Funding an Intent

Funding an intent is done through the fund method, which calculates the deterministic intent hash, ensures the intent was not already funded, and then funds the intent.

    function fund(
        bytes32 routeHash,
        Reward calldata reward,
        bool allowPartial
    ) external payable returns (bytes32 intentHash) {
        bytes32 rewardHash = keccak256(abi.encode(reward));
        intentHash = keccak256(abi.encodePacked(routeHash, rewardHash));
        VaultState memory state = vaults[intentHash].state;

        _validateInitialFundingState(state, intentHash);

        address vault = _getIntentVaultAddress(intentHash, routeHash, reward);
        _fundIntent(intentHash, reward, vault, msg.sender, allowPartial);

        _returnExcessEth(intentHash, address(this).balance);
    }

For more information on how intents are funded, please refer to the source code here.

​

Nuances of Publishing and Funding

It is possible to both publish and fund an intent in a single transaction. This transaction is done through the publishAndFund method, which is a convenience method that combines the functionality of the publish and fund methods.

    function publishAndFund(
        Intent calldata intent,
        bool allowPartial
    ) external payable returns (bytes32 intentHash) {
        bytes32 routeHash;
        (intentHash, routeHash, ) = getIntentHash(intent);
        VaultState memory state = vaults[intentHash].state;

        _validateInitialFundingState(state, intentHash);
        _validateSourceChain(intent.route.source, intentHash);
        _validateAndPublishIntent(intent, intentHash, state);

        address vault = _getIntentVaultAddress(
            intentHash,
            routeHash,
            intent.reward
        );
        _fundIntent(intentHash, intent.reward, vault, msg.sender, allowPartial);

        _returnExcessEth(intentHash, address(this).balance);
    }

However, it is also possible to fund an intent without publishing it, or even calling the fund method! In order to understand how this is possible, we need to understand how intents are hashed and how vaults are calculated.

​

Address Calculation and Intent Hashing

The IntentSource contract uses the getIntentHash method to calculate the deterministic intent hash, which is used to calculate the deterministic intent vault address. The intent hash is calculated by hashing the route and reward structs separately and then hashing the two hashes together. Because there is a salt in the route struct, this creates a unique hash for each intent.

    function getIntentHash(
        Intent calldata intent
    )
        public
        pure
        returns (bytes32 intentHash, bytes32 routeHash, bytes32 rewardHash)
    {
        routeHash = keccak256(abi.encode(intent.route));
        rewardHash = keccak256(abi.encode(intent.reward));
        intentHash = keccak256(abi.encodePacked(routeHash, rewardHash));
    }

Using the intent hash, the intentVaultAddress method can be used to calculate the deterministic intent vault address. This is possible because of the use of Create2, which allows for the deterministic creation of contracts at a specific address.

    function intentVaultAddress(
        Intent calldata intent
    ) external view returns (address) {
        (bytes32 intentHash, bytes32 routeHash, ) = getIntentHash(intent);
        return _getIntentVaultAddress(intentHash, routeHash, intent.reward);
    }

​

Putting it all together

This means that we can know the intent vault address before the intent is published! This allows for the intent to be funded without publishing it first by just sending the collateral to the intent vault address in advance.

The data for the intent can then be published offchain, on a chain with very cheap calldata, etc. This makes the intent publishing process very flexible and allows users to publish intents in a way that balances the convenience of onchain publishing with the cost efficiency of offchain publishing.

​

Reward Withdrawal

The IntentSource contract contains methods that also govern the behavior of refunds and rewards payments to solvers.

​

Refunds

If a user wants to refund an intent, they can call the refund method. This will send the intent collateral back to the user who published the intent by deploying a Vault contract to the intent vault address which returns the collateral to the user.

    function refund(bytes32 routeHash, Reward calldata reward) external {
        bytes32 rewardHash = keccak256(abi.encode(reward));
        bytes32 intentHash = keccak256(abi.encodePacked(routeHash, rewardHash));

        VaultState memory state = vaults[intentHash].state;

        if (
            state.status != uint8(RewardStatus.Claimed) &&
            state.status != uint8(RewardStatus.Refunded)
        ) {
            address claimant = BaseProver(reward.prover).provenIntents(
                intentHash
            );
            // Check if the intent has been proven to prevent unauthorized refunds
            if (claimant != address(0)) {
                revert IntentNotClaimed(intentHash);
            }
            // Revert if intent has not expired
            if (block.timestamp <= reward.deadline) {
                revert IntentNotExpired(intentHash);
            }
        }

        if (state.status != uint8(RewardStatus.Claimed)) {
            state.status = uint8(RewardStatus.Refunded);
        }

        state.mode = uint8(VaultMode.Refund);
        state.allowPartialFunding = 0;
        state.usePermit = 0;
        state.target = address(0);
        vaults[intentHash].state = state;

        emit Refund(intentHash, reward.creator);

        new Vault{salt: routeHash}(intentHash, reward);
    }

​

Rewards Payments

The withdrawRewards method is used to withdraw rewards from an intent. This method checks that the intent is proven on the specified prover, has not been claimed or refunded, deploys a vault to the intent vault address, and then emits a Withdrawal event. Solvers can also batch withdraw rewards by calling the batchWithdraw method, which is a convenience method that combines the functionality of the withdrawRewards method for multiple intents to save on gas / calldata.

Note that the method only accepts a route hash and reward struct, not an intent struct. This is because the intent hash is not needed to withdraw rewards, and is not required to be provided by the user, which saves on gas and calldata.

    function withdrawRewards(bytes32 routeHash, Reward calldata reward) public {
        bytes32 rewardHash = keccak256(abi.encode(reward));
        bytes32 intentHash = keccak256(abi.encodePacked(routeHash, rewardHash));

        address claimant = BaseProver(reward.prover).provenIntents(intentHash);
        VaultState memory state = vaults[intentHash].state;

        // Claim the rewards if the intent has not been claimed
        if (
            claimant != address(0) &&
            state.status != uint8(RewardStatus.Claimed) &&
            state.status != uint8(RewardStatus.Refunded)
        ) {
            state.status = uint8(RewardStatus.Claimed);
            state.mode = uint8(VaultMode.Claim);
            state.allowPartialFunding = 0;
            state.usePermit = 0;
            state.target = claimant;
            vaults[intentHash].state = state;

            emit Withdrawal(intentHash, claimant);

            new Vault{salt: routeHash}(intentHash, reward);

            return;
        }

        if (claimant == address(0)) {
            revert UnauthorizedWithdrawal(intentHash);
        } else {
            revert RewardsAlreadyWithdrawn(intentHash);
        }
    }

    function batchWithdraw(
        bytes32[] calldata routeHashes,
        Reward[] calldata rewards
    ) external {
        uint256 length = routeHashes.length;

        if (length != rewards.length) {
            revert ArrayLengthMismatch();
        }

        for (uint256 i = 0; i < length; ++i) {
            withdrawRewards(routeHashes[i], rewards[i]);
        }
    }

​

Gasless Intent Initiation

IntentSource also supports gasless intent initiation, which allows users to initiate intents via signatures. Typically, these signatures are created and submitted directly by the solver who wants to fulfill the intent.

In order to gaslessly initiate an intent, the fundFor and publishAndFundFor methods are used. These methods use the permit method to approve the intent source contract to spend the user’s tokens.

​

Design Discussion

​

Intent Publishing Flexibility

Because intents can be funded with a simple transfer to a deterministic address, the protocol can be extremely flexible about where and how intent data is published. This creates several interesting possibilities:

1. Cheap Data Availability Layers: Intent data could be published on chains or L2s with very low calldata costs (like Celestia) while the actual funding happens on the origin chain. This can dramatically reduce the cost of publishing intents.

2. Off-chain Publishing: Intent data could be published through off-chain channels like IPFS or even centralized databases, with only the funding happening on-chain. This approach can be useful for private intents or in cases where minimizing costs is critical.

3. Hybrid Approaches: The protocol could support multiple publishing methods simultaneously, allowing users to choose the approach that best fits their needs based on cost, privacy, and latency requirements.

​

User and Solver Matching

In order to better match users with solvers, the protocol uses an offchain matching mechanism called the Open Quoting Client to match solvers and users who have intents. Users should request quotes from the Open Quoting Client to get matched with solvers before funding their intents, lest they be stuck without a solver and be locked out of their collateral for the duration of the intent.