TipsLib

Git Source

Tips

Library for formatting the tips part of the base messages.

How the tips are awarded

Tips are paid for sending a base message, and are split across all the agents that made the message execution on destination chain possible.

Summit tips

Split between:

• Guard posting a snapshot with state ST_G for the origin chain.
• Notary posting a snapshot SN_N using ST_G. This creates attestation A.
• Notary posting a message receipt after it is executed on destination chain.

Attestation tips

Paid to:

• Notary posting attestation A to destination chain.

Execution tips

Paid to:

• First executor performing a valid execution attempt (correct proofs, optimistic period over), using attestation A to prove message inclusion on origin chain, whether the recipient reverted or not.

Delivery tips.

Paid to:

• Executor who successfully executed the message on destination chain.

Tips encoding

• Tips occupy a single storage word, and thus are stored on stack instead of being stored in memory.
• The actual tip values should be determined by multiplying stored values by divided by TIPS_MULTIPLIER=2**32.
• Tips are packed into a single word of storage, while allowing real values up to ~8*10**28 for every tip category.

The only downside is that the "real tip values" are now multiplies of ~4*10**9, which should be fine even for the chains with the most expensive gas currency.

Tips stack layout (from highest bits to lowest)

State Variables

SHIFT_SUMMIT_TIP

Amount of bits to shift to summitTip field

uint256 private constant SHIFT_SUMMIT_TIP = 24 * 8;

SHIFT_ATTESTATION_TIP

Amount of bits to shift to attestationTip field

uint256 private constant SHIFT_ATTESTATION_TIP = 16 * 8;

SHIFT_EXECUTION_TIP

Amount of bits to shift to executionTip field

uint256 private constant SHIFT_EXECUTION_TIP = 8 * 8;

Functions

encodeTips

Returns encoded tips with the given fields

function encodeTips(uint64 summitTip_, uint64 attestationTip_, uint64 executionTip_, uint64 deliveryTip_)
    internal
    pure
    returns (Tips);

Parameters

encodeTips256

Convenience function to encode tips with uint256 values.

function encodeTips256(uint256 summitTip_, uint256 attestationTip_, uint256 executionTip_, uint256 deliveryTip_)
    internal
    pure
    returns (Tips);

wrapPadded

Wraps the padded encoded tips into a Tips-typed value.

There is no actual padding here, as the underlying type is already uint256, but we include this function for consistency and to be future-proof, if tips will eventually use anything smaller than uint256.

function wrapPadded(uint256 paddedTips) internal pure returns (Tips);

emptyTips

Returns a formatted Tips payload specifying empty tips.

function emptyTips() internal pure returns (Tips);

Returns

leaf

Returns tips's hash: a leaf to be inserted in the "Message mini-Merkle tree".

function leaf(Tips tips) internal pure returns (bytes32 hashedTips);

summitTip

Returns summitTip field

function summitTip(Tips tips) internal pure returns (uint64);

attestationTip

Returns attestationTip field

function attestationTip(Tips tips) internal pure returns (uint64);

executionTip

Returns executionTip field

function executionTip(Tips tips) internal pure returns (uint64);

deliveryTip

Returns deliveryTip field

function deliveryTip(Tips tips) internal pure returns (uint64);

value

Returns total value of the tips payload. This is the sum of the encoded values, scaled up by TIPS_MULTIPLIER

function value(Tips tips) internal pure returns (uint256 value_);

matchValue

Increases the delivery tip to match the new value.

function matchValue(Tips tips, uint256 newValue) internal pure returns (Tips newTips);