StarknetGatewayAdapter

Title: StarknetGatewayAdapter

Authors: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80), Modified from Starknet (https://github.com/starkware-libs/cairo-lang)

L1-side (Ethereum-only) Starknet L1 <-> L2 connector facet: sendMessage escrows a non-refundable fee and dispatches a felt-chunk-encoded payload to a registered L2 l1_handler; startCancellation/cancel are the initiator-gated two-step cancellation of an in-flight message; consumeMessage is the permissionless keeper-driven PULL of a trusted L2 sender's message from the core. DELIBERATELY BESPOKE, not an IERC7786GatewaySource — the inbound path is a counter-based pull (no message id), attributes cannot express the escrowed fee + cancellation lifecycle, and the wire payload is a felt array (see IStarknetGatewayAdapter).

Stateless delegator — logic/storage live in StarknetGatewayAdapterLib. The send/cancel/consume paths are nonReentrant; cancellation authority is re-derived at the facet level because the DIAMOND is the L1 sender on the Starknet core. FEE WARNING: the message fee is escrowed by Starknet and NEVER refunded, cancellation included.

Notes:

lattice-version: 0.1.0
lattice-source: Starknet

Functions

sendMessage

Sends payload (felt-chunk encoded) to the ERC-7930 Starknet recipient's registered l1_handler, escrowing msg.value as the message fee.

The fee is escrowed by the Starknet core and NEVER refunded — cancellation included. The caller is recorded as the message's initiator and is the only party able to cancel it.

function sendMessage(bytes calldata recipient, bytes calldata payload)
        external
        payable
        virtual
        returns (bytes32 msgHash, uint256 nonce);

Parameters

Name	Type	Description
recipient	`bytes`	The ERC-7930 interoperable recipient (starknet chainType + chain reference + felt252).
payload	`bytes`	The raw bytes payload (encoded per the felt-chunk convention v1 on the wire).

Returns

Name	Type	Description
msgHash	`bytes32`	The core-computed message hash.
nonce	`uint256`	The core-minted message nonce (keep it — cancellation needs it).

startCancellation

Starts the two-step cancellation of a previously sent message, re-derived from the ORIGINAL recipient/selector/payload/nonce. Initiator only.

selector is the SEND-TIME l1_handler selector (emitted in StarknetMessageSent) — passed explicitly and NOT re-read from the mutable handler registry, so an admin re-registering the target's selector while the message is in flight cannot lock the initiator out of cancelling. The core enforces a messageCancellationDelay() wait between this call and cancel.

function startCancellation(bytes calldata recipient, uint256 selector, bytes calldata payload, uint256 nonce)
        external
        virtual
        returns (bytes32 msgHash);

Parameters

Name	Type	Description
recipient	`bytes`
selector	`uint256`
payload	`bytes`
nonce	`uint256`

Returns

Name	Type	Description
msgHash	`bytes32`

cancel

Completes the cancellation started by startCancellation (same arguments), at least messageCancellationDelay() seconds later. Initiator only. The escrowed fee is NOT refunded.

function cancel(bytes calldata recipient, uint256 selector, bytes calldata payload, uint256 nonce)
        external
        virtual
        returns (bytes32 msgHash);

Parameters

Name	Type	Description
recipient	`bytes`
selector	`uint256`
payload	`bytes`
nonce	`uint256`

Returns

Name	Type	Description
msgHash	`bytes32`

consumeMessage

Permissionless keeper-driven pull: consumes an L2 -> L1 message from the trusted L2 sender fromAddress addressed to this diamond, and emits it. Emit-only in v1.

The core is the real authenticator (it only consumes messages addressed to msg.sender — the diamond — and reverts when the message counter is zero). Counter semantics: duplicates are N DISTINCT consumes, not replays — consuming the same message twice requires the L2 to have SENT it twice. NOT routed into CrosschainLink / OpenBridge.

function consumeMessage(uint256 fromAddress, bytes calldata payload) external virtual returns (bytes32 msgHash);

Parameters

Name	Type	Description
fromAddress	`uint256`
payload	`bytes`

Returns

Name	Type	Description
msgHash	`bytes32`

registerL2Handler

Registers the l1_handler selector to invoke when sending to l2Target. Both values must be non-zero felt252s. Admin only.

function registerL2Handler(uint256 l2Target, uint256 selector) external virtual;

Parameters

Name	Type	Description
l2Target	`uint256`
selector	`uint256`

setTrustedL2Sender

Sets the trusted flag of the L2 sender fromAddress (a non-zero felt252) for the inbound consume path. Admin only.

function setTrustedL2Sender(uint256 fromAddress, bool trusted) external virtual;

Parameters

Name	Type	Description
fromAddress	`uint256`
trusted	`bool`

starknetCore

The Starknet core (StarknetMessaging) contract on this chain.

function starknetCore() external view virtual returns (address);

Returns

Name	Type	Description
<none>	`address`

expectedChainReference

The ERC-7930 chain reference this adapter accepts (UTF-8 chain-id string, e.g. SN_MAIN).

function expectedChainReference() external view virtual returns (bytes memory);

Returns

Name	Type	Description
<none>	`bytes`

l1HandlerSelector

The registered l1_handler selector for l2Target (0 = unregistered).

function l1HandlerSelector(uint256 l2Target) external view virtual returns (uint256);

Parameters

Name	Type	Description
l2Target	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

isTrustedL2Sender

Whether fromAddress is a trusted L2 sender for the inbound consume path.

function isTrustedL2Sender(uint256 fromAddress) external view virtual returns (bool);

Parameters

Name	Type	Description
fromAddress	`uint256`

Returns

Name	Type	Description
<none>	`bool`

initiatorOf

The initiator recorded for an in-flight outbound message (address(0) = unknown/cancelled).

function initiatorOf(bytes32 msgHash) external view virtual returns (address);

Parameters

Name	Type	Description
msgHash	`bytes32`

Returns

Name	Type	Description
<none>	`address`

starknetSelector

Computes the Starknet selector (starknet_keccak) of an l1_handler entry-point name: uint256(keccak256(bytes(name))) & ((1 << 250) - 1) (keccak256 masked to its low 250 bits).

Convenience for admins registering handlers — selectors CANNOT be derived from the ERC-7930 address, they are a property of the target contract's Cairo code.

function starknetSelector(string calldata name) external pure virtual returns (uint256);

Parameters

Name	Type	Description
name	`string`

Returns

Name	Type	Description
<none>	`uint256`

exportSelectors

ERC-8153 selector export: this facet's cuttable selectors, tightly packed (4 bytes each).

Excludes exportSelectors() itself (0x0ef22643) - it is never cut into a diamond. Order matches forge inspect StarknetGatewayAdapter methodIdentifiers (alphabetical by signature); kept in exact parity by ExportSelectorsParityTest. Chunks: cancel(bytes,uint256,bytes,uint256) 0x71dcb2b0 consumeMessage(uint256,bytes) 0x367bd9dd expectedChainReference() 0x743bb3f6 initiatorOf(bytes32) 0x5b8cbad8 isTrustedL2Sender(uint256) 0x3984b96c l1HandlerSelector(uint256) 0xc9aacd1d registerL2Handler(uint256,uint256) 0x3b70379a sendMessage(bytes,bytes) 0x48e6fa23 setTrustedL2Sender(uint256,bool) 0x92126474 starknetCore() 0x39e730ab starknetSelector(string) 0xeafe2ebf startCancellation(bytes,uint256,bytes,uint256) 0xd75ed921

function exportSelectors() external pure virtual returns (bytes memory selectors);

Returns

Name	Type	Description
selectors	`bytes`