Add Solana ALT operations skill

solana-alt-ops-skill/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: validate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: bash scripts/validate.sh

solana-alt-ops-skill/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.DS_Store
+coverage/
+campaigns/

solana-alt-ops-skill/DEMO.md

@@ -0,0 +1,69 @@
+# Demonstration: a safe ALT rollout plan
+
+This is an offline, fictional example. It deliberately does not create a
+table, connect a wallet, submit a transaction, or claim that a transaction
+landed on any cluster.
+
+## Scenario
+
+`RoutePilot` has a swap route that intermittently exceeds its legacy message
+budget. The route reuses three stable, non-signer program accounts, while the
+payer and user signer vary per request.
+
+## 1. Make the decision
+
+The operator collects an oversized legacy transaction, measures it, and
+confirms that a v0 message without a lookup table still cannot carry the
+repeated route accounts. The candidate accounts are stable and have recorded
+provenance. The result is **v0 with an ALT**, not “put every account in a
+table.”
+
+```text
+Static: payer, user signer, user token accounts, dynamic route accounts
+ALT:    fixed program IDs / fixed route accounts only
+Fallback: existing legacy route subset for clients without v0 support
+```
+
+## 2. Validate the proposed manifest
+
+```bash
+$ node scripts/validate-alt-manifest.mjs --strict fixtures/valid-manifest.json
+Valid ALT manifest: 1 table(s), 0 warning(s).
+```
+
+The manifest identifies a mutable table, its public authority, the multisig
+review process, the stable address set, and the static address set. It is only a
+review artifact; the operator must still fetch the real deployed table.
+
+## 3. Required evidence before a signer acts
+
+```text
+1. On-chain table owner and authority match the approved manifest.
+2. Table has remaining capacity and is not deactivating.
+3. Extension transaction contains only the reviewed incremental addresses.
+4. After confirmation, a later slot has passed.
+5. Fresh RPC fetch returns the expected address list.
+6. Exact v0 route compiles, has the expected static signer map, and simulates.
+7. A devnet or low-risk canary succeeds before wider rollout.
+```
+
+## 4. Rollout gate
+
+```text
+if wallet_v0_capable && table_fresh && v0_simulation_ok:
+    select ALT-backed v0 route
+else:
+    select existing tested fallback
+```
+
+The application emits the table version and selected path. If ALT-only compile,
+simulation, or signing failures rise, the feature flag disables new ALT traffic
+without trying to mutate the table during the incident.
+
+## 5. Retire later
+
+When a replacement table is live and no clients select the old version, the
+authorized operator deactivates the old table, waits until its deactivation slot
+is absent from `SlotHashes`, verifies that state, and closes it to a separately
+verified recipient. This never applies to a frozen table, because freezing
+removes the authority needed for deactivation and closure.

solana-alt-ops-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anant Garg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

solana-alt-ops-skill/README.md

@@ -0,0 +1,123 @@
+# Solana ALT Operations Skill
+
+Production operating guidance for Solana Address Lookup Tables (ALTs): deciding
+when they are justified, creating and extending them safely, composing v0
+transactions, and retiring tables without breaking users.
+
+This is deliberately not a generic transaction tutorial. It is a runbook for
+the awkward lifecycle problems that surface after an ALT becomes production
+infrastructure: authority ownership, same-slot activation, compatibility,
+rollbacks, observability, deactivation, and rent recovery.
+
+## Why this skill exists
+
+An ALT can replace repeated 32-byte account keys in a v0 transaction with
+one-byte indices. That makes complex routes and batched flows possible, but it
+also creates deployed state with its own authority and lifecycle. A careless
+table change can turn otherwise valid transactions into opaque client failures.
+
+This skill helps an agent produce an evidence-backed plan before it touches a
+table. It treats ALTs as versioned dependencies rather than a bag of public
+keys.
+
+## What it covers
+
+- A decision gate for legacy, v0-without-ALT, and v0-with-ALT transactions.
+- Immutable address manifests, ownership and change-control design.
+- Safe create, extend, activation, fetch, compile, simulate, and rollout flow.
+- v0 transaction composition with explicit fallback behavior.
+- Security review for mutable authorities, poisoned manifests, and stale RPC
+  responses.
+- Metrics, alert thresholds, incident triage, deactivation, and closure.
+- A dependency-free manifest validator with fixture-backed tests.
+
+## Install
+
+Review the repository before installing. The installer never overwrites an
+existing skill.
+
+```bash
+git clone https://github.com/anantgar/solana-alt-ops-skill
+cd solana-alt-ops-skill
+./install.sh             # ~/.claude/skills/solana-alt-ops
+./install.sh --project   # ./.claude/skills/solana-alt-ops
+```
+
+For other agent runtimes, copy the `skill/` directory into that runtime's
+skills folder.
+
+## Use it for
+
+```text
+"Our Jupiter route now exceeds the legacy transaction size. Decide whether an
+ALT is appropriate and create a safe rollout plan."
+
+"Review this ALT manifest before our multisig extends the production table."
+
+"A v0 transaction started failing after an ALT extension. Triage it without
+asking users to re-sign blindly."
+
+"We need to deprecate an ALT and recover its rent without breaking queued
+transactions."
+```
+
+## Validate an ALT manifest
+
+The validator catches inexpensive mistakes before a proposal reaches a signer:
+invalid public keys, duplicates, capacity overflows, unsafe mode/authority
+combinations, and missing operational ownership metadata.
+
+```bash
+npm test
+node scripts/validate-alt-manifest.mjs fixtures/valid-manifest.json
+node scripts/validate-alt-manifest.mjs --strict fixtures/valid-manifest.json
+```
+
+The validator is intentionally offline. It verifies a plan, not chain state.
+Before any mainnet action, independently fetch the table account from a trusted
+RPC and have the designated authority review the exact transaction bytes.
+
+## Repository layout
+
+```text
+skill/
+  SKILL.md                    Entry point and routing table
+  architecture.md             Decision, manifest, and ownership design
+  operations.md               Create/extend/rollout/retire runbook
+  transaction-composition.md  v0 construction and client compatibility
+  security.md                 Authority, integrity, and signing controls
+  testing.md                  Local, devnet, and production verification
+  observability.md            Metrics and incident triage
+commands/
+  plan-alt.md                 Discovery-to-rollout command contract
+  audit-alt.md                Read-only review command contract
+scripts/
+  validate-alt-manifest.mjs   Offline manifest validator
+fixtures/                     Good and intentionally broken examples
+tests/                        Node test coverage for the validator
+```
+
+## Non-negotiable safety rules
+
+1. Never put a signer in an ALT. Loaded addresses cannot sign a v0 message.
+2. Do not use addresses added in the current slot; fetch the table again after
+   the next slot and simulate the exact v0 message first.
+3. Do not silently switch an existing transaction path from legacy to v0.
+   Roll out behind a capability and error-rate gate.
+4. A frozen table has no authority. It cannot later be extended, deactivated,
+   or closed to reclaim rent. Freeze only deliberately.
+5. Do not promise a fixed deactivation duration. Closure becomes possible only
+   once the deactivation slot ages out of the `SlotHashes` sysvar.
+6. Never include private keys, seed phrases, raw signing payloads, or API keys
+   in a manifest, issue, PR, or agent transcript.
+
+## Sources
+
+- [Solana: Address Lookup Tables](https://solana.com/developers/guides/advanced/lookup-tables)
+- [Solana: Versioned Transactions](https://solana.com/docs/core/transactions/versioned-transactions)
+- [Solana: RPC JSON structures](https://solana.com/docs/rpc/json-structures)
+- [Official Address Lookup Table program](https://github.com/solana-program/address-lookup-table)
+
+## License
+
+[MIT](LICENSE)

solana-alt-ops-skill/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+This repository contains guidance and an offline manifest validator; it does
+not custody keys or submit transactions.
+
+Do not disclose private keys, seed phrases, API keys, confidential routes, or
+unreleased vulnerability details in public issues. For a security issue in the
+skill itself, open a minimal private-contact request through the repository
+owner's GitHub profile and include only the information needed to establish a
+secure channel.
+
+Operational advice in this skill is not a substitute for an independent review
+of the exact v0 message by the authorized signer(s).

solana-alt-ops-skill/agents/alt-operator.md

@@ -0,0 +1,20 @@
+# ALT operator
+
+Use this focused agent for planning and read-only audit work around Solana
+Address Lookup Tables.
+
+## Priorities
+
+1. Preserve signer and user safety over reducing transaction bytes.
+2. Ask for the cluster, table address, authority process, and fallback before
+   recommending any write.
+3. Fetch and distinguish live chain facts from an unverified manifest.
+4. Produce explicit evidence requirements and an owner handoff.
+5. Never request secrets or send/sign mainnet transactions.
+
+## Do not do
+
+- Treat a cached address array as a deployed table.
+- Recommend a table extension for an unprovenanced or user-controlled address.
+- Say a table can be closed immediately after deactivation.
+- Recommend freezing without explaining the permanent loss of the close path.

solana-alt-ops-skill/commands/audit-alt.md

@@ -0,0 +1,33 @@
+# /audit-alt
+
+Perform a read-only, evidence-based review of an existing Solana Address Lookup
+Table and its proposed manifest diff.
+
+## Required inputs
+
+- Cluster, RPC endpoint, and table address.
+- Manifest or proposed change diff.
+- Intended client/repository release that consumes the table.
+- Public authority/change-control details.
+
+## Audit checks
+
+1. Fetch and identify the table owner, authority/frozen state, deactivation
+   status, address count, last extension slot, and capacity.
+2. Compare chain addresses with the manifest; report missing, extra, duplicate,
+   and unprovenanced addresses.
+3. Check mode/authority/change-control consistency.
+4. Identify signer/static-key violations in the consuming v0 message design.
+5. Evaluate client, RPC, and decoder support for v0 messages.
+6. Provide a canary and rollback recommendation, not a write command.
+
+## Output format
+
+```text
+Verdict: ready / needs changes / blocked
+Facts observed:
+Manifest differences:
+Risks:
+Required evidence before approval:
+Recommended owner actions:
+```

solana-alt-ops-skill/commands/plan-alt.md

@@ -0,0 +1,31 @@
+# /plan-alt
+
+Produce a safe ALT rollout plan from a user's transaction-size or account-count
+problem. This command is planning only: it must not create, extend, freeze,
+deactivate, close, sign, or broadcast a table.
+
+## Required inputs
+
+- Cluster and target environment.
+- Current transaction path and exact failure/sizing evidence.
+- Known payer and signer roles (public identifiers only).
+- Proposed recurring non-signer accounts and their provenance.
+- Existing table address, if any.
+- Authority/change-control process and fallback path.
+
+## Output
+
+1. Legacy/v0/ALT decision record.
+2. Manifest draft compatible with `validate-alt-manifest.mjs`.
+3. Step-by-step create/extend → later-slot fetch → exact compile → simulation →
+   canary rollout plan.
+4. Wallet/RPC/indexer compatibility matrix.
+5. Rollback and retirement plan.
+6. List of actions reserved for the authorized operator.
+
+## Refuse / pause when
+
+- The user asks to provide or embed secrets.
+- The cluster/table/authority is unknown for a requested write.
+- Address provenance is absent or comes from an untrusted dynamic source.
+- There is no tested fallback and the change could affect users.

solana-alt-ops-skill/fixtures/invalid-manifest.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "cluster": "mainnet-beta",
+  "tables": [
+    {
+      "name": "bad",
+      "mode": "frozen",
+      "authority": "11111111111111111111111111111111",
+      "purpose": "too short",
+      "reviewedAt": "not-a-date",
+      "reviewedBy": "x",
+      "addresses": [
+        "not-a-public-key",
+        "not-a-public-key"
+      ],
+      "staticAddresses": []
+    }
+  ]
+}

solana-alt-ops-skill/fixtures/valid-manifest.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "cluster": "devnet",
+  "tables": [
+    {
+      "name": "swap-route-core-v1",
+      "address": null,
+      "mode": "mutable",
+      "authority": "11111111111111111111111111111111",
+      "changeControl": "multisig proposal with independent manifest review",
+      "purpose": "Stable non-signer program and route accounts for the v0 route compiler.",
+      "reviewedAt": "2026-07-10",
+      "reviewedBy": "protocol-ops",
+      "addresses": [
+        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+        "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+        "So11111111111111111111111111111111111111112"
+      ],
+      "staticAddresses": [
+        "11111111111111111111111111111111"
+      ]
+    }
+  ]
+}