# 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)

```text
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`.