03 - Template Cookbook

A collection of template examples by lane. For detailed rules, see docs/reference/compiler/plan-compilation.md.

Register from the Dashboard (Recommended)

If you select a preset on the dashboard’s Templates page (/routes), you do not need to write JSON by hand:

Click the lane card you want in the Presets grid at the bottom of the Templates page
In Customize, change only the core fields such as asset, exchange, and network
Check the result in Graph Preview and JSON Preview
Register it with the Register Template button

Currently available presets: CEX Transfer, CCTP Bridge, Gateway Transfer, Multi-hop (CEX->CEX->Chain->Gateway)

For a custom template that is not covered by a preset, use the JSON examples below and register it directly through the API.

Register Directly Through the API

Template Structure at a Glance

{
  "template_key": "identifier",
  "name": "human-readable name",
  "version": 1,
  "nodes": [node array],
  "edges": [edge array],
  "approval_policy": {"mode": "manual_first"},
  "completion_policy": {"completion_assurance": "..."},
  "risk_controls": {}
}

Required node fields: node_key, node_kind, action_type, executor_selector, has_side_effect Required edge fields: from, to, edge_type (usually "on_success")

1. CEX 3-Node (Upbit -> Bybit XRP)

The simplest shape: withdrawal -> withdrawal observe -> deposit observe.

{
    "template_key": "cex.upbit_to_bybit.xrp",
    "name": "Upbit to Bybit XRP",
    "version": 1,
    "nodes": [
        {
            "node_key": "withdraw",
            "node_kind": "action",
            "action_type": "cex_withdrawal",
            "executor_selector": {"action_type": "cex_withdrawal"},
            "config": {
                "asset": "XRP",
                "source_exchange": "upbit",
                "destination_exchange": "bybit",
                "network": "XRP"
            },
            "has_side_effect": true,
            "timeout_policy": {"submit_seconds": 120},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "withdraw_observe",
            "node_kind": "observe",
            "action_type": "cex_withdrawal_status",
            "executor_selector": {"action_type": "cex_withdrawal_status"},
            "config": {"asset": "XRP", "source_exchange": "upbit"},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 1800},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "deposit_observe",
            "node_kind": "observe",
            "action_type": "cex_deposit_status",
            "executor_selector": {"action_type": "cex_deposit_status"},
            "config": {"asset": "XRP", "destination_exchange": "bybit", "match_mode": "txid"},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 3600},
            "retry_policy": {},
            "risk_patch": {}
        }
    ],
    "edges": [
        {"from": "withdraw", "to": "withdraw_observe", "edge_type": "on_success"},
        {"from": "withdraw_observe", "to": "deposit_observe", "edge_type": "on_success"}
    ],
    "approval_policy": {"mode": "manual_first"},
    "completion_policy": {"completion_assurance": "destination_credited"},
    "risk_controls": {"asset_allowlist": ["XRP"], "max_amount": "1000"}
}

Key points:

completion_assurance: "destination_credited" -> the terminal node is cex_deposit_status (the destination_provider_observe family)
match_mode is required on the terminal node
risk_controls is free-form and only max_amount binds (fail-closed at dispatch). The asset_allowlist in every template below is descriptive — hash-pinned, but not enforced. See the v3 endpoints reference

2. CCTP 5-Node (Base Sepolia -> Arbitrum Sepolia)

Cross-chain USDC transfer via CCTP. Requires a signer.

{
    "template_key": "cctp.base-to-arb-sepolia.usdc",
    "name": "CCTP USDC Base Sepolia -> Arbitrum Sepolia",
    "version": 1,
    "nodes": [
        {
            "node_key": "burn",
            "node_kind": "action",
            "action_type": "cctp_burn",
            "executor_selector": {"action_type": "cctp_burn", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "source_chain_id": 84532,
                "source_domain_id": 6,
                "destination_chain_id": 421614,
                "destination_domain_id": 3,
                "token_messenger_address": "0x9f3B8679c73C2Fef8b59B4f3444d4e156fb70AA5",
                "burn_token_address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "destination_caller": "0xYOUR_SIGNER_ADDRESS",
                "token_decimals": 6,
                "max_fee_raw": 500000,
                "min_finality_threshold": 1000,
                "gas_buffer_multiplier": "1.3"
            },
            "has_side_effect": true,
            "timeout_policy": {},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "attestation",
            "node_kind": "observe",
            "action_type": "protocol_observe",
            "executor_selector": {"action_type": "protocol_observe"},
            "config": {"probe_key": "cctp_iris", "source_domain_id": 6},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 600},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "mint",
            "node_kind": "action",
            "action_type": "cctp_mint",
            "executor_selector": {"action_type": "cctp_mint", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "destination_chain_id": 421614,
                "destination_domain_id": 3,
                "message_transmitter_address": "0xaCF1ceeF35caAc005e559DCB4211986aA0e55344",
                "destination_caller": "0xYOUR_SIGNER_ADDRESS",
                "gas_buffer_multiplier": "1.3"
            },
            "has_side_effect": true,
            "timeout_policy": {},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "mint_receive_observe",
            "node_kind": "observe",
            "action_type": "destination_chain_receive_observe",
            "executor_selector": {"action_type": "destination_chain_receive_observe", "chain_family": "evm"},
            "config": {
                "probe_key": "evm",
                "chain_id": 421614,
                "match_mode": "txid",
                "token_contract": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
                "token_decimals": 6,
                "amount_match": "at_least",
                "amount_floor_deduction_raw": 500
            },
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 900},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "mint_finality",
            "node_kind": "observe",
            "action_type": "destination_chain_finality_observe",
            "executor_selector": {"action_type": "destination_chain_finality_observe", "chain_family": "evm"},
            "config": {"probe_key": "evm", "chain_id": 421614, "confirmations_required": 2},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 300},
            "retry_policy": {},
            "risk_patch": {}
        }
    ],
    "edges": [
        {"from": "burn", "to": "attestation", "edge_type": "on_success"},
        {"from": "attestation", "to": "mint", "edge_type": "on_success"},
        {"from": "mint", "to": "mint_receive_observe", "edge_type": "on_success"},
        {"from": "mint_receive_observe", "to": "mint_finality", "edge_type": "on_success"}
    ],
    "approval_policy": {"mode": "manual_first"},
    "completion_policy": {"completion_assurance": "destination_finalized"},
    "risk_controls": {}
}

Key points:

Put the signer address in destination_caller (you can confirm it through signer health)
signer_selector: {"chain_family": "evm"} -> matches the active signer registry row
confirmations_required is required on the terminal node
Environment variables: MG_EVM_RPC_ENDPOINTS_JSON, MG_LOCAL_SIGNER_*

3. Gateway 3-Node (Base Sepolia -> Arbitrum Sepolia)

Immediate cross-chain transfer through the Gateway unified balance.

{
    "template_key": "gateway.base-to-arb-sepolia.usdc",
    "name": "Gateway USDC Base Sepolia -> Arbitrum Sepolia",
    "version": 1,
    "nodes": [
        {
            "node_key": "intent",
            "node_kind": "action",
            "action_type": "gateway_intent",
            "executor_selector": {"action_type": "gateway_intent", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "source_domain": 6,
                "destination_domain": 3,
                "source_chain_id": 84532,
                "destination_chain_id": 421614,
                "gateway_wallet": "0x0077777d7eba4688bdef3e311b846f25870a19b9",
                "gateway_minter": "0x0022222abe238cc2c7bb1f21003f0a260052475b",
                "source_token": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
                "destination_token": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
                "max_fee_raw": 2000000
            },
            "has_side_effect": true,
            "timeout_policy": {},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "mint",
            "node_kind": "action",
            "action_type": "gateway_mint",
            "executor_selector": {"action_type": "gateway_mint", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "destination_chain_id": 421614,
                "gateway_minter": "0x0022222abe238cc2c7bb1f21003f0a260052475b"
            },
            "has_side_effect": true,
            "timeout_policy": {},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "mint_finality",
            "node_kind": "observe",
            "action_type": "destination_chain_finality_observe",
            "executor_selector": {"action_type": "destination_chain_finality_observe", "chain_family": "evm"},
            "config": {"probe_key": "evm", "chain_id": 421614, "confirmations_required": 2},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 300},
            "retry_policy": {},
            "risk_patch": {}
        }
    ],
    "edges": [
        {"from": "intent", "to": "mint", "edge_type": "on_success"},
        {"from": "mint", "to": "mint_finality", "edge_type": "on_success"}
    ],
    "approval_policy": {"mode": "manual_first"},
    "completion_policy": {"completion_assurance": "destination_finalized"},
    "risk_controls": {}
}

Key points:

Gateway is faster than CCTP (no attestation polling; burn intent signature -> immediate mint)
Contract addresses differ by network - check Circle’s official docs
Environment variables: MG_GATEWAY_API_BASE_URL, MG_EVM_RPC_ENDPOINTS_JSON, MG_LOCAL_SIGNER_*

4. Multi-Hop 9-Node (Upbit -> Binance -> Base -> Gateway)

A composite CEX-to-CEX-to-chain-to-Gateway route. $ref: dynamically references output from earlier nodes.

Why multi-hop

Upbit does not support direct withdrawals to Base (only routes such as Tron/ERC-20 are available)
Route through Binance for the Base withdrawal, then deposit into Gateway

Graph Structure

Phase 1: CEX -> CEX (Upbit -> Binance, Tron USDC)
  [1] upbit_withdraw         -> action   FIRE
  [2] upbit_withdraw_observe -> observe
  [3] binance_deposit_observe -> observe

Phase 2: CEX -> On-chain (Binance -> Base)
  [4] binance_withdraw         -> action   FIRE  <- $ref:binance_deposit_observe.credited_amount
  [5] binance_withdraw_observe -> observe
  [6] base_receive_observe     -> observe

Phase 3: Gateway deposit (Base -> unified balance)
  [7] gateway_approve          -> action   FIRE  <- $ref:base_receive_observe.credited_amount
  [8] gateway_deposit          -> action   FIRE  <- $ref:base_receive_observe.credited_amount
  [9] deposit_finality         -> observe  DONE

`$ref:` Usage Points

Node	Config Key	Reference	Description
`binance_withdraw`	`amount`	`$ref:binance_deposit_observe.credited_amount`	Net credited amount after fees
`gateway_approve`	`amount`	`$ref:base_receive_observe.credited_amount`	On-chain received amount
`gateway_deposit`	`amount`	`$ref:base_receive_observe.credited_amount`	Same amount

Template JSON

{
    "template_key": "multihop.upbit_binance_base_gateway",
    "name": "Upbit -> Binance -> Base -> Gateway Deposit",
    "version": 1,
    "nodes": [
        {
            "node_key": "upbit_withdraw",
            "node_kind": "action",
            "action_type": "cex_withdrawal",
            "executor_selector": {"action_type": "cex_withdrawal"},
            "config": {
                "source_exchange": "upbit",
                "destination_exchange": "binance",
                "network": "tron",
                "asset": "USDC"
            },
            "has_side_effect": true,
            "timeout_policy": {"submit_seconds": 120},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "upbit_withdraw_observe",
            "node_kind": "observe",
            "action_type": "cex_withdrawal_status",
            "executor_selector": {"action_type": "cex_withdrawal_status"},
            "config": {"source_exchange": "upbit", "asset": "USDC"},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 1800},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "binance_deposit_observe",
            "node_kind": "observe",
            "action_type": "cex_deposit_status",
            "executor_selector": {"action_type": "cex_deposit_status"},
            "config": {
                "destination_exchange": "binance",
                "asset": "USDC",
                "network": "tron",
                "match_mode": "txid"
            },
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 3600},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "binance_withdraw",
            "node_kind": "action",
            "action_type": "cex_withdrawal",
            "executor_selector": {"action_type": "cex_withdrawal"},
            "config": {
                "source_exchange": "binance",
                "network": "base",
                "asset": "USDC",
                "amount": "$ref:binance_deposit_observe.credited_amount"
            },
            "has_side_effect": true,
            "timeout_policy": {"submit_seconds": 120},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "binance_withdraw_observe",
            "node_kind": "observe",
            "action_type": "cex_withdrawal_status",
            "executor_selector": {"action_type": "cex_withdrawal_status"},
            "config": {"source_exchange": "binance", "asset": "USDC"},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 1800},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "base_receive_observe",
            "node_kind": "observe",
            "action_type": "destination_chain_receive_observe",
            "executor_selector": {"action_type": "destination_chain_receive_observe", "chain_family": "evm"},
            "config": {"chain_id": 8453, "match_mode": "event"},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 600},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "gateway_approve",
            "node_kind": "action",
            "action_type": "gateway_approve",
            "executor_selector": {"action_type": "gateway_approve", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "source_chain_id": 8453,
                "source_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "gateway_wallet": "0x0077777d7eba4688bdef3e311b846f25870a19b9",
                "amount": "$ref:base_receive_observe.credited_amount"
            },
            "has_side_effect": true,
            "timeout_policy": {"submit_seconds": 60},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "gateway_deposit",
            "node_kind": "action",
            "action_type": "gateway_deposit",
            "executor_selector": {"action_type": "gateway_deposit", "chain_family": "evm"},
            "signer_selector": {"chain_family": "evm"},
            "config": {
                "source_chain_id": 8453,
                "source_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                "gateway_wallet": "0x0077777d7eba4688bdef3e311b846f25870a19b9",
                "amount": "$ref:base_receive_observe.credited_amount"
            },
            "has_side_effect": true,
            "timeout_policy": {"submit_seconds": 60},
            "retry_policy": {},
            "risk_patch": {}
        },
        {
            "node_key": "deposit_finality",
            "node_kind": "observe",
            "action_type": "destination_chain_finality_observe",
            "executor_selector": {"action_type": "destination_chain_finality_observe", "chain_family": "evm"},
            "config": {"probe_key": "evm", "chain_id": 8453, "confirmations_required": 12},
            "has_side_effect": false,
            "timeout_policy": {"observe_seconds": 300},
            "retry_policy": {},
            "risk_patch": {}
        }
    ],
    "edges": [
        {"from": "upbit_withdraw", "to": "upbit_withdraw_observe", "edge_type": "on_success"},
        {"from": "upbit_withdraw_observe", "to": "binance_deposit_observe", "edge_type": "on_success"},
        {"from": "binance_deposit_observe", "to": "binance_withdraw", "edge_type": "on_success"},
        {"from": "binance_withdraw", "to": "binance_withdraw_observe", "edge_type": "on_success"},
        {"from": "binance_withdraw_observe", "to": "base_receive_observe", "edge_type": "on_success"},
        {"from": "base_receive_observe", "to": "gateway_approve", "edge_type": "on_success"},
        {"from": "gateway_approve", "to": "gateway_deposit", "edge_type": "on_success"},
        {"from": "gateway_deposit", "to": "deposit_finality", "edge_type": "on_success"}
    ],
    "approval_policy": {"mode": "manual_first"},
    "completion_policy": {"completion_assurance": "destination_finalized"},
    "risk_controls": {"asset_allowlist": ["USDC"], "max_amount": "50000"}
}

Runtime Data Flow

How $ref: resolves during movement execution:

[3] binance_deposit_observe completes
    -> provider_refs: {"credited_amount": "9995.00", "txid": "T9f8a...", ...}

[4] At binance_withdraw dispatch time
    -> looks up "binance_deposit_observe.credited_amount" = "9995.00" in namespaced_refs
    -> config.amount: "$ref:..." -> replaced with "9995.00"
    -> the executor sees only the resolved config

[6] base_receive_observe completes
    -> provider_refs: {"credited_amount": "9995.00", "tx_hash": "0xabc...", ...}

[7] At gateway_approve dispatch time
    -> "base_receive_observe.credited_amount" = "9995.00"
    -> config.amount replaced

[8] gateway_deposit - same behavior

If the target key for $ref: does not exist, the node immediately becomes FAILED (error_code: CONFIG_REF_UNRESOLVED).

`$ref:` Rules Summary

Item	Rule
Format	`$ref:node_key.field_name` (exactly one `.`)
Scope	Top-level string values in `config` only (nested dict/list ignored)
Target	A key in `provider_refs` from an ancestor node in the DAG
Failure policy	Fail-closed - becomes `FAILED` if it cannot be resolved
`node_key`	`.` is forbidden
Executor impact	None - `provider_context` keeps the existing flat merge behavior

Common Pitfalls

Mistake	Symptom	Correct value
`edge_type: "then"`	422 rejection	`"on_success"`
`chain_id` (Gateway/CCTP config)	`MISSING_SOURCE_CHAIN_ID`	`source_chain_id` / `destination_chain_id`
Missing `has_side_effect`	hash mismatch	Declare it on every node
Missing `match_mode` on the terminal node	422 rejection	Required on `destination_provider_observe` / `destination_chain_receive_observe` family terminal nodes
Missing `confirmations_required` on the terminal node	422 rejection	Required on `destination_chain_finality_observe` family terminal nodes
`$ref:` target is a sibling	422 rejection	Only ancestors (earlier nodes) can be referenced
`node_key` contains `.`	422 rejection	`.` forbidden (conflicts with the `$ref` separator)

Full compilation behavior: docs/reference/compiler/plan-compilation.md

Next: 04-going-live.md - prepare for production deployment

Getting Started

Concepts

Guides

Template Cookbook

03 - Template Cookbook

Register from the Dashboard (Recommended)

Register Directly Through the API

Template Structure at a Glance

1. CEX 3-Node (Upbit -> Bybit XRP)

2. CCTP 5-Node (Base Sepolia -> Arbitrum Sepolia)

3. Gateway 3-Node (Base Sepolia -> Arbitrum Sepolia)

4. Multi-Hop 9-Node (Upbit -> Binance -> Base -> Gateway)

Why multi-hop

Graph Structure

`$ref:` Usage Points

Template JSON

Runtime Data Flow

`$ref:` Rules Summary

Common Pitfalls

​03 - Template Cookbook

​Register from the Dashboard (Recommended)

​Register Directly Through the API

​Template Structure at a Glance

​1. CEX 3-Node (Upbit -> Bybit XRP)

​2. CCTP 5-Node (Base Sepolia -> Arbitrum Sepolia)

​3. Gateway 3-Node (Base Sepolia -> Arbitrum Sepolia)

​4. Multi-Hop 9-Node (Upbit -> Binance -> Base -> Gateway)

​Why multi-hop

​Graph Structure

​$ref: Usage Points

​Template JSON

​Runtime Data Flow

​$ref: Rules Summary

​Common Pitfalls

03 - Template Cookbook

Register from the Dashboard (Recommended)

Register Directly Through the API

Template Structure at a Glance

1. CEX 3-Node (Upbit -> Bybit XRP)

2. CCTP 5-Node (Base Sepolia -> Arbitrum Sepolia)

3. Gateway 3-Node (Base Sepolia -> Arbitrum Sepolia)

4. Multi-Hop 9-Node (Upbit -> Binance -> Base -> Gateway)

Why multi-hop

Graph Structure

`$ref:` Usage Points

Template JSON

Runtime Data Flow

`$ref:` Rules Summary

Common Pitfalls