Thiagodeev/refactor-add-txn

[thiagodeev]

• solve @todo's
• apply the changes for other rpc pkgs as well
• improve the benchmark code since it will stay there

// session with the benchmark analysis
claude --resume e130bcb2-943a-4697-9228-572919f100c1

Summary

Refactor of the v10 AddTransaction / EstimateFee / Simulate / EstimateMessageFee flow to:

• Eliminate redundant Sierra class hashing and (more importantly) redundant Sierra→CASM compilation when the receivedTransactionFeed is enabled.
• Replace BroadcastedTransaction.ContractClass json.RawMessage with a typed ContractClass struct that mirrors the spec.
• Decouple EstimateMessageFee from EstimateFee.
• Drop fields/validators no longer required by Starknet RPC v0.10.2.
• Fix a v10 deploy_account v3 panic surfaced while writing benchmarks.

What changed

New types

• ContractClass, ContractClassEntryPoints, ContractClassEntryPoint (rpc/v10/transaction_types.go) replace the untyped json.RawMessage for the broadcast
  contract class. Field validation moves from runtime checks (almost no validation here) into struct tags.
• MessageFeePayload { L1Handler, PaidFeeOnL1 } (rpc/v10/estimate_fee.go) lets EstimateMessageFee build a core.L1HandlerTransaction directly without faking a
  BroadcastedTransaction.

Refactored adaptation

• New AdaptBroadcastedTransactionToCore(ctx, tx, classHash, network) in rpc/v10/adapt_transaction.go replaces AdaptBroadcastedTransaction. It accepts a
  pre-computed Sierra class hash (declare only) instead of recomputing it, and skips the BroadcastedTransaction → starknet.Transaction → sn2core.AdaptTransaction round
  trip in favor of dedicated adaptBroadcastedInvokeToCore / adaptBroadcastedDeclareToCore / adaptBroadcastedDeployAccountToCore helpers.
• New unexported helper adaptAndCompileBroadcastedTxToCore in rpc/v10/transaction.go runs compile + hash + adapt as a single unit, returning (coreTxn, *core.SierraClass, error). addToMempool, prepareTransactions (simulation), and the receivedTransactionFeed fallback in AddTransaction all share this helper.
• addToMempool now returns the adapted core transaction back to AddTransaction, which forwards it to the feed without re-adapting (and, for declare, without
  recompiling).
• pushToFeederGateway uses a new ContractClassToGatewayPayload(*ContractClass) to produce the gzip+base64 contract class payload from the typed struct, instead of unmarshaling into map[string]any, mutating, and re-marshaling. Notably this no longer mutates the caller's tx.ContractClass.

Spec / API surface

• Removed BroadcastedTransaction.PaidFeeOnL1 (L1_HANDLER is not broadcastable via RPC).
• Removed the custom validateResourceBounds tag in favor of validator.WithRequiredStructEnabled() plus plain validate:"required".
• ResourceBoundsMap.{L1Gas,L2Gas,L1DataGas} are now value types (ResourceBounds) instead of *ResourceBounds. Required by validator semantics and removes a layer
  of nil checks across the call chain.

Performance impact

Benchmarks added under rpc/v9/bench_addtxn_test.go and rpc/v10/bench_addtxn_test.go (full Handler.AddTransaction() end-to-end, 8×1s, paired with benchstat).
Stub compiler so the deltas reflect RPC-layer changes only; a separate real-compiler scenario uses compiler.NewUnsafe() (in-process FFI). Sierra fixture: real
8.9k-felt class from clients/feeder/testdata/sepolia-integration. Both mempool and receivedTransactionFeed are enabled in every iteration, matching the default
node config.

Stub compiler

                            v9 sec/op    v10 sec/op   Δ sec        Δ B/op      Δ allocs                                                                              

AddTxn_Mempool_Invoke 250.4 µs 124.5 µs -50.28% -59% -59%
AddTxn_Mempool_DeployAccount 994.8 µs 623.7 µs -37.31% -59% -58%
AddTxn_Mempool_Declare 104.90 ms 42.67 ms -59.32% -90% -84%
AddTxn_Gateway_Invoke 139.7 µs 139.9 µs ~ -7% -11%
AddTxn_Gateway_DeployAccount 399.7 µs 392.2 µs ~ -9% -13%
AddTxn_Gateway_Declare 34.5 ms 72.5 ms +110%* -18% -5%

Real compiler (FFI Sierra→CASM)

AddTxn_Declare_RealCompiler_Mempool 527.7 ms → 255.8 ms -51.53%
AddTxn_Declare_RealCompiler_Gateway 35.6 ms* → 283.1 ms correctness fix, see below

* The v9 gateway-declare numbers are misleading. pushToFeederGateway in v9 mutates tx.ContractClass in place (gzipping the Sierra program), and the subsequent
receivedTransactionFeed branch then tries to unmarshal that mutated payload back into a starknet.SierraClass — which fails (program is now a string, not
[]*felt.Felt) and gets logged as a warning. v9 silently drops declare submissions from the received-tx feed when the gateway path is used. v10 doesn't mutate the
input, so the feed branch publishes correctly. The "+110% / +695%" gateway-declare numbers are v10 doing the work v9 was silently skipping.

Where the wins come from on the mempool path

Stage	v9 (mempool + feed)	v10
Adapt broadcasted → core	2×	1×
compiler.Compile (Sierra → CASM)	2×	1×
sn2core.AdaptSierraClass (Poseidon over program + Keccak over ABI)	2×	1×
Class hash (CalculateSierraClassHash)	2×	1×
core.TransactionHash	2×	1×
Resource bounds + DA-mode adaptation	2×	1×

For nodes acting as both mempool source and feed source — the common production deployment — declare submissions are roughly 2× faster end-to-end with the real
compiler, and use ~65% fewer allocations.

Test plan

• go build ./... clean
• go vet ./rpc/v10/... ./core/... ./rpc/v9/... clean
• go test ./rpc/v10/... ./core/... passing
• Benchmarks for invoke / deploy_account / declare on mempool and gateway paths added in v9 and v10 (see rpc/{v9,v10}/bench_addtxn_test.go)
• Real-compiler benchmarks for declare on both paths (see BenchmarkAddTxn_Declare_RealCompiler_{Mempool,Gateway})
• Manual smoke test against Sepolia: invoke v3 / declare v3 / deploy_account v3 via mempool path
• Manual smoke test: same three via gateway path
• Confirm receivedTransactionFeed actually emits declare transactions on both paths

Follow-ups (not in this PR)

• pushToFeederGateway could compute the core txn for the feed at the same time it builds the gateway payload, eliminating the second adapt+compile on the gateway
  path. Would bring v10 gateway-declare from ~283 ms back down to ~35 ms while keeping the feed correct.
• v8/v9/v10 still carry near-identical copies of adaptCoreResourceBounds / feeder bounds adapters. Worth promoting to rpc/rpccore in a follow-up.
• ResourceBoundsMap.MarshalJSON default-fill should move to a constructor / decode hook rather than mutating a receiver inside a serializer.
• Add positive coverage for AdaptBroadcastedTransactionToCore (declare path) and ContractClassToGatewayPayload. Two // @todo add test markers remain.

[codecov]

Codecov Report

❌ Patch coverage is 45.09804% with 140 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.84%. Comparing base (4b37ae9) to head (214dfec).

Files with missing lines	Patch %	Lines
rpc/v10/adapt_transaction.go	45.00%	76 Missing and 1 partial ⚠️
rpc/v10/transaction.go	49.25%	27 Missing and 7 partials ⚠️
rpc/v10/estimate_fee.go	4.54%	21 Missing ⚠️
rpc/v10/simulation.go	73.91%	3 Missing and 3 partials ⚠️
rpc/v10/transaction_types.go	0.00%	1 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (45.09%) is below the target coverage (60.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3582      +/-   ##
==========================================
- Coverage   76.00%   75.84%   -0.16%     
==========================================
  Files         381      381              
  Lines       34222    34272      +50     
==========================================
- Hits        26009    25994      -15     
- Misses       6390     6459      +69     
+ Partials     1823     1819       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.