86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# 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`.
|