Include internal admin-call handling in legacy snapshot extraction

[MontrealAI]

Motivation

• The legacy snapshot extractor previously only consumed top-level transactions and therefore missed admin updates executed via multisig/contract-wallet internal calls, which can silently under-capture moderator/allowlist/URI state.
• The change aims to make snapshot replay deterministic and complete by accounting for internal-call ordering and provenance so migrations reproduce live state accurately.

Description

• Added trace-aware replay utilities to scripts/snapshotLegacyMainnetConfig.js: parseTraceId(traceId) and compareReplayOrder(a, b), and included traceId in replay provenance so internal calls can be traced back to their context.
• When ETHERSCAN_API_KEY is present the script now fetches both account.txlist and account.txlistinternal, filters internals to those targeting the legacy address, merges + de-duplicates entries, and sorts by block/tx/index/trace order for deterministic replay.
• The extractor now fails loudly if txlistinternal contains internal calls to the legacy contract without calldata, and the HTML-scrape fallback will refuse to proceed when the snapshot owner is a contract wallet (enforcing ETHERSCAN_API_KEY in that case).
• Regenerated the pinned snapshot at block 23200000 (migrations/snapshots/legacy.mainnet.0x0178B6baD606aaF908f72135B8eC32Fc1D5bA477.json), added a migration migrations/2_deploy_agijobmanager_from_legacy_snapshot.js, renamed the deployment entrypoint to migrations/1_deploy_contracts.js, and updated docs and scripts/docs/generate-repo-map.mjs to reflect the migration rename.

Testing

• Ran the snapshot generator with MAINNET_RPC_URL=https://ethereum-rpc.publicnode.com node scripts/snapshotLegacyMainnetConfig.js --block 23200000 and it completed and wrote the snapshot JSON. (success)
• Ran the repo build with npm run build (Truffle compile) which completed successfully albeit with a bytecode-size warning for a test harness. (success)
• Ran docs checks with npm run docs:check which passed. (success)

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5bf2669483

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Require API replay when fallback cannot prove full history

The HTML fallback gate only checks whether owner is a contract at the snapshot block, but internal admin calls can still exist from earlier periods when ownership was a multisig/contract wallet; those calls are not discoverable via /txs?a=... scraping and will be silently omitted from replayed mutator state. This means the script can report success while producing an incomplete snapshot whenever historical owner type changed over time, so deterministic migration is not guaranteed unless txlistinternal data is required (or historical ownership is fully validated).

Useful? React with 👍 / 👎.