hyperlane-xyz/hyperlane-monorepo / .agents/skills/svm-warp-alt-manage
svm-warp-alt-manage
VerifiedCreate, check, and read on-chain Sealevel (SVM) Address Lookup Tables (ALTs) for a warp route. Use after deploying, extending, or upgrading an SVM warp route, when transfers fail with transaction-too-large errors, or when asked to inspect or verify a route's ALTs. Fee-enabled SVM transfers bundle 40+ accounts and require ALTs to fit under the 1232-byte tx limit.
SVM Warp ALT Management
Manage the on-chain Address Lookup Tables (ALTs) that a Sealevel warp route uses to compress its account list into a v0 VersionedTransaction. Fee-enabled SVM warp transfers reference 40+ accounts (core + fee + IGP + token plugin) and exceed Solana's 1232-byte transaction size limit without ALTs.
Wraps the hyperlane warp alt command group (typescript/cli/src/commands/warp-alt.ts): create, check, read.
When to Use
- Right after deploying a new SVM warp route (
/warp-deploy-init-route), extending one, or upgrading an SVM program (/svm-warp-program-upgrade) — ALTs must be (re)created. - SVM transfers fail with transaction-too-large / too-many-accounts errors.
- "check the ALTs for " / "are the lookup tables up to date?" →
check. - "show me the ALT contents for " →
read.
Model
Each Sealevel chain in the route has, in the registry warp config under options.sealevel.altAddresses.<chain>:
core— one chain-shared ALT (mailbox/core accounts, reusable across routes on that chain).warpSpecific— an array (min 1) of route-specific ALTs (this route's token/fee/IGP accounts).
ALTs are created on-chain, populated, then frozen. Frozen tables are immutable and their rent cannot be reclaimed — you never "edit" an ALT, you create a fresh one and update the registry pointer. This is why --force/--full-force leak the old (frozen) tables: they create new ones and abandon the old, unrecoverable ones.
Commands
All commands run from typescript/cli and require --warp-route-id. --chain is optional and scopes to a single chain (defaults to all Sealevel chains in the route). create needs write context (--key.sealevel + private RPC via HTTP registry); check and read are read-only.
create — build + persist ALTs
cd <MONOREPO_ROOT>/typescript/cli && pnpm --silent hyperlane warp alt create \
--registry http://localhost:<port> \
--key.sealevel "$SEALEVEL_KEY_VAR" \
-w <WARP_ROUTE_ID> \
[--chain <chain>]
- Default (no flags): creates ALTs only where the registry has none. Existing entries are left as-is.
--force/-f: recreate the warp-specific ALTs for chains that already have registry entries; the chain-sharedcoreALT is reused. Old warp-specific frozen ALTs are leaked (unrecoverable).--full-force/-F: recreate all ALTs includingcore. Implies--force. All old frozen ALTs leaked.- Writes the resulting ALT addresses back to the registry warp config (
options.sealevel.altAddresses).
Use plain create after a fresh deploy. Use --force after an upgrade/extend that changed the route-specific account set. Reserve --full-force for when the core ALT itself is wrong — it's the most wasteful (leaks the shared table too).
check — verify on-chain ALTs match expected
cd <MONOREPO_ROOT>/typescript/cli && pnpm hyperlane warp alt check \
--registry http://localhost:<port> \
-w <WARP_ROUTE_ID> \
[--chain <chain>]
Compares on-chain ALT contents against the expected account set for the route. Exits non-zero on drift — treat a non-zero exit as "ALTs are stale, recreate them". check reports core and warpSpecific drift separately, and the fix differs by bucket: recreate warpSpecific drift with create --force (reuses the shared core ALT); recreate core drift (including an unfrozen core) with create --full-force. Do NOT use --force for a core diff — it reuses the existing core, so the core stays broken and the next check still fails. Report the specific diff and its bucket to the user.
read — dump ALT contents
cd <MONOREPO_ROOT>/typescript/cli && pnpm hyperlane warp alt read \
--registry http://localhost:<port> \
-w <WARP_ROUTE_ID> \
[--chain <chain>] \
[--out <file.yaml>]
Read-only. Prints (or writes) the current on-chain ALT addresses and their entries. No key needed.
Execution Flow
- Start the HTTP registry per
/start-http-registry(needed for private Sealevel RPC; add--writeModeforcreate, omit forcheck/read). Note the port + task ID. - Run the requested subcommand (
create/check/read) against--registry http://localhost:<port>. - For
create: after success, confirm the registry warp config now hasoptions.sealevel.altAddresses.<chain>.{core,warpSpecific}and follow with acheckto prove no drift. - Stop the HTTP registry per
/stop-http-registry, even on failure. - If
createmutated the registry, open a registry PR with the updated warp config (thealtAddressesblock) so the ALT pointers are canonical.
Caveats
- ALTs are frozen and unrecoverable. Never assume you can reclaim rent or mutate a table.
--force/--full-forceintentionally abandon old frozen tables — only use them when the account set actually changed. - Always create ALTs after any deploy/extend/upgrade of an SVM route. Missing or stale ALTs are the usual cause of transaction-too-large failures on fee-enabled SVM transfers.
checkexit code is the signal — non-zero = drift; don't ignore it. Recreate and re-check.- Core vs warp-specific: match the fix to the drift bucket
checkreports —--forceforwarpSpecificdrift (keeps the shared core ALT),--full-forceforcoredrift. A--forcewon't touch the core, so using it on a core diff leaves the check failing. createneeds write context and a funded--key.sealevel;check/readdo not.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |