Talos Action Development and Maintenance

Runtime Model

• Author actions in tasks/actions/<actionName>.ts with the action({...}) wrapper from tasks/lib/action.ts.
• Actions self-register and run through tasks/run.ts; do not register ops tasks.
• Run an action locally with pnpm exec tsx tasks/run.ts <actionName> --network <network>. Treat a transaction-writing invocation as production-affecting.
• Production schedules are defined in migrations/seed_schedules.sql; the Talos runner loads the generated catalogue from actions-catalog.json.

Implement an Action

1. Match the filename and name with camelCase, and provide a clear description and explicit chains guardrail.
2. Define every CLI parameter with the params builder and keep names camelCase. The generated catalogue converts names to kebab-case flags.
3. Use the context's signer, chainId, networkName, log, and args. Initialise no independent provider or signer unless the action genuinely requires it.
4. Prefer getContract("DeploymentName") from tasks/lib/contracts for a direct committed deployment binding. For a proxy or interface call, use getContractAt() with a curated interface ABI or instantiate ethers.Contract with a narrow inline ABI.
5. Treat committed deployment artifacts, utils/addresses.js, and action-local chain maps as address sources. artifacts/ and Foundry build/deployments-<chainId>.json are not Talos runtime inputs.
6. Use named ethers contract methods and logTxDetails for write transactions. Avoid raw selector encoding and signer.sendTransaction({ to, data }) when the method is known.
7. Validate chain-specific addresses, deployment availability, and signer authority before a transaction. For Safe proposals, preserve simulation, nonce, and delegate checks.

Maintain Existing Actions

• Keep proxy ABI selection deliberate: a deployment artifact supplies an address, but its ABI may not expose an implementation method. Prefer curated abi/*.json interfaces for stable proxy calls.
• When a Foundry deployment changes an action target, update the corresponding deployment descriptor address or pinned action address in the same change.
• Preserve idempotency and useful action-specific logging. Do not turn a manual-only or proposal action into an enabled schedule without explicit authorization.
• Avoid co-scheduling two transaction-writing actions for the same signer in a five-minute window; check migrations/seed_schedules.sql.

Update Supporting Records

• Update docs/ACTIONS.md when a scheduled action or its operational behavior changes.

• Regenerate docs/talos-actions-inventory.md after action entry-point or local-import changes:

  node scripts/talos/action-chains.mjs > docs/talos-actions-inventory.md
  

• Rebuild the runtime catalogue when validating the action image:

  pnpm run dump-catalog
  

Verify

pnpm prettier:ts
pnpm typecheck

Run the smallest safe action-level validation available. Only invoke an action against a live network when the requested work authorizes its side effects.