Intent Lifecycle

Complete lifecycle of an intent from creation to reward distribution

Overview

An intent progresses through several states from creation to completion. Understanding this lifecycle is crucial for all participants in the protocol.

Intent Status

The protocol tracks intent rewards through the following states:

enum Status {
    Initial,    // Intent published but not funded
    Funded,     // Intent fully funded and ready for fulfillment
    Withdrawn,  // Rewards claimed by solver
    Refunded    // Rewards returned to creator (expired)
}

Complete Lifecycle

Alternative Path: Refund

If an intent expires without fulfillment, the creator can recover their rewards.

Refund Conditions

contracts/IntentSource.sol

function refund(
    uint64 destination,
    bytes32 routeHash,
    Reward calldata reward
) external

Validation logic:

function _validateRefund(
    bytes32 intentHash,
    uint64 destination,
    Reward calldata reward
) internal view {
    Status status = rewardStatuses[intentHash];
    IProver.ProofData memory proof = IProver(reward.prover).provenIntents(
        intentHash
    );

    // If proof is incorrect or no proof
    if (proof.destination != destination || proof.claimant == address(0)) {
        if (block.timestamp < reward.deadline) {
            revert InvalidStatusForRefund(
                status,
                block.timestamp,
                reward.deadline
            );
        }
        return;
    }

    if (status == Status.Initial || status == Status.Funded) {
        revert IntentNotClaimed(intentHash);
    }
}

Refund process:

1. Checks deadline has passed: block.timestamp >= reward.deadline
2. Verifies intent was not proven as fulfilled
3. Updates status to Refunded
4. Transfers all tokens from vault back to creator
5. Emits IntentRefunded event

Refund to custom address:

function refundTo(
    uint64 destination,
    bytes32 routeHash,
    Reward calldata reward,
    address refundee
) external

Only the intent creator can specify a different refund recipient.

State Transitions

Timeline Constraints

• Route deadline: Intent must be fulfilled before route.deadline
• Reward deadline: Intent must be fulfilled before reward.deadline
• Refund eligibility: Can only refund after reward.deadline has passed
• Proof validity: Proof must match the destination chain ID

Best practice: Set route.deadline slightly before reward.deadline to give solvers time to prove fulfillment before the intent becomes refundable.