Generate TransactionCommonFields from rippled's getCommonFields() with a CI drift check #295

Summary

Generate the TransactionCommonFields trait (xrpl-common-stdlib/src/current_tx/traits.rs) from rippled's TxFormats::getCommonFields() instead of hand-writing each getter, and add a --check drift gate to CI, mirroring what ./scripts/generate-ledger-objects.sh already does for ledger-object field traits.

Motivation

Today the trait is 100% hand-written. Each new common field (e.g. get_delegate, added in the feat/add-delegate-tx-field branch) means a hand-written getter, doc comment, and a set of mock-based tests copied from a neighbouring getter. Nothing in CI notices when rippled adds a common field.

Compared against src/libxrpl/protocol/TxFormats.cpp on the ripple/se/supported branch (the default source the existing generators read), the trait is already missing five common fields:

A generator with a drift check would have surfaced all five.

Proposed approach

Reuse the machinery in tools/generateLedgerObjects.js rather than writing a parallel generator:

• Parse getCommonFields() from TxFormats.cpp ({sfX, SoeRequired|SoeOptional} entries, same shape as ledger_entries.macro).
• Resolve Rust types through the shared tools/sfieldTypeMap.js, emitting Result<T> for required fields and Result<Option<T>> for optional ones. Skip Array/Object fields (Memos, Signers) as the ledger-object generator does; they stay reachable via path().
• Emit to a new generated file (e.g. xrpl-common-stdlib/src/current_tx/generated/common_fields.rs) with the same banner, #[cfg(test)] mod tests block, and unmapped-type header the ledger-object generator produces.
• Fetch doc comments from the xrpl-dev-portal transaction common-fields page, analogous to the per-entry docs fetch for ledger objects.
• Add ./scripts/generate-tx-common-fields.sh with a --check mode, wire it into scripts/run-all.sh and .github/workflows/test.yml, and document it in CLAUDE.md's command list and generated-files sections.

Hand-written divergences to preserve

The current trait deliberately differs from rippled in four places. The generator needs per-field exclusions (like PER_ENTRY_EXCLUDED_FIELDS) so these can stay in a hand-written extension trait, or be relocated:

1. get_gas is not a common field. rippled declares sfGas as SoeOptional on ttESCROW_FINISH only, but the trait exposes it as a required Result<u32> on the common trait. It probably belongs in xrpl-escrow-stdlib (on EscrowFinish), and this work should decide that.
2. get_signing_pub_key is SoeRequired in rippled but returns Result<Option<PublicKey>> based on a 0-or-33-byte length check (empty means multi-signed), with a panic on any other length.
3. get_txn_signature is SoeOptional in rippled but the trait returns a required Result<SignatureBlob>.
4. The existing doc comments carry security notes and usage guidance that a docs-portal fetch may not reproduce. Decide whether to keep those getters hand-written or accept generated docs.

Acceptance criteria

• TransactionCommonFields getters for every field in getCommonFields() are generated, excluding Array/Object fields and the explicit exclusions above.
• The five currently-missing fields are exposed (or explicitly excluded with a documented reason).
• ./scripts/generate-tx-common-fields.sh --check runs in run-all.sh and CI and fails on drift.
• Generated tests cover the same Some/None/error/invalid cases the hand-written tests do today.
• get_gas placement is resolved (moved to xrpl-escrow-stdlib or kept with a documented rationale).
• CLAUDE.md, skills/xrpl-smart-escrows/reference/api-surface.md, and scripts/README.md are updated.

Related

• feat/add-delegate-tx-field branch: hand-written get_delegate, the change that prompted this proposal.
• feat: Remove float_root #283 (float_root removal) and the --check gate in scripts/generate-ledger-objects.sh for the drift-check pattern to copy.