Fetch Safe Tx Batch

---
name: fetch-safe-tx-batch
description: Fetch and decode a pending Safe (multisig) governance batch from the Safe Transaction Service into a chain-tagged transactions JSON file that `/warp-route-check` (or any downstream consumer with the same input shape) ingests. Safe-API integration only — no forks, no replay, no simulation.
---

# Fetch Safe Tx Batch — fetch + decode front end

Fetch a pending Safe / Heimdall multisig batch from the Safe Transaction Service, decode the MultiSend wrapper into inner transactions, tag each with the source `chainId`, and emit a single JSON file that `/warp-route-check` consumes. `/warp-route-check` then forks the touched chains, replays the batch under impersonated owners, self-relays any cross-chain ICA messages, and runs `hyperlane warp check` against the target registry config to verify the batch produces the desired state before anyone signs it.

This skill is intentionally narrow. The Safe Transaction Service integration (v2 endpoint URL, 308 redirect, MultiSend decode) is the only piece that's specific to Safe-style batches. Keeping it in its own skill leaves `/warp-route-check` generic — any chain-tagged transactions JSON works as input, regardless of whether it came from a Safe batch, a Heimdall queue, or a hand-rolled tx list.

## When to use

- An engineer shares Heimdall / Safe links for a warp route update and asks "do these txs lead to the desired config?"
- Before signing any warp route governance batch — the simulation downstream verifies the result against the target registry config.

## Input Parameters

| Parameter    | Required | Description                                                                                                                                                                       |
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `safe_txs`   | Yes      | One or more `(chainId, safeAddress, safeTxHash)` triples, or Safe / Heimdall URLs to derive them from. Multiple batches are concatenated into one chain-tagged transactions file. |
| `output_dir` | No       | Where to write the decoded files. Defaults to `~/.hyperlane/safe-batches/<timestamp>/`.                                                                                           |

Solana / Squads and other non-EVM legs cannot be EVM-forked — verify those separately. This skill handles EVM Safe batches only.

## Prerequisites

- `curl`, `python3`, `jq` on PATH. No `anvil` / `cast` / `forge` needed in this skill — those run in `/warp-route-check`.

## Instructions

### Step 1 — Fetch and decode each Safe batch

The Safe Transaction Service returns the batch as a single `MultiSend` (`multiSend(bytes)`, selector `0x8d80ff0a`). Decode it into the inner txs the Safe executes (`to`, `value`, `data`). Note the **308 redirect** (`-L`) and the **v2** endpoint.

First set up **one** clean working directory for this invocation. Never reuse a directory that already holds decoded files from a previous run — Step 2 merges by an explicit manifest, but a stale `*.decoded.json` left in the directory is still a corruption hazard, so fail closed if the target isn't clean:

```bash
WORK=${output_dir:-~/.hyperlane/safe-batches/$(date +%s)}
mkdir -p "$WORK/decoded"
if compgen -G "$WORK/decoded/*.decoded.json" > /dev/null; then
  echo "ERROR: $WORK/decoded already contains decoded files from a previous run;" >&2
  echo "use a fresh output_dir (or clear it) so stale batches are not merged." >&2
  exit 1
fi
: > "$WORK/manifest"   # exact list of files decoded in THIS invocation
```

Then, for each `(chainId, safeAddress, safeTxHash)` triple in `safe_txs`:

```bash
SAFE_TX_HASH=0x....              # from the Safe / Heimdall link
CHAIN_ID=1                        # the executing chain

# Resolve the Safe Transaction Service base URL for THIS chain from the local
# Hyperlane registry — the same source the infra Safe scripts use
# (chains/<chain>/metadata.yaml -> gnosisSafeTransactionServiceUrl). Never
# hardcode a host or assume mainnet.
META=$(grep -rlE "^chainId:[[:space:]]*${CHAIN_ID}[[:space:]]*$" "$REGISTRY_PATH/chains/"*/metadata.yaml | head -1)
[ -n "$META" ] || { echo "ERROR: no registry chain with chainId ${CHAIN_ID}." >&2; exit 1; }
BASE=$(grep -m1 "^gnosisSafeTransactionServiceUrl:" "$META" | sed 's/^[^:]*:[[:space:]]*//; s/[[:space:]]*$//; s#/*$##')
[ -n "$BASE" ] || { echo "ERROR: chainId ${CHAIN_ID} has no gnosisSafeTransactionServiceUrl in the registry." >&2; exit 1; }
# Match the SDK's normalizeSafeTxServiceUrl: append /api unless already present.
case "$BASE" in */api) TX_SERVICE="$BASE";; *) TX_SERVICE="$BASE/api";; esac

curl -sL "${TX_SERVICE}/v2/multisig-transactions/${SAFE_TX_HASH}/" \
  -o "$WORK/decoded/${CHAIN_ID}-${SAFE_TX_HASH}.json"

python3 - "$WORK" "$CHAIN_ID" "$SAFE_TX_HASH" << 'EOF'
import json, sys
W, chain_id, safe_tx = sys.argv[1], int(sys.argv[2]), sys.argv[3]
src = f"{W}/decoded/{chain_id}-{safe_tx}.json"
d = json.load(open(src))
raw = d['data'][2:]
assert raw[:8] == '8d80ff0a', "expected MultiSend"
rest = raw[8:]; length = int(rest[64:128], 16); packed = rest[128:128 + length * 2]
b = bytes.fromhex(packed); i = 0; out = []
while i < len(b):
    op = b[i]; i += 1; to = '0x' + b[i:i+20].hex(); i += 20
    val = int.from_bytes(b[i:i+32], 'big'); i += 32
    dl = int.from_bytes(b[i:i+32], 'big'); i += 32
    # Preserve the MultiSend operation (0 = CALL, 1 = DELEGATECALL). The fork
    # replay in /warp-route-check executes inner txs as plain CALLs, so a
    # delegatecall would be silently misrepresented — fail closed instead of
    # downgrading it. Warp-management batches are all CALLs; a delegatecall
    # here needs manual handling.
    if op != 0:
        sys.exit(f"inner tx {len(out)} of {chain_id}-{safe_tx} is a delegatecall "
                 f"(operation={op}); the fork replay only supports CALL — handle "
                 "this batch manually")
    out.append({
        'chainId': chain_id,
        'safeAddress': d['safe'],
        'safeTxHash': safe_tx,
        'to': to,
        'value': str(val),
        'operation': op,
        'data': '0x' + b[i:i+dl].hex(),
    })
    i += dl
json.dump(out, open(f"{W}/decoded/{chain_id}-{safe_tx}.decoded.json", 'w'), indent=2)
print(f"chainId={chain_id} safe={d['safe']} innerTxs={len(out)}")
EOF

# Record this file so Step 2 merges only what THIS invocation produced.
echo "$WORK/decoded/${CHAIN_ID}-${SAFE_TX_HASH}.decoded.json" >> "$WORK/manifest"
```

The executing **safe address** is each batch's `defaultSender` — `/warp-route-check` impersonates it on the fork. The inner txs typically split into:

- **Direct calls** on the local (executing-chain) routers: `enrollRemoteRouters` (`0xe9198bf9`), `enrollCrossCollateralRouters` (`0x081954bc`), `setDestinationGas` (`0xb1bd6436`), `setFeeRecipient` (`0xe74b981b`).
- **ICA fan-out** to remote chains: `callRemoteWithOverrides` (`0xeab4eaa4`) on the origin InterchainAccountRouter. Each carries inner enroll calls destined for a remote router — these only take effect after the dispatched message is **relayed** (handled in `/warp-route-check`).

### Step 2 — Combine decoded inner txs into one chain-tagged transactions file

Concatenate only the files decoded in **this** invocation (from the manifest — not a wildcard over the directory, which could pull in stale batches) into a single array and write to `<output_dir>/transactions.json`:

```bash
jq -s 'add' $(cat "$WORK/manifest") > "$WORK/transactions.json"
echo "total inner txs: $(jq 'length' $WORK/transactions.json)"
echo "unique chainIds: $(jq -r '[.[].chainId] | unique | join(",")' $WORK/transactions.json)"
echo "unique safe senders: $(jq -r '[.[].safeAddress] | unique | join(",")' $WORK/transactions.json)"
```

The resulting `transactions.json` is the format `/warp-route-check` expects in Step 5 (it `jq`'s `.[].chainId` and `.[].to`).

### Step 3 — Hand off to `/warp-route-check`

Tell the user:

> Decoded `<N>` inner txs across `<M>` chains. Output:
>
> - `<output_dir>/transactions.json` — combined chain-tagged batch (the file to pass to `/warp-route-check`)
> - `<output_dir>/decoded/<chainId>-<safeTxHash>.decoded.json` — per-source-batch decoded copy (debugging / per-batch inspection)
>
> Run `/warp-route-check` next, passing `<output_dir>/transactions.json` as the `transactions-file` input. It will fork every touched chain, impersonate each target's **current on-chain `owner()`**, replay the inner txs from that owner, self-relay any cross-chain ICA messages, and verify the resulting state against the target registry config.

**Caveat — sender vs. on-chain owner.** `/warp-route-check` replays from each target's queried `owner()`, **not** from the `safeAddress` recorded here. That is correct only when the recorded Safe IS the current on-chain owner of every target. When they differ — a direct Safe call whose target owner is a different address, or an ICA `callRemote` whose origin owner differs — the replay runs under the wrong sender and the result is not a faithful verification. Grouping/replaying by the recorded sender is a `/warp-route-check` change tracked as part-2; until then, do NOT treat this handoff as a verification gate for batches where the recorded Safe is not the target's current owner (fall back to the post-execution registry-PR CI).

End the message there. This skill does NOT run forks, replay txs, or call `warp check` — those are `/warp-route-check`'s responsibilities.

## Gotchas

- **Safe Tx Service URL**: use `-L` (308 redirect) and the `/api/v2/multisig-transactions/<safeTxHash>/` path.
- **MultiSend layout**: selector `0x8d80ff0a`; packed per inner tx is `op(1) to(20) value(32) len(32) data(len)`.
- **Inner-call selectors** (sanity-check the decode):
  - `enrollRemoteRouters` — `0xe9198bf9`
  - `enrollCrossCollateralRouters` — `0x081954bc`
  - `setDestinationGas` — `0xb1bd6436`
  - `setFeeRecipient` — `0xe74b981b`
  - `callRemoteWithOverrides` (ICA fan-out) — `0xeab4eaa4`
- **Non-EVM batches** (Solana / Squads) — out of scope for this skill. They reach signers via a different propose path (`file` submitter, manual hand-off) and don't pass through Safe Transaction Service.

## Related skills

- `/warp-route-check` — the simulation engine this skill feeds into.
- `/warp-fork` — lower-level fork primitive used by `/warp-route-check`.
- `/start-http-registry` — serve the target / PR registry to fork+check.
- `/self-relay-hyperlane-message` — deliver a dispatched ICA message manually (used inside `/warp-route-check`).