Changelog

Copy Markdown View Source

All notable changes to this project will be documented in this file.

[Unreleased]

[0.2.0] — 2026-05-05

Added

  • Cartouche.Transaction.V4 adds EIP-7702 set-code transaction support for Pectra-era authorization-list transactions (0x04). V4 mirrors the existing typed-transaction shape with RLP encode/decode, outer transaction signing/recovery, transaction hashing, and authorization tuple signing/recovery over the EIP-7702 0x05 || rlp([chain_id, address, nonce]) digest. A real mainnet type-4 vector pins raw signed transaction decoding, hash agreement, and both outer-signer and authorization-authority recovery.
  • Cartouche.Transaction.V3 now supports EIP-4844 blob transaction envelopes introduced with Dencun. The new typed transaction module encodes, decodes, signs, hashes, and recovers signers for canonical type-0x03 execution-layer payloads, including max_fee_per_blob_gas and blob_versioned_hashes, while keeping blob sidecars out of scope. A mainnet blob transaction fixture pins byte-for-byte RLP decoding, hashing, and sender recovery against live post-Dencun data. Closes ROADMAP Task 31 / INE-23.

Changed

  • INE-19 optional hieroglyph API adoption: ABI.method_id/1 now replaces local 4-byte selector hashing in lib/mix/cartouche.gen.ex:148 and lib/mix/cartouche.gen.ex:412, while preserving the full 32-byte event-topic hash separately; ABI.decode_error/2 now drives RPC revert decoding at lib/cartouche/rpc.ex:49, with Cartouche's existing full-signature error map contract preserved by mapping the decoded error name and selector back to the matching ABI definition. ABI.encode_packed/2 had no current adoption opportunity after searching lib/** for packed-encoding and keccak patterns.

Fixed

  • Cartouche.Typed return-shape coverage now pins the current private-helper behavior that unblocks the downstream Typed spec rewrite: primitive and custom-type encode_value_map/3 paths are exercised through hash_struct/3 as 32-byte EIP-712 hashes, find_type/2 is exercised through deserialize/encode callers for the {name, %Typed.Type{}} tuple handoff, and both no-match / multiple-match error branches are covered. The live implementation has no map-returning encode_value_map/3 branch; the map-shaped JSON path is pinned separately through serialize/1 so Tasks 19+20 can distinguish encode-data bytes from serialized value maps before rewriting specs. Closes ROADMAP Task 45 / INE-21.
  • INE-17 / Phase 11 decode_structs: true audit re-verified the generator emission shape after PR #24's false-positive closeout: lib/mix/cartouche.gen.ex emits return-field names only as strings in selector metadata (build_selector_fn/1 returns Macro.escape(selector)), not as compile-time atom literals. Both audited decode_structs: true paths therefore needed explicit handling before Hieroglyph 1.4's String.to_existing_atom/1 decode branch: generated exec_vm_* functions now call a generated private helper before ABI.decode/3, while Cartouche.Sleuth.query_v2/4 validates that runtime selector atoms already exist instead of minting caller-supplied atoms. The runtime validation now walks nested tuple and array return types, and generated test bindings were regenerated so fixture exec_vm_* paths carry the same helper. The new Sleuth regressions prove raw Hieroglyph decoding raises with a unique cold return-field atom absent, Cartouche's runtime-selector boundary fails safely without creating it, and nested cold tuple/array names are detected before decode.
  • Coverage now clears the VM dialyzer cleanup entry gate: focused ExUnit tests cover Cartouche.VM.Context.init_from/2 happy and edge setup paths plus the context display helpers, Cartouche.Erc20.Call balance/transfer public entry points, and the Cartouche.VM.InvalidVm raise/rescue contract. This unblocks the downstream Phase 5 none() cascade investigation and Phase 6 VM context type-alignment work without changing runtime behavior. Closes ROADMAP Task 46 / INE-22.
  • Cartouche.RPC.send_rpc/3 and Cartouche.Solana.RPC.send_rpc/3 now return {:error, {:invalid_params, reason}} when outbound JSON-RPC request encoding fails, instead of letting Jason.encode!/1 exceptions escape the documented return contract. Both transports catch Jason.EncodeError and Protocol.UndefinedError, document the invalid-params shape in doctests, and carry widened transport specs that match the audited runtime error paths (JSON-RPC error envelopes, invalid response sentinels, transport errors, decode errors, and the new request-encoding failure). Focused ExUnit assertions cover non-UTF-8 method binaries, tuple params, atom-keyed map params containing non-encodable values, and custom structs without encoders across both transports. Closes ROADMAP Tasks 14, 15, and 35 / INE-25.
  • Mix.Tasks.Cartouche.Gen coverage now clears the standard ≥80% gate using a small synthetic ABI fixture instead of regenerating production bindings. The new generator tests drive constructor, fallback, receive, event, error, no-argument, blank-name, tuple-argument, ABI-only JSON, AST-name fallback, invalid-file, usage-error, asymmetric bytecode, and emitted catch-all decoder paths through the public Mix task entrypoint. This closes ROADMAP Task 44 / INE-20 and unblocks the downstream Generator hardening bundle tasks (41 / 42 / 50 / 59-gen) without mutating lib/mix/cartouche.gen.ex.
  • Phase 11 Hieroglyph bug-fix audit: Cartouche now has targeted regression coverage for the silent Hieroglyph 1.0.0-1.2.0 fixes it depends on. Cartouche.Filter log decoding asserts indexed reference-type event params surface {:indexed_hash, topic}; generated contract call decoding preserves embedded NUL bytes in :string values; signed-int overflow at the ABI encode call layer raises an explicit signed-range error; and zero-length fixed arrays round-trip through ABI encode/decode without crashing. No Cartouche compensation code for the old Hieroglyph behavior was found or removed. Closes ROADMAP Phase 11 bug-fix audit / INE-18.

  • New Cartouche.Transaction.Call struct (destination: <<_::160>>, data: binary()) replaces the %V2{} masquerade for eth_call shapes. Generator-emitted Cartouche.Contract.Sleuth.build_trx_query/3 now returns %Call{} instead of a partial %V2{}; Cartouche.RPC dispatch extended to accept V1.t() | V2.t() | Call.t(). Eth_call params are not transactions — never signed, never broadcast — and the prior abstraction lie drove the invalid_contract cascade through Cartouche.Sleuth. Structural fix collapses the cascade without widening V2 to nullable. Closes ROADMAP Task 54 / INE-10; Task 49 (V2.encode/1 spec duplication) closes as superseded since the cascade is gone.

  • Cartouche.Trace.@type t (and nested Cartouche.Trace.Action) widened to admit nil on fields the runtime proves are optional, matching dialyzer's inferred shape from deserialize/1. Cartouche.TraceCall.@type t widened analogously. Action serialization now nil-safe. New ExUnit assertions in test/trace_test.exs and test/trace_call_test.exs ground the widened types against deserialize/1 JSON both with and without optional fields, per feedback_doctests_not_substitute_for_tests.md. Dialyzer drops trace.ex:408 invalid_contract and trace_call.ex:124 invalid_contract. Closes ROADMAP Phase 3 (Tasks 16+17+18) / INE-14.
  • Cartouche.Filter expired-filter recovery test (test/filter_test.exs) now asserts Process.get(:expired_seen) == true and Process.get(:new_filter_count) >= 2 after the existing receive asserts, pinning the recovery branch by fingerprint instead of relying solely on the mock returning data under a different filter id. A future implementation that silently retried on the same filter id and somehow satisfied the receive contract would now fail. Closes ROADMAP Task 58 / INE-15.
  • Cartouche.RecoveryBit doctests for normalize/2, normalize_signature/2, and recover_base/1 rewritten to chain-agnostic examples — they no longer bake the test-config chain_id=:goerli into expected output. EIP-155 chain-id-dependent behaviour (the :eip155-branch normalize/2 arithmetic and the recover_base(47) raise message) moved to focused ExUnit assertions in test/recovery_bit_test.exs per feedback_doctests_not_substitute_for_tests.md. Closes ROADMAP Task 39 / INE-7.
  • Cartouche.Wei.to_wei/1 now supports :eth inputs for whole integers and exact Decimal values, with :eth documented as the sole ETH-denomination atom (:ether is intentionally unsupported for short-form parity with :wei / :gwei). Decimal is lifted from a transitive dep to a direct runtime pin ({:decimal, "~> 2.0"}); sub-wei precision raises rather than silently rounding. Moduledoc updated to document the bare-integer-treated-as-wei form alongside the tagged-tuple denominations. Closes ROADMAP Task 74 / INE-13.
  • Cartouche.Receipt now preserves EIP-4844 receipt blob fee fields. Type-3 blob receipts decode blobGasUsed and blobGasPrice into new blob_gas_used / blob_gas_price struct fields, while pre-Cancun and non-blob receipts keep both fields as nil. Focused unit coverage pins populated, absent, and "0x0" boundary shapes; the mainnet integration suite adds a real post-Dencun type-3 receipt anchor. Closes ROADMAP Task 67.
  • Generator decode_error/1 template — collapsed dead if true do :not_found else {:ok, "Impossible", <<>>} end branch to def decode_error(_), do: :not_found (lib/mix/cartouche.gen.ex:186-197). Pre-existing Elixir 1.20 type-checker false positive (pattern can never match the type true) at lib/cartouche/contract/i_console.ex:18704 and lib/cartouche/contract/sleuth.ex:107 — never surfaced in CI before because the harness OOM'd during PLT construction before dialyzer reached analysis. Regenerated lib/cartouche/contract/{i_console,sleuth}.ex via mix cartouche.gen against sol/out/IConsole.sol/IConsole.json and priv/Sleuth.json respectively. Closes ROADMAP Task 42 (the dead-branch sub-item from the generator hardening pass).
  • Regenerated bindings now carry @moduledoc false + per-def @doc false + @spec ... :: term() from Task 73's generator pass (which previously only ran on test fixtures). Production lib/cartouche/contract/{i_console,sleuth}.ex were on the pre-Task-73 generator output until this commit. Permissive term() placeholders satisfy Doctor's presence-based gate; ABI type → Elixir type derivation remains pending under Task 50, along with .doctor.exs ignore_paths: [~r"^lib/cartouche/contract/"] removal.
  • KMS signer Goth credential-path coverage now exercises Goth.fetch!/1 end-to-end for both Ethereum secp256k1 and Solana Ed25519 CloudKMS signers. The tests use :meck to patch Goth globally, verify one fetch per credential-path call, and keep the existing Tesla.Mock Cloud KMS response fixtures as the HTTP layer. Closes ROADMAP Task 73.

Tooling

  • CI harness dialyzer step trimmed PLT scope via mix.exs dialyzer: [plt_add_apps: [:mix, :ex_unit], plt_ignore_apps: [:google_api_cloud_kms, :google_gax, :goth, :tesla, :jose]]. Pre-trim deps PLT spanned ~1044 modules, with the GCP cluster (google_api_cloud_kms ~600 generated modules + goth + google_gax + tesla + jose) being the bulk: ~387 dialyzer-expensive modules with auto-generated @specs and macro-heavy crypto. PLT construction OOM'd both the 16 GB ubuntu-latest runner (CI runs 25306079957, 25313348846, 25313517870 — all runner shutdown signal exit 143) AND a 48 GB local Mac (compressor + swap saturation, 21 GB RSS for 31 min wall, system CPU > user CPU 2:1). :plt_ignore_apps truly subtracts from the deps PLT app list (verified via deps/dialyxir/lib/dialyxir/project.ex:50-75 — Kernel.--(plt_ignore_apps())), not just from warning output. Trade-off: dialyzer no longer type-checks Cartouche.Signer.CloudKMS / Cartouche.Solana.Signer.CloudKMS interactions with GoogleApi.CloudKMS.V1.* / Goth.Token — acceptable since CloudKMS is an optional signer with narrow surface (4 distinct external functions × 2 callsites = 8 unknown_function warnings), Code.ensure_loaded?/1 guards keep runtime correctness independent of GCP deps presence, and the alternative is harness red on every PR until the runner gets an order-of-magnitude RAM bump.
  • New .dialyzer_ignore.exs with two file-scoped entries ({"lib/cartouche/signer/cloud_kms.ex", :unknown_function} + the Solana counterpart) suppressing the 8 GCP/Goth unknown_function warnings the PLT trim creates. Tighter than per-line (won't break on file edits), narrower than full-file (only unknown_function is suppressed — any other class of dialyzer finding in those files would still surface). Both files exist exclusively to wrap GCP signer code, so file-scope is the right granularity.
  • Reverted the .github/workflows/harness.yml swap step added at commit 8e44328 (16 GB swap via fallocate -l 16G /swapfile). ubuntu-latest images already ship with /swapfile active — fallocate against a live swap file returns ETXTBSY (fallocate: fallocate failed: Text file busy, exit 1, run 25314151347), failing the harness before dialyzer ever ran. With the :plt_ignore_apps trim above, the underlying memory pressure is addressed structurally; swap headroom becomes obsolete.
  • Dialyzer removed from cartouche's PR harness (.github/workflows/harness.yml) — last-resort, repo-specific, not a generic "drop dialyzer in CI" recommendation. After the :plt_ignore_apps trim above, cartouche's deps PLT still spans 621 modules and OOM'd the 16 GB ubuntu-latest runner mid-construction (run 25319850405 — runner has received a shutdown signal at 12:52:25 while adding 621 modules to dialyxir_erlang-27.3.4.11_elixir-1.18.4_deps-test.plt). The remaining cluster (hieroglyph, descripex, finch/mint/hpax/inets HTTP stack, ssl/public_key/asn1/crypto/xmerl OTP crypto+XML) doesn't have an obvious next "trim this and the rest fits in 16 GB" target — hieroglyph and descripex are first-party / consumed deeply by cartouche and excluding them would eliminate most of dialyzer's value. Bigger runners (ubuntu-latest-large, 32 GB) cost ~8× per minute, which is outsized for a personal pre-1.0 library where local dialyzer already works (warm priv/plts/ cache, ~30s incremental run). PR CI now runs format / compile (warnings-as-errors) / credo / doctor / sobelow / test+coverage; dialyzer signal stays available locally via mix dialyzer.json. Upstream confirms the carve-out shape: googleapis/elixir-google-api (the monorepo google_api_cloud_kms lives in) runs zero dialyzer in its own CI — .github/workflows/presubmit.yml only invokes mix do deps.get, test per changed client (the Mixfile generated from the protobuf templates ships no dialyzer: block, no :plt_optional flag, no PLT cache); 600+ generated REST modules × hundreds of clients × auto-generated @specs make dialyzer prohibitively expensive even for the package authors. Sibling deps (google_gax, goth, jose) similarly ship no dialyzer hints to consumers. The implicit upstream guidance is "don't bother dialyzing the cluster" — :plt_ignore_apps IS that, and there's no further upstream slimming path to leverage. For other repos: the recommended posture is to KEEP dialyzer in the harness by default; only drop it if the specific repo's CI shows the same OOM signature, and try :plt_ignore_apps for heavy generated-API deps before dropping. The elixir-ci-harness marketplace template (when propagated) will document this ordering — trim first, drop only as last resort. ROADMAP Task 76 captures cartouche-specific restoration paths (separate workflow on a larger runner / nightly cron / more aggressive PLT trim) for if/when cartouche outgrows local-only signal.
  • .sobelow-skips regenerated via mix sobelow --mark-skip-all to track line-number drift from the decode_error/1 template collapse (7 lines → 1 line in lib/mix/cartouche.gen.ex). Same three rules and same code paths — DOS.StringToAtom, Traversal.FileModule ×3 — pure line shifts, no new findings.
  • Mix.Tasks.Cartouche.Gen now emits @moduledoc false + per-def @doc false + @spec ... :: term() annotations on generated test-fixture modules via a new AST post-processor (annotate_internal_defs/1). Permissive term() placeholders satisfy Doctor's spec-coverage gate (presence-based, per memory feedback_doctor_internal_surface_convention.md); type fidelity follows in Task 50 once ABI type → Elixir type derivation is wired. Multi-clause functions get one annotation pair before the first clause (subsequent clauses skipped via a seen-set; duplicate @spec per arity is a compile error). Test fixtures test/support/cartouche/contract/{block_number,ierc20,rock}.ex regenerated; hand-converted test/support/{live,client,signer,solana_client,solana_signer,sleuth_handler,vm_test_helpers}.ex to the same shape. Known regen gap: the generator does not yet preserve the # credo:disable-for-this-file Credo.Check.Readability.MaxLineLength pragma that ierc20.ex needs for its 121-char bytestring topic-0 hash lines (636, 647) — re-added by hand for this commit; the proper fix (conditional pragma emission when long bytestring topics are detected) is captured by Task 50's scope. Production bindings under lib/cartouche/contract/{i_console,sleuth}.ex are intentionally NOT regenerated in this commit — they remain on the old (no @doc/@spec) generator output and the .doctor.exs ignore_paths: [~r"^lib/cartouche/contract/"] exclusion stays load-bearing until Task 50 closes both the regeneration AND the (now-also-needed) term() → ABI-derived type sweep.
  • Sobelow-skip fingerprints in .sobelow-skips re-numbered to track the annotate_internal_defs/1 insertion + its TODO(Task 50): comment block (File.read!/1 868 → 934, File.mkdir_p!/1 906 → 972, File.write!/3 907 → 973). Same three rules and same code paths — pure line-number drift from the new generator helpers above the affected sites. Verified via mix sobelow (clean output).
  • lib/cartouche/transaction.ex line 740: when guard collapsed to a single line (mix format outcome, no semantic change).
  • ExUnit coverage now ignores the generated Cartouche.Contract.IConsole binding via test_coverage: [ignore_modules: [Cartouche.Contract.IConsole]] in mix.exs, so headline mix test.json --cover percentages track hand-written code instead of generated bytecode wrappers.
  • GitHub Actions harness gate at .github/workflows/harness.yml runs mix compile --warnings-as-errors, mix format --check-formatted, mix credo --strict, mix doctor --failed, mix sobelow, and mix test.json --cover --cover-threshold 80 --summary-only --exclude integration on every PR targeting development and on every push to development. Closes the Codex-sandbox-blocked-hex.pm evidence gap (see project memory feedback_codex_sandbox_pr_gap.md) — Codex-delegated PRs now arrive with harness output as PR checks instead of needing the local reviewer to fetch the branch and re-run the suite. Single-row matrix (Elixir 1.18.4 / OTP 27.3); actions/cache@v4 keys on mix.lock hash and covers _build. Integration tests (mainnet archive node) are explicitly excluded from the gate via --exclude integration. Permissions scoped to contents: read; concurrency cancels in-progress runs on the same ref. (Dialyzer is not part of the harness — see ### Tooling above for the OOM rationale.)

[0.1.3] — 2026-05-02

Bumped

  • google_api_cloud_kms 0.38.1 → 0.43.0 (loosened mix.exs pin ~> 0.38.1 → ~> 0.43). Breaking change at 0.40.0 — cloudkms_..._get_public_key and ..._asymmetric_sign collapsed from arity 7/8 (split path components: (connection, project, location, keychain, key, version, ...)) to arity 4 ((connection, name, optional_params \\ [], opts \\ [])) where name is the full projects/{p}/locations/{l}/keyRings/{kc}/cryptoKeys/{k}/cryptoKeyVersions/{v} resource path. Both KMS signer modules (lib/cartouche/signer/cloud_kms.ex for Ethereum secp256k1 + lib/cartouche/solana/signer/cloud_kms.ex for Solana Ed25519) updated to construct the name string internally via a new private key_version_name/5 helper; public API of Cartouche.Signer.CloudKMS.{get_address,sign} and Cartouche.Solana.Signer.CloudKMS.{get_address,sign} is preserved — callers continue to pass (cred, project, location, keychain, key, version). Audit trail (hex tarball diff across 0.39.0 / 0.40.0 / 0.41.0 / 0.42.0 / 0.42.2 / 0.43.0): %PublicKey{algorithm:, pem:}, %AsymmetricSignResponse{signature:}, %Connection{}, and Goth/Tesla.Env.client() integration unchanged across all 5 minors; 0.43.0 adds :publicKey (ChecksummedData) + :publicKeyFormat to PublicKey additively. Pre-mutation coverage push (per critical-rules.md "RAISE COVERAGE BEFORE MUTATING") added focused ExUnit assertions for both modules: get_address/6 algorithm-mismatch error contracts on both, plus malformed-DER (wrong SubjectPublicKeyInfo OID) on Solana — Cartouche.Signer.CloudKMS 69.23% → 88.24%, Cartouche.Solana.Signer.CloudKMS 68.75% → 90.00%. The remaining uncovered lines on each module are exclusively the defp client(cred) do; %{token: token, type: "Bearer"} = Goth.fetch!(cred); Connection.new(token); end config-glue path, which (a) is not affected by this mutation, (b) requires :meck/Mox test infrastructure not currently in cartouche to exercise, and (c) sits below the 95% critical-tier gate strictly speaking — but the actually-mutated lines (resource-path construction + new arity-4 call sites) are 100% covered by the existing Tesla.Mock URL-pinning setup, which is the operative safety net for the API rewrite. Adding test mocking infrastructure for the Goth path is filed as a follow-up rather than blocking this dep refresh. Closes ROADMAP Tasks 24 + 25; Task 26 closed as superseded (EC_SIGN_ED25519 already shipped via Cartouche.Solana.Signer.CloudKMS in earlier work — the Phase 7.1 prose was stale on that point; no HMAC / attestation / new auth surfaces in 0.39 → 0.43 worth surfacing as Cartouche-level helpers).
  • junit_formatter 3.3.1 → 3.4.0 (loosened mix.exs pin ~> 3.3.1 → ~> 3.3). Passive ExUnit formatter, zero callsites in cartouche source — no API risk. Root cause for the prior "Update not possible" was commit 860ac52 ("Tighten dep pins to match refreshed lockfile") rewriting ~> 3.3 → ~> 3.3.1; loosening back to ~> 3.3 lets future patches land without re-triggering the pin gate. Closes ROADMAP Task 71.
  • bandit 1.10.4 → 1.11.0 (lock-only refresh — mix.exs pin ~> 1.10 already permitted 1.11.0). Single dev-only callsite (mix.exs tidewave alias, Bandit.start_link(plug: Tidewave, port: 4013)); the running Tidewave session keeps the old beam loaded until the user restarts, so the actual 1.11.0 boot is deferred to the next session — verified here only that the lock pins 1.11.0 and the test suite + dialyzer + credo + sobelow are clean against the new transitive set (thousand_island 1.4.3, plug 1.19.1, websock 0.5.3). Closes ROADMAP Task 72.

Documentation

  • Cartouche.Recover promoted from internal (@moduledoc false) to a documented public module. The three primitives — recover_eth/2, recover_public_key/2, find_recid/3 — were already @doc'd with full doctests and referenced by name in the README's operator-keys-vs-end-user-wallets prose, so the existing state was incoherent (module attribute said "internal", per-function docs said "use me, here's how"). Drops @moduledoc false and adds a moduledoc covering the EIP-191 personal_sign framing, the two accepted signature shapes (%Curvy.Signature{} struct vs raw 65-byte <<r::256, s::256, v::8>>), the three recid encodings the v byte may carry (raw 0/1, personal_sign 27/28, EIP-155 35 + 2 * chain_id + recid), and the two consumer audiences (internal Cartouche.Signer recover-and-verify path; external user-supplied signature verification e.g. MetaMask / WalletConnect). Pre-1.0 is the cheap window to formalise this surface; doing it post-1.0 would awkwardly relabel a module downstream consumers had already informally pinned to. The accompanying prefix_eth/1 docstring is rewritten to spell out the four-part byte structure (0x19 version byte + "Ethereum Signed Message:\n" prefix + decimal-ASCII length + message) and to flag that the \x19 and \n in the doctest output are the literal bytes — newcomers reading the rendered HexDocs page were misreading them as escape syntax. README's "Modules at a glance" table gains a Cartouche.Recover row between Cartouche.Typed (EIP-712) and Cartouche.RecoveryBit (v-byte normalisation), grouping the three signature-side primitives together. Also fixes the long-standing "Etheruem" typo in the prefix_eth/1 docstring inherited from upstream signet. Doc-only — no library code changed; the public function set is unchanged. Future agent-economy work (descripex api() annotations) deliberately deferred — see internal discussion 2026-05-02 — pending a Cartouche.Verify facade design that exposes hex-string-shaped agent verbs over the byte-binary primitives Recover speaks.

Roadmap

  • ROADMAP Task 68 ("Cartouche.DebugTrace.StructLog — add EIP-7702 opcodes (AUTH, AUTHCALL)") closed obsolete 2026-05-01. The task's two technical premises were both wrong, verified against the EIP-7702 spec, ethereum.org/roadmap/pectra, and go-ethereum master core/vm/opcodes.go (Codex consultation independently corroborated, pulling geth master + v1.14.12 + the EIP-3074 spec page which now displays a 🛑 Withdrawn badge). (1) AUTH (0xf6) and AUTHCALL (0xf7) were EIP-3074 opcodes — that spec is withdrawn and never reached any client. EIP-7702 is the replacement for 3074, swapping the new-opcode design for delegation indicators (0xef0100 || address) on existing CALL-family opcodes (geth's enable7702 in core/vm/eips.go:571–575 adjusts gas only, no opcode slots). (2) Pectra activated mainnet 2025-05-07 at epoch 364032 — bundling 10 EIPs that ship zero new opcode mnemonics. The current closed whitelist (lib/cartouche/debug_trace.ex:56–67) covers all live mainnet opcodes; 7702 delegation txs decode cleanly because the on-the-wire op strings remain standard CALL-family. The "Avoid anchors involving post-EIP-7702 traces until Task 68 lands" reservation in Task 62's notes (downstream of the same misunderstanding) was relaxed in the same edit. No production-code changes — the closure is roadmap hygiene against a corrected technical premise.
  • ROADMAP Task 70 filed (Phase 0.5, 🔶 blocked on Fusaka/Osaka mainnet activation): add CLZ (0x1e, EIP-7939) to the DebugTrace opcode whitelist. CLZ is in geth master's newOsakaInstructionSet() per EIP-7607 Osaka composition; once Osaka activates and the mnemonic emitted in struct-logs is confirmed against an Osaka testnet trace, add the atom + a round-trip regression test. Replaces the abandoned Task 68 with the correctly-scoped forward-compat task surfaced by Codex's read of geth master.

[0.1.2] — 2026-05-01

Changed

  • Refreshed deps to current hex versions and tightened mix.exs pins to match what the lockfile (and test suite) is now built against:
    • hieroglyph 1.0.0 → 1.4.0; pin ~> 1.0 → ~> 1.4 (consumer-visible — raises floor to >= 1.4.0). Picks up the decode_structs: true String.to_existing_atom hardening (atom-table DOS guard, see ROADMAP Phase 11 advisory) plus the silent bug-fix windfall from 1.0.0–1.2.0 (indexed reference-type event params returning {:indexed_hash, _}, :string decode no longer truncating at NUL, encode_int/2 overflow guard, dynamic?/1 no longer crashes on T[0]).
    • ex_dna 1.4.1 → 1.4.3 (dev/test only, pin ~> 1.3 → ~> 1.4).
    • ex_ast 0.5.0 → 0.8.1 (dev/test only, pin ~> 0.5 → ~> 0.8).
  • Hieroglyph 1.4.0 brings two new transitive deps into the lockfile (descripex 0.6.0, json_spec 1.1.1) — surface-only for hieroglyph's self-describing api() macro; cartouche doesn't import either directly.
  • Phase 11 advisory audit (the two decode_structs: true callsites at lib/mix/cartouche.gen.ex:611-614 and lib/cartouche/sleuth.ex:91-128) verified safe under the offline test suite — atoms are pre-interned at module-compile time in both paths. Integration coverage for the Sleuth runtime path remains unverified this run.

[0.1.1] — 2026-05-01

Added

  • ROADMAP Block decoder bundle (Tasks 63 + 64 + 65) — Cartouche.Block extended with seven Ethereum hard-fork fields that the integration suite (Task 61) had pinned with refute Map.has_key?/2 decoder-gap assertions: base_fee_per_gas (London, EIP-1559), withdrawals_root + withdrawals (Shanghai, EIP-4895), parent_beacon_block_root (Cancun, EIP-4788), blob_gas_used + excess_blob_gas (Cancun, EIP-4844), and mix_hash (pre-Merge PoW mix hash; post-Merge PREVRANDAO per EIP-4399). All seven fields are ... | nil in @type t so pre-fork blocks deserialize cleanly through the existing map(x, f) nil-tolerant helper. withdrawals decodes to [Cartouche.Block.Withdrawal.t()] | nil via a new nested Cartouche.Block.Withdrawal submodule (mirrors the Cartouche.Receipt.Log precedent — own defstruct, @type t, deserialize/1, doctest) carrying index, validator_index, address, amount per EIP-4895. The empty-list boundary ("withdrawals": [] → withdrawals: [], distinct from absent → nil) is explicitly tested so consumers can detect Shanghai+ blocks with no withdrawals in this slot. Block doctest split into pre-London (existing fixture) and post-Cancun (new) shapes for documentation; load-bearing assertions live in test/block_test.exs's new describe "deserialize/1 — fork-tier optional fields (Tasks 63 + 64 + 65)" and describe "Cartouche.Block.Withdrawal.deserialize/1 (Task 64)" blocks per feedback_doctests_not_substitute_for_tests.md — covering pre-London nil defaults, the post-London base_fee_per_gas boundary, the post-Shanghai withdrawals-list-of-structs shape with non-empty + empty boundaries, the post-Cancun all-fields-populated shape, the cross-fork mix_hash decode, the zero-amount Withdrawal boundary, and the uint64-max amount round-trip. Integration tests at test/rpc_integration_test.exs strengthen the three prior refute blocks to positive assertions: post-London 15M anchor (assert b.base_fee_per_gas > 0), post-Shanghai 18M anchor (assert [%Cartouche.Block.Withdrawal{} | _] = b.withdrawals, byte_size(b.withdrawals_root) == 32), post-Cancun 20M anchor (32-byte parent_beacon_block_root, integer blob_gas_used + excess_blob_gas, 32-byte mix_hash). RPC doctests at lib/cartouche/rpc.ex:463/522 (get_block_by_number/2 and get_block_by_hash/2) updated to reflect the new struct shape — the mock test client at test/support/client.ex:893 already returns mixHash in its fixture, so the doctests show mix_hash populated and the six other new fields as nil. Pre-mutation gate cleared (Cartouche.Block already at 100% coverage); post-mutation Cartouche.Block and Cartouche.Block.Withdrawal both at 100%; dialyzer clean on block.ex; total invalid_contract count holds at 8 (no regressions). The :include_transaction_details opt remains hardcoded transactions: [] per ROADMAP Task 66 (filed standalone, separate concern). A new TODO(Task 66): marker at lib/cartouche/block.ex:294 makes that deferral visible to credo. Closes ROADMAP Tasks 63, 64, 65.

  • Mainnet archive integration test suite (test/rpc_integration_test.exs) with Cartouche.Test.Live helper module (test/support/live.ex). Opt-in via mix integration or mix test --include integration; excluded from mix test.json by default. The suite ground out two real Task-60-class wire-format bugs the mock client had been masking — both fixed in this release; see Fixed entries below.
    • Methods covered (13 read-only): eth_chainId, eth_blockNumber, eth_gasPrice, eth_maxPriorityFeePerGas, eth_getBlockByNumber, eth_getBlockByHash, eth_getTransactionReceipt, eth_getCode, eth_getBalance, eth_getTransactionCount, eth_call, eth_estimateGas, eth_feeHistory. Trace methods (trace_transaction, trace_call, trace_callMany, debug_traceCall) deferred to v2 — see ROADMAP Task 62.
    • Anchor strategy: historical mainnet data at four fork-tier blocks (pre-London 10M, post-London 15M, post-Shanghai 18M, post-Cancun 20M), plus type-0 + type-2 receipt anchors and WETH9 code/balance/nonce anchors at block 18M. The chain is immutable, so assertions are deterministic forever.
    • Architectural pattern: per-call client: Finch + ethereum_node: <url> opts (CCXT-style local-object pattern modeled on ../ccxt_client/test/support/integration_helper.ex). No Application.put_env mutation, no on_exit cleanup, tests stay async: true. Required a private :client opt on Cartouche.RPC.send_rpc/3 — every wrapper already forwards opts, so this propagates transparently to all 16 method wrappers without further surface changes.
    • Setup / failure mode: default node URL http://127.0.0.1:8545 (the blockwatch-one SSH tunnel: ssh -L 8545:127.0.0.1:8545 -L 8546:127.0.0.1:8546 blockwatch-one); override via CARTOUCHE_LIVE_NODE_URL. Cartouche.Test.Live.assert_node_available!/0 flunks loudly with multi-line tunnel-setup instructions when the node is unreachable, and with a chain-id-mismatch message when the node responds but isn't mainnet — never silent skips.
    • Decoder gaps surfaced: pinned with # TODO(integration-gap, ROADMAP Task NN): comments adjacent to refute Map.has_key? assertions — Tasks 63 (Block base_fee_per_gas), 64 (Block withdrawals), 65 (Block Cancun fields), 67 (Receipt EIP-4844 blob fields). Tasks 62 (trace methods), 66 (Block.transactions full-detail), and 68 (DebugTrace EIP-7702 opcodes) are filed for follow-up — no integration anchor yet.
    • Mix wiring: integration: ["test --only integration"] alias, integration: :test in cli/0 preferred_envs, test_helper.exs now ExUnit.start(exclude: [:integration]).

Fixed

  • Cartouche.RPC.get_block_by_hash/2 was sending only [block_hash] on the wire — JSON-RPC eth_getBlockByHash requires two params: [blockHash, fullTransactionObjects]. Real mainnet nodes (verified 2026-04-30 against the local archive tunnel) responded {:error, %{code: -32602, message: "Invalid params"}}; the mock client at test/support/client.ex:881 accepted the single-param shape and returned a fixture, masking the bug for the entire history of the upstream signet codebase. Same Task-60 class as the integer-block-param bug fixed in 0.1.0. Fix: get_block_by_hash/2 now reads :include_transaction_details from opts (default false, matching get_block_by_number/2's contract) and forwards both params on the wire. Mock client's eth_getBlockByHash/1 widened to eth_getBlockByHash/2 with a default-false second arg to match the new wire shape. Discovered by the new mainnet integration suite at first run — exactly what the suite is designed to catch.
  • The V1 call-params builder (private to_call_params/2 in Cartouche.RPC) for Cartouche.Transaction.V1 encoded the data field via Cartouche.Hex.encode_short_hex/1, which strips leading zeros and produces "0x0" for empty calldata. Real mainnet nodes reject data: "0x0" with -32602 Invalid params — the JSON-RPC DATA type requires bytes-preserving hex ("0x" for empty, full-width otherwise). The mock client accepted any value, masking the bug. Fix: V1's data now uses Cartouche.Hex.encode_big_hex/1, matching V2's encoding (which was already correct). The other V1 fields (gasPrice, gas, value) stay on encode_short_hex — they're QUANTITY type, where "0x0" is the spec-mandated form. Discovered by the integration suite's eth_estimateGas test for a simple ETH transfer with empty calldata.

[0.1.0] — 2026-04-30

First active release under the cartouche namespace. Ports the signet codebase under the Cartouche module tree with Elixir 1.20 compatibility, a published-on-hex ABI dep (hieroglyph), and a cleaned-up dialyzer baseline.

Fixed

  • ROADMAP Phase 1 closeout — Cartouche.Wei.to_wei/1 spec narrowed integer() | {integer(), :wei | :gwei}) :: integer() → non_neg_integer() | {non_neg_integer(), :wei | :gwei}) :: non_neg_integer(), with matching amount >= 0 guards on all three clauses. Wei is a discrete count by domain — every internal caller (Cartouche.Transaction constructors at :67/:70/:384/:386/:389, Cartouche.RPC fee-suggestion fallbacks at :1569/:1584/:1591) already passes non-negative values; the spec was simply loose. Negative inputs now raise FunctionClauseError at the contract boundary instead of silently propagating a nonsense wei count downstream. New describe "spec boundaries (Phase 1.2)" block in test/wei_test.exs pins the zero boundary in all three clauses, the large-value identity round-trip, the :gwei multiplier, and the negative-input rejection — grounded as ExUnit assertions per feedback_doctests_not_substitute_for_tests.md. Cartouche.Wei coverage stays at 100%; full suite green; dialyzer clean on wei.ex. Closes ROADMAP Tasks 7+8+9, completing Phase 1 (1.1 RecoveryBit, 1.3 Signer mfa(), 1.4 Hex returns already shipped). The downstream onchain @dialyzer {:no_match} strip across Onchain.Hex / ABI / ERC / ENS / Multicall callers becomes load-bearing once cartouche 0.1.x ships (Task 6).

  • Cartouche.Trace.deserialize/1 no longer raises Protocol.UndefinedError on RPC payloads with missing or nil traceAddress. The Enum.map(params["traceAddress"], &decode_address_or_number/1) line at trace.ex:423 (tracked under TODO(Task 55) since Tasks 51 + 52) now routes through a decode_trace_address/1 helper that raises ArgumentError, "missing traceAddress in trace_transaction result element" when the key is absent or nil, and maps the list otherwise. The audit attached to ROADMAP Task 55 (Codex consultation 2026-04-26 reviewing OpenEthereum + Infura trace_transaction schemas) confirmed traceAddress is mandatory at the wire — the root call shows [], not omission — so the right contract is "loud reject", not soft || [] (which would silently coerce corrupt nodes' output). New describe "deserialize/1 — traceAddress absent/nil (Task 55)" block in test/trace_test.exs pins both the missing-key and explicit-nil shapes via assert_raise ArgumentError, ~r/missing traceAddress/. Cartouche.Trace coverage stays at 100%; full suite green; dialyzer clean on trace.ex. Closes ROADMAP Task 55.

  • Cartouche.RPC.get_block_by_number/2 and 9 companion JSON-RPC callsites no longer send raw integers as block parameters. The @spec declared non_neg_integer() | String.t() and the doctest at lib/cartouche/rpc.ex:450 exercised get_block_by_number(55) — but send_rpc/3 Jason.encode!s params verbatim, so the integer hit the wire as [55, false] and any real Ethereum node responded {:error, %{code: -32602, message: "Invalid params"}} (verified 2026-04-28 against a live mainnet reth tunnel). The mock test client at test/support/client.ex accepted any value, masking the bug for the entire history of the upstream codebase. Fix shape: a new public Cartouche.Hex.encode_quantity/1 produces JSON-RPC-spec-compliant lowercase quantity strings (0 → "0x0", no leading zeros, lowercase hex digits) — distinct from encode_short_hex/1, which is uppercase by design for transaction-field encoding. A private normalize_block_param/1 helper inside Cartouche.RPC (integer → Cartouche.Hex.encode_quantity/1, binary passthrough) is applied at all 10 callsites that forward a block tag: get_block_by_number/2, get_nonce/2, call_trx/2, estimate_gas/2, get_code/2, get_balance/2, get_transaction_count/2, trace_call/3, trace_call_many/2, and debug_trace_call/2. The existing integer doctest at :450 continues to pass — the mock returns the same fixture for any block param — and now accurately documents real-node behavior. New ExUnit coverage: a describe "encode_quantity/1" block in test/hex_test.exs (zero, small int, single-digit, large multi-byte block number, all-letter hex, negative-rejection) per critical-rules.md "Doctests Are Documentation, Not Tests"; and a describe "block-param wire encoding" block in test/rpc_test.exs using a CaptureClient test double that delegates to Cartouche.Test.Client while sending the decoded JSON-RPC body back to the test pid — pins the integer-in → "0x37"-on-wire wiring through the public get_block_by_number/2 path and proves companion normalization via get_balance/2 + get_nonce/2 opt-reader assertions. Pre-mutation coverage gate: Cartouche.Hex already 100% (Phase 1.4 closeout); Cartouche.RPC 91.55% module-level, but the touched functions are 100% covered — the 18 uncovered RPC lines are entirely in untouched error-path code (Solidity Panic decoding, prepare_trx, execute_trx, fee history, trace_revert) and tracked separately. README's RPC example block restored to chain eth_block_number/0 → get_block_by_number(int) (the original honest shape that motivated the bug discovery) alongside the "latest" form. Closes ROADMAP Task 60.

  • ROADMAP Phase 1.4 — Cartouche.Hex return-shape spec audit closeout. The five spec corrections (decode_hex/1, from_hex/1, from_hex!/1, decode_hex_number/1, plus the private decode_hex_/1) had previously shipped as a drive-by under commit 8d4bc18 ("doctor, credo fixes", 2026-04-26): {:ok, t()} | :error → {:ok, t()} | :invalid_hex on the four soft-return functions and t() -> String.t() → t() -> t() on from_hex!/1, matching the actual runtime return shape of the private helper. This commit grounds the corrections so a future onchain audit doesn't have to reverse-engineer them: (a) failure-path doctest added to from_hex/1 (parity with decode_hex/1 — both now show :invalid_hex on bad input); (b) raise-path doctest added to from_hex!/1 (parity with decode_hex!/1 — both now show the Cartouche.Hex.InvalidHex exception); (c) new describe "spec boundaries (Phase 1.4)" block in test/hex_test.exs pinning all four corrected return shapes as ExUnit assertions per the project rule that doctests are documentation, not load-bearing tests for spec contracts. Bundled with the closeout: a describe "deep_encode_binaries/1" block covering the four previously-uncovered lines of the @doc false recursive helper, lifting Cartouche.Hex coverage 94.29% → 100% and clearing the ≥95% critical-tier gate prophylactically for any future Hex mutation. No runtime behavior change. Dialyzer outcome: 0 hex.ex warnings (unchanged — the spec corrections were already absorbed); total invalid_contract count remains 8 (the 6 in sleuth.ex are tracked under Task 54, the 2 in typed.ex under Tasks 19+20). Onchain's @dialyzer {:no_match} strip on Onchain.Hex and the cascading ABI / ERC / ENS / Multicall callers becomes load-bearing once cartouche 0.1.x ships (Task 6). Closes ROADMAP Tasks 10+11+12+13.

  • Cartouche.Transaction.V1 r/s/v storage unified to integers throughout, settling a Schrödinger spec that produced three different runtime shapes for the same field. V1.t() declared r: integer(), s: integer(), v: integer(), but add_signature/2 (lib/cartouche/transaction.ex:170) stored r/s as 32-byte binaries (matched out of <<r::binary-size(32), s::binary-size(32), v::binary>>), while V1.new/7 and V1.decode/1 stored them as integers. The mismatch was latent until a public-API path exercised it: V1.decode → recover_signer raised ArgumentError on any signed legacy RLP transaction, because get_signature/1's second clause built the signature with <<r::binary-size(32), …>> and decode/1 had stored r/s via :binary.decode_unsigned/1. add_signature/2 now :binary.decode_unsigned/1s the incoming r/s segments so they match the spec and the other constructors; get_signature/1's second clause now rebuilds the signature with <<r::big-256, s::big-256, v_enc::binary>> — byte-equivalent to the prior 32-byte binary form, so add_signature → get_signature round-trips bit-for-bit and the chain-side recovery doctest still passes unchanged. Side benefit: add_signature(...) |> encode() now produces canonical RLP for r/s (leading zeros stripped) — the prior binary form was technically non-canonical on the wire. Bundled hardening from the staged-review pass: V1.decode/1 now guards byte_size(r) <= 32 and byte_size(s) <= 32 on the 9-element RLP shape, returning {:error, "invalid legacy transaction"} on adversarial input with >32-byte r/s — without the guard, the new <<r::big-256>> reconstruction in get_signature/1 would raise ArgumentError on r ≥ 2^256 reachable through decode → recover_signer. The add_signature doctest in transaction.ex was updated to show r: 1, s: 2 post-call (the only doctest whose expected output changed). New ExUnit describe "V1 (Task 53)" block in test/transaction_test.exs covers the malformed-RLP fallback in decode/1 (closing the coverage gate), the full build_signed_trx → encode → decode → recover_signer round-trip (the previously-broken path; failed pre-fix exactly as the type system predicted), the empty-sig boundary (r:0, s:0 → recover_signer reports missing signature), and the adversarial 33-byte r/s fixture asserting {:error, "invalid legacy transaction"} — four cases grounded as ExUnit assertions per critical-rules.md "Doctests Are Documentation, Not Tests". Coverage on Cartouche.Transaction.V1 93.33% → 100%; dialyzer drops transaction.ex:169 invalid_contract (count 9 → 8); 748/748 tests green. Closes ROADMAP Task 53; Phase 0.4 is fully cleared and Task 6 (mix hex.publish) is the only remaining 0.1.0 item.

  • Cartouche.Solana.Transaction.deserialize/1 and sign_partial/2 were specced as well-formed but raised on malformed input. deserialize/1 (specced {:ok, t()} | {:error, term()}) raised FunctionClauseError on empty / truncated compact-u16 prefixes (both decode_compact_u16_acc/3 clauses required <<byte, rest::binary>>), FunctionClauseError on sub-3-byte message headers (the only deserialize_message/1 head-clause required three header bytes), and MatchError on truncated instruction bodies (three raw <<...>> = rest matches in read_instructions/3 body). Hardened with a private safe_decode_compact_u16/1 returning {:ok, val, rest} | {:error, :truncated_compact_u16} (public decode_compact_u16/1 tuple contract preserved); a read_instructions/3 rewrite using with + a read_size_prefixed/2 guard helper that mirrors the existing read_signatures/3 / read_pubkeys/3 shape, plus a fallback (_, _, _) -> {:error, :insufficient_instruction_data} clause; and a deserialize_message(_) -> {:error, :invalid_message_header} fallback. sign_partial/2 evaluated Enum.map(0..-1, …) on a 0-signer message and produced two zero-filled placeholder signatures instead of the empty list its [<<_::512>>] field type implies; the range now carries an explicit //1 step (0..(n - 1)//1), giving the empty range when n == 0 (also silences the Elixir 1.20 deprecation on the unstepped form). Both behaviours grounded by new ExUnit describe blocks in test/solana/transaction_test.exs covering <<>>, truncation at every section boundary (compact-u16, signatures, header, pubkeys, blockhash, instruction header / accounts / data), and the synthetic zero-signer boundary — 10 new test cases, all assert {:error, _} / boundary-shape assertions per critical-rules.md "NEVER HIDE TEST FAILURES". Coverage on Cartouche.Solana.Transaction 95.56% → 98.97%; full suite green; dialyzer clean on the touched file. Closes ROADMAP Tasks 56 and 57.

  • Cartouche.Trace.t().trace_address and Cartouche.TraceCall.t().trace were typed as singular values but always built as lists at runtime — trace_address via Enum.map(params["traceAddress"], …) and trace via Cartouche.Trace.deserialize_many/1 (whose @spec returns [t()]). Consumer code pattern-matching on the documented singular shape would have raised MatchError on every real trace_transaction / trace_callMany response. Specs narrowed to [<<_::160>> | integer()] and [Cartouche.Trace.t()] respectively. Behavior-preserving — the runtime always returned lists; only the contract documentation was wrong. Dialyzer drops the trace.ex:412 and trace_call.ex:124 invalid_contract warnings (invalid_contract count 11 → 9). New focused ExUnit blocks in test/trace_test.exs and test/trace_call_test.exs ground the list shapes against edge cases (mixed-element union [42, <<_::160>>], empty list, deserialize_many/1 round-trip) — the existing doctests cover the happy path as documentation but read as prose, so the new assertions pin the spec shape against boundary conditions doctests don't exercise. Closes ROADMAP Tasks 51 + 52. A latent crash on missing/nil traceAddress (the Enum.map(nil, _) path at trace.ex:423) is tracked under TODO(Task 55) and filed as ROADMAP Task 55 for follow-up — the test suite intentionally does not pin the broken behavior with assert_raise per critical-rules.md "NEVER HIDE TEST FAILURES".

Documentation

  • README's Solana example block modernized to use the Cartouche.Solana.Signer GenServer (Signer.address/0, Signer.sign/1) instead of raw seed handling, paralleling the Ethereum example's reliance on Cartouche.Signer. Adds Cartouche.Solana.Transaction.serialize_message/1 to the example for explicit message-byte handoff to the signer. Old shape used an undefined fee_payer_seed variable inherited from upstream — the new example is runnable end-to-end against a configured signer. A trailing prose note links offline (raw-seed) signing via Transaction.sign/2 and sponsored-transaction signing via sign_partial/2 + add_signature/3. README-only; no library code change.
  • Doctor-driven typespec + docstring sweep across lib/cartouche/**. Adds .doctor.exs (min_*_coverage: 100, failed: false, ignores Mix.Tasks.Cartouche.Gen and lib/cartouche/contract/ — Doctor's source-level AST walker counts the generator's def unquote(name)(args) literals inside quote do blocks as defs of the Mix task itself, producing 23 false-positive missing-doc warnings; BEAM introspection confirms only run/1 is exported). Adds missing @spec and/or @doc/@doc false entries on 18 modules: Cartouche, Cartouche.{Application, Assembly, Block, Erc20, Filter, Hash, Hex, Keys, OpenChain, Recover, RPC, Signer, Sleuth, Transaction, Typed, VM}, and Cartouche.Solana.Programs. Behavior-preserving — pure documentation/typespec coverage.

Fixed

  • Cartouche.Signer.start_link/1 and Cartouche.Signer.sign_direct/4 specs: replace the Erlang mfa() BIF (which is {module(), atom(), arity :: non_neg_integer()}) with {module(), atom(), [any()]} to match what the impl actually receives — an args list, not an arity. Fixes the dialyzer signer.ex:141 invalid_contract warning that ROADMAP Phase 1.3 tracked, and forestalls the same regression that was about to ship via the new start_link spec. Bundled with the typespec sweep above per the touched-files credo rule.

  • Cartouche.get_contract_address/1 spec: widen the input type from Cartouche.contract() (which excludes hex strings — address() :: <<_::160>>) to binary() | atom() to match the impl, which routes any is_binary/1 value through Cartouche.Hex.decode_hex_input!/1 (handles both 20-byte raw binaries and "0x..." hex strings, per the function's own doctest).

  • Cartouche.Transaction.V1.add_signature/2 spec: return type tightened from the %__MODULE__{} literal to t() for consistency with V2.add_signature/2,4.
  • Cartouche.Transaction.V2.add_signature/2 (binary form): tighten the second-arg spec from loose binary() to <<_::512, _::_*8>> to match the pattern (r::32, s::32, v::binary — at least 64 bytes), aligning with V1's spec.

Security

  • Cartouche.DebugTrace.StructLog.deserialize/1 no longer mints atoms from RPC input. The previous implementation called String.to_atom(params["op"]) for every entry of an eth_debug_traceCall structLogs array — thousands of opcodes per trace — which let a buggy or compromised RPC node permanently grow the BEAM atom table (default cap ~1M; exhaustion crashes the VM). The hardened path defines a closed compile-time map of every Cancun-era EVM opcode (single-name + PUSH1..32 / DUP1..16 / SWAP1..16 / LOG0..4 ranged families) and resolves opcodes via Map.fetch/2. The whitelist also carries two alias pairs verified against go-ethereum's core/vm/opcodes.go master: KECCAK256 / SHA3 for opcode 0x20 (SHA3 covers pre-1.8 Geth and some non-Geth nodes), and DIFFICULTY / PREVRANDAO for opcode 0x44 (current Geth still emits "DIFFICULTY" — the rename TODO is still open in go-ethereum master, so without DIFFICULTY the whitelist would crash on every modern Geth trace; PREVRANDAO is forward-compat for clients that already emit the post-Merge name). Unknown strings raise ArgumentError carrying the offending value, surfacing future-EVM additions as visible failures instead of silent corruption. New regression coverage in test/debug_trace_test.exs (per-family boundary tests + nil/invalid rejections) and a non-async atom-table-stability test in test/debug_trace_atom_safety_test.exs (1000-iteration loop with novel-looking opcode strings; asserts the atom_count delta is ≪ iterations after a warmup pass that lets ExUnit/Logger machinery settle). Sobelow's DOS.StringToAtom finding at lib/cartouche/debug_trace.ex:71 (fingerprint 4F16CCA) is removed from .sobelow-skips. Audit of remaining String.to_atom callsites in lib/cartouche/sleuth.ex (the query_by/3 atom-deriving pair plus name_keyword/1) is tracked as ROADMAP Task 48 — those are bounded by compile-time atoms but warrant the same String.to_existing_atom treatment after raising Sleuth coverage to the 95% gate. The Mix-task callsite at lib/mix/cartouche.gen.ex:817 is dev-time only and stays in .sobelow-skips.

Changed

  • Breaking: rename Cartouche.Hex.HexError → Cartouche.Hex.InvalidHex and Cartouche.VM.VmError → Cartouche.VM.InvalidVm for consistency with the codebase's Invalid* exception strategy (InvalidAssembly, InvalidCode, InvalidOpcode, InvalidFileError). Public callers that rescue Cartouche.Hex.HexError / rescue Cartouche.VM.VmError must update. Settles cleanup.md B7 in favor of consistency over the no-breakage option, since cartouche is pre-1.x. Affects all decode_hex!/decode_address!/decode_word!/decode_sized!/decode_hex_number!/encode_address raise paths and Cartouche.VM.exec/3's error-rescue path.
  • Tooling: add .credo.exs (strict, with TagTODO: [exit_status: 2] to keep TODOs visible per project policy and Refactor.FunctionArity max_arity: 12 to permit Transaction.V2's EIP-1559-mirroring constructors), .sobelow-conf (exit: "Low"), and .sobelow-skips (fingerprints for two runtime String.to_atom callsites in Cartouche.Sleuth.query_by/3 bounded by compile-time-known atoms (full audit tracked as Task 48), one build-time String.to_atom callsite in the generator's contract-name binding (lib/mix/cartouche.gen.ex:817), and three File.* traversal flags in the generator's IO writers). The previously-suppressed runtime String.to_atom in Cartouche.DebugTrace.StructLog.deserialize/1 is now hardened (see Security above) rather than suppressed.
  • Cross-module helper-extraction refactor to bring mix credo --strict to zero issues on lib/cartouche/{assembly,hex,open_chain,rpc,sleuth,solana/token,solana/transaction,typed,vm}.ex. Extractions: Assembly.resolve_jump_ptr/2; OpenChain.decode_response/1 + pick_signature/3 clauses; RPC.error_matches?/2 + classify_decoded_error/2 (Panic dispatch table) + build_revert_data/2 + decode_revert_error/2 + decode_result/4 + log_decode_error/4 + resolve_gas_limit/4 + maybe_trace_revert/6 + do_estimate_and_verify/2 + apply_trace/6; Sleuth.{with_indexed_name,fallback_name,to_named_pair,name_keyword,obvious_results}/*; Solana.Token.{summarize_balance,accumulate_token_amount,maybe_include_token_2022}/*; Solana.Transaction.{merge_instruction_accounts,merge_account_meta}/2; Typed.type_fields_match?/2; VM.Operations.{do_sign_extend,extend_with_sign}/*, VM.{handle_static_call_result,pad_or_truncate_return}/*, ~25 do_* opcode-handler helpers, and pure safe_floor_div/safe_rem/safe_addmod/safe_mulmod/int_lt/int_gt/int_eq/int_is_zero callbacks for the unsigned_op*/signed_op* dispatch. Behavior-preserving — mix test.json --quiet green pre-commit. Two # credo:disable-for-next-line Refactor.CyclomaticComplexity retained on Assembly.show_opcode/1 and VM.run_single_op/3 (EVM opcode-dispatch tables — splitting would add indirection without reducing real complexity), one Readability.FunctionNames disable on Base58.sigil_B58/2 (Elixir requires sigil names start with uppercase), and two credo:disable-for-this-file Readability.{MaxLineLength,FunctionNames} on test-support files for generated bytestring fixtures and JSON-RPC method-name parity respectively.

Fixed

  • Cartouche.Sleuth.try_apply now uses reraise __STACKTRACE__ instead of raise inside the rescue, preserving the original exception's stacktrace alongside the descriptive RuntimeError message about the missing bytecode/0 (or other required) function. Settles cleanup.md B8.
  • Cartouche.OpenChain.lookup_* decode_response/1 now returns {:error, "unexpected response shape: ..."} for any successfully-decoded JSON envelope that doesn't match the OpenChain {ok: true, result: …} / {ok: false, error: …} contract, instead of raising CaseClauseError. Pre-existing gap surfaced when the inline case was extracted into the helper.
  • Cartouche.OpenChain.lookup/3 raise_on_multiple: true path: Enum.join(found_signatures, ",") was iterating a list of {sig, name} tuples and crashing Protocol.UndefinedError instead of returning {:error, "Multiple matching signatures: ..."}. Fixed at lib/cartouche/open_chain.ex:200 with Enum.map_join(found_signatures, ",", fn {_, name} -> name end) so the error message now lists the actual signature names. Surfaced during the Task 43 coverage push while writing the multi-result error-path test; per critical-rules.md "NEVER HIDE TEST FAILURES" the test asserts the corrected return shape rather than pinning the broken raise.

Tests

  • Pre-credo coverage push (ROADMAP Task 43) on the six modules slated for credo-strict cleanup, so the refactor session can rename / restructure / silence flags safely. New ExUnit blocks added to test/assembly_test.exs, test/receipt_test.exs, test/open_chain_test.exs, test/transaction_test.exs, test/sleuth_test.exs, test/solana/signer_test.exs. Highlights: data-driven show_opcode/1 table covering every named arm in Cartouche.Assembly (PUSH/DUP/SWAP/INVALID tuple coverage + show-only atoms :blobhash/:blobbasefee/:log) plus compile/1 3–7-operand cases, transform_jumps missing-jump-dest path, full PUSH1–32 / DUP1–16 / SWAP1–16 disassembly, per-clause opcode_size/1, and exception-struct defaults; contract-creation Cartouche.Receipt with to: nil/contractAddress populated and log shapes for empty / 2-topic / 4-topic data; Cartouche.OpenChainTest.TestClient extended with magic-byte signature dispatch (0xee000001–05) routing to ok=false / non-JSON-body / transport-error / multi-result / empty-result paths in one async-safe inline client, plus lookup_error / lookup_error_and_values short-binary clauses and Signatures.deserialize/1 filter behaviour; V2 transaction roundtrip through Cartouche.Test.Signer.start_signer/0 + signer recovery, plus V2.new/9 chain-id-nil fallback, V2.new/12 nil-fee passthrough, ABI-tuple vs raw-binary build_trx_v2 call-data, callback-short-circuit on build_signed_trx_v2, and V2.decode/1 malformed-RLP rejection; Cartouche.Sleuth.try_apply rescue exercising the descriptive RuntimeError when the contract module is missing bytecode/0; explicit cache-hit test for Cartouche.Solana.Signer using :sys.get_state/1 to confirm the :address key is populated after the first address/1 call. No new test files; no new test dependencies (compile-time module substitution via config/test.exs already in place — no Mox/Bypass).

Changed

  • Generator gates exec_vm_* emission on real bytecode. Mix.Tasks.Cartouche.Gen now treats nil, blank strings, "0x", and "0x" <> whitespace as missing bytecode (new blank_bytecode?/1 predicate in lib/mix/cartouche.gen.ex), and the :pure dispatch branch now requires has_bytecode before emitting exec_vm_fn / exec_vm_raw_fn. Without both, the generator was emitting def bytecode, do: hex!("0x") (compile-time <<>>) plus a :pure branch that always emitted exec_vm_* — producing 762 exec_vm_* functions in Cartouche.Contract.IConsole (Hardhat console.log interface, no on-chain bytecode) that called Cartouche.VM.exec_call(<<>>, ...) and always raised VmError. Dialyzer flagged each as no_return, cascading to 1534 of 1626 total warnings. New regression tests in test/mix/cartouche_gen_test.exs cover the four blank-bytecode shapes plus the working real-bytecode path. Drops Cartouche.Contract.IConsole.{bytecode/0, deployed_bytecode/0, exec_vm_*} from the generated module (RPC-side encode_* / call_* / execute_* family preserved); regenerated file is 18705 lines (was 28084). Bundled with the bug fix: the four pre-existing credo issues in lib/mix/cartouche.gen.ex (L153 nesting in rename_dups/1, L170 cyclomatic in get_encode_calls/2, L247 cyclomatic in encode_function_call/3, L337 nesting) are resolved by extracting accumulate_named_abi/2 + dedup_named_abi/5 + maybe_rename_dup_fn/5 (rename-dups), merge_encode_call_result/2 (encode-calls reducer), and ~16 build_*_fn/1 helpers + select_emitted_fns/3 + supporting argument-spec helpers (encode-function dispatch). Generator output AST is byte-identical to pre-refactor for i_console.ex (verified via the new cartouche_gen_test.exs suite). One additional post-process: strip_zero_arity_def_parens/1 rewrites def name() → def name on emitted defs (the macro source must keep the parens — def unquote(name)() is the canonical AST shape; without parens, unquote(:foo) produces a literal-atom AST and won't compile), eliminating ~382 ParenthesesOnZeroArityDefs flags from generated i_console.ex without manual annotation. String.to_atom/1 callsites in 6 generator helpers carry # sobelow_skip ["DOS.StringToAtom"] annotations (build-time codegen, not runtime input).
  • Delete Cartouche.Util grab-bag module. Helpers redistributed into five focused modules: Cartouche.Address.from_public_key/1 (renamed from Util.get_eth_address/1), Cartouche.Chain.parse_id/1 + chain registry (renamed from Util.parse_chain_id/1), Cartouche.Wei.to_wei/1, Cartouche.HTTP.normalize_finch_result/1, and Cartouche.RecoveryBit (promoted from the nested Cartouche.Util.RecoveryBit submodule). The five hex helpers decode_hex_input!/1, encode_bytes/2, pad/2, nibbles/1, and checksum_address/1 move to Cartouche.Hex. The seven @deprecated decode/encode aliases (decode_hex/1, decode_hex!/1, decode_sized_hex!/2, decode_word!/1, decode_address!/1, decode_hex_number!/1, encode_hex/2) and the keccak/1 defdelegate are removed — modern equivalents already exist in Cartouche.Hex / Cartouche.Hash. nil_map/2 is inlined as a module-local private helper in Cartouche.Trace and Cartouche.Trace.Action (its only consumers).

Fixed

  • Cartouche.RecoveryBit.normalize/2 and normalize_signature/2 specs: literal atom :no_return replaced with the no_return() type (ROADMAP Phase 1.1). Dialyzer silently accepts unknown atoms in unions, so this was semantically meaningless; now matches the documented raise behaviour.

Changed

  • Reset mix.exs version from the inherited signet pin 1.6.1 to 0.1.0-dev ahead of the first hex publish under the cartouche namespace (ROADMAP Phase 0, Task 1).
  • Swap the :abi path dep (path: "../abi", override: true) for the published hex package {:hieroglyph, "~> 1.0", override: true}. ZenHive's abi fork is now on hex.pm as hieroglyph 1.0.0; hex package name is hieroglyph but the Elixir module namespace remains ABI, so no callsite changes. Unblocks mix hex.publish for cartouche, which rejects path/git deps (ROADMAP Phase 0, Task 6).
  • Update mix.exs :package for the publish cut: maintainers: ["ZenHive"] (was ["Geoffrey Hayes"] — attribution preserved in LICENSE and in [0.0.1] below); drop test/support from :files (test helpers aren't part of the public surface), add CHANGELOG*; add CHANGELOG.md to docs[:extras] so hexdocs renders the release history; add a Changelog entry to package[:links].

Fixed

  • Pin bitstring size variables in binary matches across Cartouche.Solana.Transaction.read_instructions, Cartouche.Assembly.disassemble_opcode, and Cartouche.VM.{Memory,Operations} / Cartouche.VM.static_call for Elixir 1.20 compatibility. Behaviour-preserving; resolves all variable "X" is accessed inside size(...) ... must precede it with the pin operator warnings under 1.20-rc.4 (cleanup.md C1).
  • Pin bitstring size variable in Cartouche.VmTestHelpers.word/2 (test/support/vm_test_helpers.ex:11) — missed in the initial C1 sweep; same Elixir 1.20 compat fix.
  • Remove leading-underscore on expected in Cartouche.Solana.PDATest "wrong bump" test (test/solana/pda_test.exs:137) — variable is used inside the match?/2 guard at line 143, so the underscore was misleading and fired an Elixir 1.20 warning.
  • Cut dialyzer noise floor from 6,620 to 1,626 warnings by fixing typespecs in the upstream :abi library. Root cause was that ABI.encode/2, ABI.decode/2-3, ABI.decode_event/3-4, ABI.TypeEncoder.encode/2, and ABI.TypeDecoder.decode_raw/3 lacked @spec declarations, and ABI.FunctionSelector.t() declared returns: type (singular) while the runtime and ABI's own doctests use returns: [argument_type]. Dialyzer's inferred success typing for ABI.encode/2 collapsed the struct branch to function: nil, types: [] only, so every populated selector at every cartouche callsite was flagged as will never return, cascading through lib/cartouche/contract/i_console.ex. Fixed in the zenhive/abi fork and published to hex.pm as hieroglyph 1.0.0 (hex package name only; ABI module namespace preserved). cartouche consumes the patched library via {:hieroglyph, "~> 1.0", override: true} (see ### Changed above). ABI typespec fixes will be upstreamed via PR to poanetwork/ex_abi. (cleanup.md A1+A2; residual cascade tracked under follow-up A1b.)
  • Restore Cartouche.Signer @moduledoc (was @moduledoc false with module-level prose stuck in a @doc that collided with start_link/1's @doc). Eliminates the last compile warning under Elixir 1.20-rc.4 and aligns with cleanup.md's documentation policy (avoid @moduledoc false).
  • Replace @moduledoc false with descriptive @moduledoc on six submodules whose t() types are referenced from outer public specs: Cartouche.VM.Input, Cartouche.VM.Context, Cartouche.VM.ExecutionResult, Cartouche.Trace.Action, Cartouche.Receipt.Log, Cartouche.DebugTrace.StructLog. Eliminates all "documentation references type X but the module is hidden" warnings from mix docs; clean docs build for the publish cut (ROADMAP Task 36).
  • IAL/markdown collision in four Cartouche.Hex doctest blocks (decode_hex/1, from_hex/1, decode_hex_number/1, encode_hex_result/1): bumped doctest source indent from 4 to 6 spaces so the heredoc-stripped output reaches the 4-space code-block threshold instead of being parsed as prose lines starting with {.
  • Drop /arity suffix on private-function references in this CHANGELOG (Cartouche.Solana.Transaction.read_instructions, Cartouche.VM.static_call) so ex_doc no longer attempts to auto-link non-public functions and emit broken-link warnings.

Documentation

  • Correct DEV.md Sleuth regeneration command — the canonical ABI source is ./priv/Sleuth.json (vendored), not the previously documented ../sleuth/out/Sleuth.sol/Sleuth.json external path.

[0.0.1] — 2026-04-22

Initial placeholder release. Claims the cartouche hex namespace under ZenHive ownership.

Active development (fork of hayesgm/signet) lands in 0.1.x.

Attribution

Cartouche is an attributed fork of hayesgm/signet, originally authored by Geoffrey Hayes at Compound Labs, Inc. (2022). The upstream MIT license is preserved alongside the ZenHive copyright in LICENSE.