smom-dbis-138/docs/bridge/TEZOS_L1_RELAY_RUNBOOK.md

Tezos L1 Relay Runbook

This runbook describes how an off-chain relay service should integrate with the TezosAdapter to complete bridge operations from an EVM chain to Tezos L1 (native Michelson).

Overview

• TezosAdapter (EVM side): Locks tokens on the source chain and emits events when a bridge is initiated.
• Relay service (off-chain): Watches these events, performs the Tezos-side mint/transfer, then calls confirmTransaction(requestId, tezosTxHash) on the adapter.

TezosAdapter Event Schema

TezosBridgeInitiated

Emitted when a user calls bridge(token, amount, destination, recipient) on the TezosAdapter.

Parameter	Type	Description
requestId	bytes32	Unique request identifier (use for confirmTransaction).
sender	address	EVM address that initiated the bridge.
token	address	Token contract address (address(0) for native ETH).
amount	uint256	Amount locked.
destination	string	Tezos address (tz1/tz2/tz3/KT1) to receive on Tezos.

Relay responsibilities:

1. Index or subscribe to TezosBridgeInitiated events from the TezosAdapter contract.
2. Decode requestId, sender, token, amount, destination.
3. Map token to the Tezos-side wrapped/representative asset (e.g. FA1.2/FA2 or custody account).
4. On Tezos: mint wrapped tokens to destination or release from custody to destination (depending on bridge design).
5. After the Tezos transaction is confirmed, call on the EVM TezosAdapter:
   • confirmTransaction(requestId, tezosTxHash) (requires ORACLE_ROLE).

TezosAdapter Methods (for relay)

Method	Role	Description
confirmTransaction(bytes32 requestId, string txHash)	ORACLE_ROLE	Mark the bridge request as confirmed and store the Tezos tx hash.
getBridgeStatus(bytes32 requestId)	any	Returns BridgeRequest (status, sender, token, amount, destinationData, etc.).

Destination Validation

TezosAdapter accepts destinations that pass validateDestination(destination):

• destination is the UTF-8 encoding of a Tezos address (tz1, tz2, tz3, or KT1).
• Length must be between 35 and 64 bytes.

Relay Flow (high level)

User -> TezosAdapter.bridge(...) -> tokens locked, TezosBridgeInitiated emitted
       -> Relay watches event
       -> Relay performs Tezos-side mint/transfer to destination
       -> Relay calls TezosAdapter.confirmTransaction(requestId, tezosTxHash)

Oracle Key Handling

• ORACLE_ROLE: The relay (or a dedicated oracle) must hold ORACLE_ROLE on the TezosAdapter to call confirmTransaction. Grant via grantRole(ORACLE_ROLE, relayAddress).
• Key material: Store relay/oracle private key securely (HSM or secrets manager); never commit to repo.
• Rotation: To rotate oracle key: deploy new relay with new key, grant ORACLE_ROLE to new address, revoke from old address, then retire old relay.
• Backup: Document backup and recovery for oracle key so confirmTransaction can continue after relay failure.

Tezos-Side Mint/Transfer Spec

• Wrapped representation: Map each EVM token to a Tezos asset (FA1.2/FA2 token contract or custody account). Maintain a config map: EVM token address -> Tezos contract/account.
• Flow: On Tezos, either (1) call a mint entrypoint on the wrapped-token contract to mint amount to destination, or (2) transfer from a custody account to destination. Use Tezos RPC (e.g. TzKT or node) to submit the operation.
• Finality: Only after the Tezos operation is included and finalized (e.g. 1 confirmation on Tezos), call confirmTransaction(requestId, tezosTxHash) with the Tezos operation hash.

Security and Operations

• The relay (or a dedicated oracle) must hold ORACLE_ROLE on the TezosAdapter to call confirmTransaction.
• Only call confirmTransaction after the Tezos transaction is finalized to avoid marking incomplete transfers as confirmed.
• Tezos L1 uses chainId 1 in BridgeRegistry (non-EVM slot); include 1 in token allowedDestinations for tokens that may bridge to Tezos L1.

Run instructions and env (relay service)

• Service: smom-dbis-138/services/tezos-relay (Node.js).
• Env: TEZOS_ADAPTER_ADDRESS, TEZOS_RELAY_ORACLE_KEY or PRIVATE_KEY (EVM key for confirmTransaction), RPC_URL_138. For real Tezos mint: TEZOS_RPC_URL, TEZOS_MINTER_ADDRESS, TEZOS_ORACLE_SECRET_KEY (Tezos edsk...). Set MOCK_TEZOS_RELAY=true to use mock hash only (no Taquito).
• Start: cd services/tezos-relay && npm install && node index.js (or npm start). Optional: add @taquito/taquito and @taquito/signer for real mint/transfer.

References

• TezosAdapter: smom-dbis-138/contracts/bridge/adapters/non-evm/TezosAdapter.sol
• IChainAdapter: smom-dbis-138/contracts/bridge/interfaces/IChainAdapter.sol
• BridgeRegistry (Tezos-Mainnet destination): chainId 1; see InitializeRegistry.s.sol.