# Changelog

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

<!-- Phase anchors for ROADMAP.md cross-references — rmap renders `CHANGELOG.md#phase-N-...` links from collapsed (status="done") phase summaries; these anchors land the click at the top of the changelog so the link isn't dead. -->
<a id="phase-1-spec-corrections-immediate-onchain-wins"></a>
<a id="phase-2-cartouche-rpc-send-rpc-3-error-shape-spec"></a>
<a id="phase-3-cartouche-trace-cartouche-tracecall-deserialize-specs"></a>
<a id="phase-5-vm-erc20-call-none-cascade-investigation"></a>
<a id="phase-6-cartouche-vm-context-init-from-2-spec"></a>
<a id="phase-7-dependency-freshness"></a>
<a id="phase-8-cartouche-transaction-v2-encode-1-duplication"></a>
<a id="phase-9-new-transaction-types-raw-decode"></a>
<a id="phase-11-hieroglyph-1-0-0-1-4-0-adoption-advisory"></a>
<a id="phase-12-agent-economy-descripex-adoption"></a>

## [0.3.0] — 2026-06-12

### Changed

- Dependency constraint bumps: `descripex ~> 0.7.0` → `~> 0.9.1` and `hieroglyph ~> 1.4.0` → `~> 1.5`. hieroglyph 1.5.0 is the current hex line. descripex 0.8/0.9 fill JSON Schema from `@spec`/declared `type:` — additive for consumers — but the floor is pinned to **0.9.1, not 0.9.0**: 0.9.0's runtime enrichment raised a `CaseClauseError` (in its `json_spec` dep) on the `%{non_neg_integer() => <<_::256>>}` spec of `Solana.Transaction.sign_partial/2`, crashing `Cartouche.describe/0` and `__api__/1`; descripex 0.9.1 fixes it. No Cartouche code changes, only the floor moves. Minor bump (not 0.2.3) because the public dependency floor changed.
- Dependency updates within existing constraints (carried from the 0.2.3 refresh): direct dev/test tooling `credo` 1.7.18 → 1.7.19, `dialyzer_json` 0.2.0 → 0.2.1; transitive `mint` 1.8.0 → 1.9.0, `thousand_island` 1.4.3 → 1.5.0. `bandit` stays at 1.11.1 — 1.12.0 is outside the intentional `~> 1.11.0` dev-only pin (PLT-stability constraint). `tesla` held at 1.18.2 (not bumped to 1.20.0): 1.20.0's `Tesla.Middleware.Compression` now mandates a `:max_body_size` option that `google_api_cloud_kms`'s middleware stack does not pass, raising `fetch_max_body_size!` and breaking all 14 CloudKMS signer tests. Pinned in `mix.lock` until the GCP cluster passes the option upstream.

### Fixed

- Generator function-name dedup (`dedup_named_abi/5` in `lib/mix/cartouche.gen.ex`) now keys collision detection on `Macro.underscore/1` instead of `String.downcase/1`. The generated identifiers are built from `Macro.underscore(name)` (`function_names/1`), but the dedup keyed on `String.downcase(name)` — a divergent normalization. A contract exposing both `getValue` and `get_value` downcases them differently (`"getvalue"` vs `"get_value"`) yet underscores both to `"get_value"`, so neither the exact-dup skip nor the rename fired and the second function emitted a silently-shadowed `encode_get_value/1` clause (plus shadowed `decode_get_value_call`, `get_value_selector`, …) — `encode_get_value` always produced `getValue`'s calldata. `Macro.underscore` subsumes the prior downcase (it lowercases) and additionally folds camelCase/snake_case collisions. New behavioral regression test (`describe "underscore-collision dedup"`): generates `[getValue(uint256), get_value(uint256)]`, compiles the module, and asserts two distinct `encode_get_value*` functions emit distinct calldata — pre-fix they collapse to one. (ROADMAP Task 106 filed for the related unlinked-library/immutable-placeholder bytecode edge.)

### Tooling

- Restored dialyzer to the PR harness (`.github/workflows/harness.yml`), reverting the 2026-05-04 carve-out (ROADMAP Task 76). The carve-out attributed an `ubuntu-latest` OOM (run 25319850405) to the 621-module deps PLT *size* and deferred dialyzer to "a larger runner / nightly cron." That diagnosis was wrong: the OOM was `Cartouche.Assembly.compile/1`'s 7-arity `tuple_set` exploding dialyzer's success-typing fixpoint (the ~30 GB bomb fixed in 0.2.2 / Task 103). A clean cold `mix dialyzer` (PLT build + analysis) now peaks at **~1.0 GB / ~26s** — ~15× under the 16 GB budget — with zero warnings. The step runs in `MIX_ENV=dev` and caches `priv/plts/` (pinned outside `_build/` for exactly this). No larger runner, separate workflow, or extra `:plt_ignore_apps` trim needed. Closes ROADMAP Task 76.

## [0.2.2] — 2026-06-05

### Changed

- `Cartouche.Assembly.compile/1` — collapse the seven fixed-arity operand heads (`opcode in @one_operand` … `@seven_operands`) into a single `is_tuple/1` clause that reads each opcode's operand count from `@opcodes` and validates arity against it. Behavior-preserving: operand ordering (reverse-compile so args land on the stack in source order), arity validation, and raise-on-unknown/wrong-arity are all unchanged — confirmed by new `test/assembly_test.exs` cases for 1- and 2-operand opcodes plus a wrong-arity (`{:add, 1}`) raise. Also drops a dead `if false && x == 0` branch in the integer clause. Motivated by keeping Dialyzer's success-typing fixpoint from expanding the 7-shape tuple product under `compile/1` self-recursion — that `tuple_set` product was a ~30 GB downstream-dialyzer memory bomb on OTP 29. Measured downstream (onchain, `plt_add_deps: :apps_direct`, cold PLT build, peak RSS via `/usr/bin/time -l`): **27.6 GB → 1.02 GB** (~27×), full IConsole left untouched (it was never the cause — see Task 103).

## [0.2.1] — 2026-06-04

### Added

- Wire `mix descripex.manifest` + `Cartouche.Manifest` runtime wrapper + `## API discovery` README section (Phase 12 / ROADMAP Task 89 / INE-49 / PR #62, delegated to Cursor). `mix manifest` alias in `mix.exs` runs `descripex.manifest --pretty --output api_manifest.json --app cartouche` — descripex 0.6's task requires `--app cartouche` to scope discovery to Cartouche-namespaced modules. New `Cartouche.Manifest` module wraps `Descripex.Manifest.build(Cartouche.__descripex_modules__())` so HTTP endpoints / MCP servers / A2A agents can serve the live manifest from a running BEAM without an out-of-band JSON artifact (same shape as the static export). `api_manifest.json` gitignored — regenerated from source on demand, never checked in to avoid merge drift; intentionally not added to `package: files` so the hex package stays light. `README.md` `## API discovery` section documents the three-level `Cartouche.describe/0,1,2` progressive-disclosure surface plus the static-vs-runtime split (`mix manifest` build-time artifact vs `Cartouche.Manifest.build/0` runtime accessor). Path A scope amendment surgically resolved a self-flagged + Codex-GitHub-bot-flagged P2 blocker before merge: descripex's `api()` macro embeds option `default:` values into the JSON-encoded annotation metadata, so Jason rejected the existing `default: @sleuth_address` references in `lib/cartouche/sleuth.ex` (the module attribute is a raw 20-byte binary; not UTF-8 encodable). Surgical 3-site swap in the metadata-only positions — `default: @sleuth_address` → `default: "0xFd946Bf25C47A1Bff567B28bA78a961bf78FF9d2"` at lines 25 (`api(:query, ...)`), 59 (`api(:query_annotated, ...)`), and 193 (`api(:query_v2, ...)`). Module attribute (line 13) and the runtime `Keyword.pop(opts, :sleuth_address, @sleuth_address)` paths (lines 151, 214) intentionally stay on the raw 20-byte binary — annotation metadata needs Jason-encodable hex, runtime path needs already-decoded binary, and the two shapes describe the same address by intent. CodeRabbit's literal-duplication nitpick (consolidate the 3 hex defaults into a single `@sleuth_address_hex` module attribute) dropped per ceremony floor (cosmetic, ≤5 LOC, the duplication is intentional shape-divergence between annotation and runtime; consolidation would force the metadata path to recompute hex from binary on every recompile, no real correctness benefit). New `test/manifest_test.exs` covers the runtime accessor — asserts the manifest has the descripex top-level shape (`:version` binary, `:generated_at` binary, `:modules` non-empty list) and that `Manifest.build/0` modules match `Cartouche.__descripex_modules__/0` exactly via `MapSet.equal?` (so future module-registration drift fails the test). CI Harness (Elixir 1.18.4 / OTP 27.3) 54s green on amend SHA `cb8e93b8`; CodeRabbit re-reviewed clean; sobelow drift gate clean (sleuth.ex changes were 3 single-line replacements, no line shifts; sleuth fingerprints had already cleared post-Task 48). Codex GitHub bot's P2 (the Jason-encode blocker itself) was on prior SHA `f7e741b8`; CI green on amend is the load-bearing confirmation. Tier-1 bot ensemble: CodeRabbit ✅ (one nit dropped), Codex GH bot P2 (resolved by amend), Copilot did not surface. Phase 12 (descripex adoption) is now fully closed — Tasks 82-89 + 93-97 all shipped. Closes ROADMAP Task 89.
- Top-level `Cartouche.Transaction.encode/1` struct dispatcher mirroring `decode/1` (ROADMAP Task 93 / INE-46 / PR #56, delegated to Cursor). Each clause delegates to the matching versioned leaf encoder (`V1.encode/1`, `V2.encode/1`, `V3.encode/1`, `V4.encode/1`), all of which already emit the EIP-2718 envelope byte where applicable, so the dispatcher is a pure pattern-match-and-delegate. Resolves the round-2 PR #42 / INE-32 finding where `Cartouche.describe(:transaction, :encode)` advertised a function that didn't exist (Codex second-opinion). Synthetic `transaction_dispatch_detail/2` helper removed from `Cartouche.describe/2` — `:encode` now resolves to real metadata for the dispatcher rather than a synthesized guidance entry. Round-trip tests `decode(encode(tx)) == {:ok, tx}` cover V1/V2/V3/V4 through the dispatcher. Closes ROADMAP Task 93.
- Phase 12 descripex annotation pass closed via the four metadata-only follow-ups bundled in INE-45 / PR #57 (ROADMAP Tasks 94 + 95 + 96 + 97, delegated to Cursor). Top-level `Cartouche.Transaction.decode/1` `api(:decode, ..., returns: ...)` now enumerates all 7 dispatcher outcomes — `{:ok, V1.t() | V2.t() | V3.t() | V4.t()}` (the four `Vn.decode/1` happy paths via EIP-2718 envelope routing), `{:error, :empty_transaction}`, `{:error, :unknown_envelope_type}`, and the delegated `{:error, String.t()}` from `V1/V2/V3/V4.decode/1` for malformed bodies (Task 94, CodeRabbit Major + Codex). `Cartouche` itself now registered in `@descripex_modules` with `:cartouche` alias; the existing `api(:describe, ...)` block covers `describe/0,1,2` via descripex's `propagate_hints_to_all_arities`; `get_contract_address/1` annotated (required because self-registration brings it into the validation test's surface); `__descripex_modules__/0` kept `@doc false` per the `__foo__/N` reserved-for-metadata convention (Task 95, CodeRabbit Major; option authorized by issue body). V1's `value` description aligned with `@spec` and the `{2, :wei}` doctest example — drops off-spec `:eth` from the unit list since `to_wei/1` accepts `integer` of wei or `{amount, :wei | :gwei}` only (Task 96, CodeRabbit Minor). New misattachment-detection pass in `test/descripex_validation_test.exs` cross-checks `Code.fetch_docs/1` `meta[:hints]` against `Module.__api__/0` declarations — every function carrying hints must have a matching `__api__()` entry for its name AND `meta.hints` must equal one of those entries' hints (Task 97, Codex severity-5; option (c) from the issue body). Post-merge bookkeeping refined the new test pass to address Codex P2 + CodeRabbit nit on PR #57: `Map.new(&{name, hints})` collapse swapped for `Enum.group_by(& &1.name, & &1.hints)` list-membership so multi-decl pairs (e.g. V2's two `api(:new, ...)` blocks for arities 9/12, V2's two `api(:add_signature, ...)` blocks for arities 2/4) are tracked as a list rather than collapsed (Codex's proposed `{name, arity}` keying would have still collapsed cartouche's V2 pairs since `find_arity_and_defaults/2` records `max_arity` for every block — verified via Tidewave against the merged BEAMs); explicit `{:error, reason}` flunk branch on `Code.fetch_docs/1` mirroring the earlier test pass in the file. Phase 12's annotation sweep is now complete; Task 89 (manifest wiring + README) remains open. Metadata-only — no runtime code path changes. Closes ROADMAP Tasks 94 + 95 + 96 + 97.
- `Cartouche.Block.transactions` now decodes full-detail transaction objects when nodes return them via `:include_transaction_details: true` (ROADMAP Task 66 / INE-44 / PR #55, delegated to Cursor; bot-finding follow-ups landed locally as `13f5e50` on `development`). `Cartouche.Block.deserialize/1` dispatches per-element on `params["transactions"]`: hash strings preserve the wire `String.t()` shape (with `Hex.decode_word!/1` validation at the boundary so a malformed hash raises at the source rather than leaking downstream); full-detail JSON maps dispatch by `"type"` to `V1/V2/V3/V4.from_json/1` (legacy / EIP-1559 / EIP-4844 / EIP-7702). `"0x1"` (EIP-2930) raises a specific `EIP-2930 ... not yet supported` error distinct from the generic `unsupported envelope type` raised on truly-unknown bytes — operators can tell "known type, not yet ported" apart from "we have no idea what this is" without grepping. New `Cartouche.Transaction.JsonField` cross-module helper module documents the six shared decoders (`decode_destination/1`, `decode_signature_word/1`, `decode_y_parity/1`, `decode_access_list/1`, `decode_blob_versioned_hashes/1`, `decode_authorization_list/1`) with real `@doc` strings — the helpers are callable from V1/V2/V3/V4.from_json/1, so real docs are more useful than `@doc false` here. Defensive `nil → []` is applied symmetrically across V2 `accessList` / V3 `blobVersionedHashes` / V4 `authorizationList` — all three are wire-required but `from_json/1` is publicly callable and tolerates omission to keep the JSON path defensively symmetric (CodeRabbit's V4-only P2 finding was kept as documented design choice rather than breaking the symmetry). Tier-1 bot ensemble findings addressed locally on `development` post-merge: CodeRabbit P1 (hash-validation), Codex GitHub bot (type-1 envelope), Doctor 0%-docs CI failure on `JsonField`. Cursor's VM OOM'd on the PLT build per the no-cloud-dialyzer convention; local `mix dialyzer.json` post-merge confirmed zero new warnings. Discovered follow-up: ROADMAP Task 99 tracks proper `Cartouche.Transaction.V_2930` (EIP-2930, type 0x1) `from_json/1` support — both bot-finding pinning tests (`block_test.exs` "EIP-2930 (type 0x1) raises…" and the matching raw-decode error-tuple test) flip from `assert_raise` / `assert {:error, :unknown_envelope_type}` to positive shape assertions when that lands. Closes ROADMAP Task 66.

### Fixed

- `Cartouche.Typed.encode_value_map/3` now keeps the stricter `binary()` private `@spec` by forcing each encoded field branch through `IO.iodata_to_binary/1` before appending into the EIP-712 encoded-data binary (ROADMAP Task 98 / harness run `run-1780622112906-4a1b918a`). This closes the Phase 4 follow-up from Tasks 19+20: the earlier `bitstring()` spec matched Dialyzer's conservative success typing, but every actual branch is byte-aligned and `hash_struct/3` depends on binary concatenation. New regression assertions exercise primitive and custom-type paths through `hash_struct/3` and pin 32-byte binary hashes. `.sobelow-skips` was regenerated for accepted baseline fingerprint drift; the stray duplicate `.sobelow-skips.committed` file was removed in review. Closes ROADMAP Task 98.
- `Cartouche.Transaction.V3.decode/1` now enforces the EIP-4844 `VERSIONED_HASH_VERSION_KZG = 0x01` leading byte on every entry of `blob_versioned_hashes`, not just the 32-byte length (ROADMAP Task 90 / INE-50 / PR #61, delegated to Cursor; surfaced during INE-30 / PR #41 review by Copilot, deferred from Task 33 per the issue body's "pure decode primitive only" scope). Single-predicate tightening in `defp decode_blob_versioned_hashes/1` — the `Enum.all?/2` callback now requires `is_binary(hash) and byte_size(hash) == 32 and binary_part(hash, 0, 1) == <<0x01>>`. Error contract `{:error, "invalid v3 transaction"}` unchanged. Regression test in `test/cartouche/transaction/v3_test.exs` mirrors the existing `"rejects non-word blob versioned hashes"` shape with a 32-byte hash whose leading byte is `0x00`. `Cartouche.Transaction.V3` coverage held at 98.73% (≥ 95% critical-tier gate); existing fixtures already use `0x01`-prefixed hashes (`<<1, 0::248>>` in `representative_tx/0`, `0x01908125...` in the mainnet blob-tx fixture), so happy paths unchanged. Out of scope (Cursor honored): encoder side (`V3.encode/1` trusts struct fields by design), `Cartouche.Transaction.V4` blob versioned-hash audit, and the dispatcher in `Cartouche.Transaction.decode/1` (Task 94 territory). Tier-1 bot ensemble: CodeRabbit ✅ "No actionable comments" (CHILL profile, 5/5 pre-merge checks); Copilot and Codex GitHub bot did not surface — change is small enough that no escalation was warranted. Harness CI (Elixir 1.18.4 / OTP 27.3) green in 54s. Local `mix dialyzer.json --quiet` post-merge confirmed zero new warnings (Cursor skipped `mix dialyzer` per AGENTS.md — cartouche PLT OOM-crashes the cloud VM). Single round, no rework. Phase 9 (raw transaction decode) is now fully closed. Closes ROADMAP Task 90.
- Bump `reach` 1.8 → 2.2 and apply hygiene fixes flagged by 2.2's expanded smell surface across `lib/cartouche/**` (ROADMAP Task 59-lib / INE-47 / PR #59, delegated to Cursor; bot-finding follow-ups landed locally on `development` post-merge as `5668c0e`). Behavior-preserving cleanups in five modules — `lib/cartouche/hex.ex` checksum loop swaps `~c"0123…"` charlist + `Enum.at/2` (O(n) per nibble lookup) for static `{?0, ?1, ?2, …}` tuples + `elem/2` (O(1)); `lib/cartouche/sleuth.ex` swaps `Enum.count(args)` → `length(args)` in the rescue-message string and splits two `is_nil(name) or name == ""` guard heads (`fallback_name/2`, `name_keyword/1`) into pattern-match clauses (`nil`/`""`) — both reach 2.2 idiom-mismatch flags; `lib/cartouche/solana/pda.ex` `create_program_address/2` collapses two `Enum.reduce` binary concatenations into a single iodata list passed to `:crypto.hash(:sha256, [seeds, program_id, @pda_marker])` (avoids two intermediate `<<>>` allocations per PDA derivation, hot-path concern for vault/PDA seed search loops); `lib/cartouche/solana/transaction.ex` `serialize_message/1` + `serialize/1` rewrite the binary-concatenation reductions to `IO.iodata_to_binary/1` over a list — but **carefully preserve the original raise-on-malformed contract** that the prior `Enum.reduce(..., fn <<key::binary-32>>, acc -> acc <> key end)` enforced via FunctionClauseError, by adding explicit `Enum.each(account_keys, fn <<_::binary-32>> -> :ok end)` and `Enum.each(sigs, fn <<_::binary-64>> -> :ok end)` validation passes at the function entry. Without those validators, malformed account keys / signatures would silently flatten into the wire format and the compact-u16 length prefix would lie about how many keys are present, with downstream parsers consuming blockhash / instruction bytes as "remainder of the account-key region"; `lib/cartouche/vm.ex` two `Enum.count/1` → `length/1` swaps (`Context.show_stack/1`, `push_word/2`) and adds `:stack_overflow` to the `@type vm_error` union (CodeRabbit minor outside-diff; `push_word/2` already returned `{:error, :stack_overflow}` at line 370 but the type didn't list it). New 122-LOC test pass in `test/solana/transaction_test.exs` covers serialize-message + serialize golden round-trips and pins the raise-on-malformed contract for both passes (account-key length validation + signature length validation) so the boundary contract is regression-tested at the type-correctness level. Tier-1 bot ensemble: CodeRabbit one Major (touched-file `defp`s missing `@spec` per the project's `include_defp: true` Credo config) + one Minor outside-diff (`vm_error` union missing `:stack_overflow`); Copilot did not surface; Codex GitHub bot did not surface. Local post-merge bookkeeping resolved both bot findings + a CI format failure (Styler at merge-time rewrote PR #60's newly-added `alias Cartouche.Solana.Transaction.{Header, Message}` references in `test/solana/transaction_test.exs`'s overlap region; the CI merge commit's regenerated long-form refs failed `mix format --check-formatted`) — fix added the same two aliases to PR #59's alias block so Styler's auto-rewrite matches local + CI; three `@spec`s added to `arg_name/2`, `build_struct_argument_spec/2`, `unused_name_value_pair/1` in `lib/mix/cartouche.gen.ex` (CodeRabbit major); `:stack_overflow` added to `vm_error` (CodeRabbit minor outside-diff). Local `mix dialyzer.json --quiet` post-merge confirmed zero new warnings on touched files (Cursor's cloud VM OOM'd on the full-deps PLT build per the no-cloud-dialyzer convention; verification ran on `development`). `.sobelow-skips` regenerated post-merge via `mix sobelow --mark-skip-all` after the three `@spec` adds in `lib/mix/cartouche.gen.ex` shifted line numbers (4 prior fingerprints rotated; 6 new fingerprints registered for the post-shift positions) — admin-merge with `--admin` was load-bearing here since the sobelow-skips drift only resolves on `main` post-merge per the project's "agents should not touch .sobelow-skips" convention. Closes ROADMAP Task 59-lib (and effectively Task 59 — the `lib/mix/cartouche.gen.ex` sub-items in the original Task 59 scope were either already shipped under the Task 41/42/50 generator-hardening bundle or rolled into this PR via reach 2.2's expanded smell surface).
- Harden `Cartouche.Solana.Transaction.sign/2` and `add_signature/3` against caller-error silent failures (ROADMAP Tasks 91 + 92 / INE-48 / PR #60, delegated to Cursor; bundled because both pass through the same critical-tier ≥95% coverage gate, both touch the same module, and both have the same fix shape — precondition + raise). `sign/2` now validates `length(seeds) == message.header.num_required_signatures` at function entry and raises `ArgumentError` with both counts named on mismatch — previously, callers could supply a seed list of any length and produce a "full transaction" whose signatures-array length didn't match the message header, surfacing only as an opaque submission failure when the Solana runtime rejected the wire payload downstream. `add_signature/3` now guards `0 ≤ index < length(transaction.signatures)` and raises `ArgumentError` on out-of-bounds — `List.replace_at/3` silently returns the list unchanged on out-of-bounds indices (verified against Elixir 1.18's documented behavior), so the prior implementation reported success while leaving the signature slot unfilled, masking partially-signed transactions in sponsored-transaction flows. The function-head guard `index >= 0` was moved into the body so negative indices raise `ArgumentError` (matching the AC) instead of `FunctionClauseError`. Both functions adopt the same contract style (raise) — the module's existing `{:error, _}` contract is reserved for parse errors (`deserialize/1`, `deserialize_message/1`, etc.), so raising on caller error matches idiomatic Elixir (`Map.fetch!` / `Keyword.fetch!` / `Kernel.elem/2`) without conflating the two error shapes. `@doc` extended on both functions documenting the new error path; `@spec` unchanged on both (raise contract, no return-type widening needed). Regression coverage in `test/solana/transaction_test.exs` covers undersupplied (1 vs 2), oversupplied (2 vs 1), and exact-match happy path for `sign/2`; off-by-one (`index = length`), negative (-1), far-OOB (99), and in-range regression for `add_signature/3`. Coverage on `Cartouche.Solana.Transaction` stayed at 100% (≥95% critical-tier gate). Tier-1 bot ensemble incomplete on this PR — CodeRabbit posted "No actionable comments were generated" (CHILL profile, Pro Plus); Copilot and Codex GitHub bot did not surface reviews, flagged as repo-config follow-up rather than Cursor failure since the PR was opened non-draft per AC. CI Harness (Elixir 1.18.4 / OTP 27.3) green; sobelow drift gate clean (PR didn't touch any `.sobelow-skips`-fingerprinted file). Local `mix dialyzer.json --quiet` post-merge confirmed zero new warnings on `lib/cartouche/solana/transaction.ex`. Closes ROADMAP Tasks 91 + 92.
- Resolve all 16 outstanding `mix dialyzer.json` warnings on `lib/mix/cartouche.gen.ex`. Single root cause: `build_selector_fn/1`'s `@spec` (line 905) declared a closed-map shape `%{names: map(), selector: ABI.FunctionSelector.t(), sig: map()}`, but its only caller (`build_function_quotes/1` at line 464) passes the full 9-key `ctx` built in `encode_function_call/5`. Dialyzer flagged the closed map with `invalid_contract`, then cascaded — `build_selector_fn` "will not succeed" → `build_function_quotes/1` `no_return` → 7 sibling `build_*_fn/1` helpers (`build_event_selector_fn`, `build_decode_event_fn`, `build_decode_call_fn`, `build_decode_error_fn`, `build_generic_decode_call_fn`, `build_generic_error_fn`, `build_generic_event_fn`) flagged `unused_fun` because they were unreachable from a no-return parent → `select_emitted_fns/3` similarly unreachable → 3 `pattern_match` warnings on `merge_encode_call_result/2` clauses 221/224/227 because dialyzer believed `encode_function_call/5` always crashed → `abi_decode_return_spec([])` flagged unreachable for the same chain-of-narrowing reason. Fix: widen all 8 `build_*_fn/1` `@spec`s to open-map syntax (`:names => map(), …, optional(atom()) => any()`), preserving the required-key documentation while admitting the actual `ctx` shape. The eight `@spec` lines are functionally identical to the prior closed form except for the trailing `optional(atom()) => any()` — no runtime behavior change. The 12-warning cascade collapses to zero with this single fix; the standalone `pattern_match_cov` on `normalize_return_types/1` line 1068 (defensive bare-`type` clause that dialyzer narrows to dead because the upstream `ABI.FunctionSelector` parser never currently emits a bare type, even though `ABI.FunctionSelector.t().returns` at `deps/hieroglyph/lib/abi/function_selector.ex:51` is officially `type() | [argument_type()] | nil`) suppressed via `@dialyzer {:no_match, normalize_return_types: 1}` with a comment pinning the rationale — the clause stays for defense-in-depth against the wider public type, the suppression silences the narrowing without deleting code that the contract supports. `.sobelow-skips` regenerated via `mix sobelow --mark-skip-all` to refresh fingerprints after line shifts. Local verification: `mix dialyzer.json --quiet` 0 warnings (was 16, all on `lib/mix/cartouche.gen.ex`), `mix compile --warnings-as-errors` clean, `mix credo --strict` 0 issues on touched file (6 project-wide TagTODO entries unchanged — tracked-debt convention per `feedback_todo_credos_visible.md`), `mix test.json --quiet` 1027/1027 offline pass (29 `:integration` excluded; the generator has no direct unit tests but its consumers exercise emitted output), `mix sobelow` clean against refreshed `.sobelow-skips`. Touched-file scope only — `lib/mix/cartouche.gen.ex` and `.sobelow-skips`. Per CLAUDE.md "Never delegate dialyzer-scoped tasks to cloud agents", this stayed local from the start.
- Harden `Cartouche.Sleuth` atom-table risks (ROADMAP Task 48 / INE-43 / PR #53, delegated to Cursor). Two-phase delivery — Phase A (`b039c5a`) raised `Cartouche.Sleuth` to ≥95% coverage per `critical-rules.md` "RAISE COVERAGE BEFORE MUTATING" (Sleuth is critical-tier as the public ABI dispatcher); Phase B (`954e8ce`) swapped the remaining runtime atom mints to `String.to_existing_atom/1`. `query_by/3`'s `encode_<fun>` and `<fun>_selector` derivations now route through `existing_function_atom/2`, raising a `RuntimeError` matching the existing `try_apply/3` shape on cold function names ("Sleuth module does not define required..."). `try_decode/4` gained a `named_returns` boolean parameter and an `ArgumentError` rescue that surfaces the INE-17-shape `{:error, "error decoding: ..."}` envelope (preserves the convention established by the prior `decode_structs: true` audit rather than minting a new tuple variant); a new `preintern_named_return_atoms/1` helper walks only top-level returns (narrower than the existing `preintern_decode_struct_atoms/1` which recurses into nested ABI tuples). `preintern_name_atom/1` uses an `existing_atom/1` wrapper that returns `{:ok, atom} | :error` and raises `ArgumentError` on cold names; `name_keyword/1`'s rescue is dead-code defense-in-depth covered by the upstream preintern step. Merge-resolution commit (`3c8ee2a`) reconciled with `development` after PR #54 / INE-42 landed. `.sobelow-skips` regenerated — all three `lib/cartouche/sleuth.ex` fingerprints (`13012D4`, `536511`, `4A9C581`) dropped out, leaving only generator entries for `lib/mix/cartouche.gen.ex` (Task 41/42/50/59-gen territory) plus `config/prod.exs`. Local `mix dialyzer.json --quiet` post-merge confirmed zero warnings on `lib/cartouche/sleuth.ex` (Cursor's cloud VM OOM'd on the full-deps PLT build per the no-cloud-dialyzer convention; verification ran on `development`); all 16 remaining warnings sit in `lib/mix/cartouche.gen.ex`. Closes ROADMAP Task 48 / Sleuth hardening bundle.
- Phase 5 `none()` cascade closed (ROADMAP Tasks 21+22 / INE-42 / PR #54). `Cartouche.Erc20.exec_trx/3` `@spec` narrowed from `term()` to `{:ok, binary()} | {:error, term()}`, mirroring `Cartouche.RPC.execute_trx/3`'s contract — independently valuable since `exec_trx/3` is the public Erc20 transaction-submission surface and the prior loose return type forced consumers to narrow downstream. Tasks 21+22 themselves were effectively resolved by INE-21 / Task 46's prior coverage push (`Cartouche.VM.Context`, `Cartouche.Erc20.Call`, `Cartouche.VM.InvalidVm` exercised the previously-untyped paths well enough that dialyzer no longer narrows the four public heads' success typing to `none()`); PR #54 was a Cursor cloud-agent delegation that surfaced this finding by attempting `@dialyzer {:no_contracts, …}` suppressions on `Cartouche.VM.exec/3`, `exec_call/3`, `Cartouche.Erc20.exec_trx/3`, `transfer/4` plus cascade-root comment blocks documenting the suppressions. Local Tier-2 commit-review verified all four annotations were dead code (cascade no longer fires on parent commit; verified by removing the annotations and re-running `mix dialyzer.json --quiet` against the host's PLT — 0 invalid_contract warnings on the four heads in three configurations: PR parent, PR head as-is, PR head with annotations stripped). PR #54 was merged for the spec narrowing; the four dead `@dialyzer {:no_contracts, …}` annotations + their cascade-root comment blocks were removed in this post-merge bookkeeping commit on `development` (25 lines deleted across `lib/cartouche/vm.ex` + `lib/cartouche/erc_20.ex`). Closes ROADMAP Phase 5 / Tasks 21+22.
- Backfill `@spec` on every `defp` across `lib/cartouche/**/*.ex` and `test/support/**/*.ex`, then enable `{Credo.Check.Readability.Specs, [include_defp: true]}` in `.credo.exs` (Task 75 / INE-41 / PR #52, delegated to Cursor). Closes the cross-codebase mandate from `~/.claude/includes/development-philosophy.md` "Marking Internal API Surface" — every function (`def` AND `defp`) now carries an `@spec`. `.credo.exs` `:files` scope on the new check is `lib/cartouche/` excluding the auto-generated `lib/cartouche/contract/` (where Task 50's regen pass already emits `@spec ... :: term()`). Placeholder `term()` shapes used on hot-path data plumbing where domain types are unclear, with a `TODO:` marker for follow-up tightening; idiomatic shapes (MFA `[term()]`, fn callback `(term() -> term())`, `{:error, term()}` reasons) used everywhere they fit. **Reviewed and merged locally**, not via the cloud-agent default flow — Cursor/Codex VMs lack the memory budget to run dialyzer against cartouche's full-deps PLT, so the harness CI's dialyzer carve-out (`:plt_ignore_apps` for the GCP cluster + dialyzer dropped from PR CI per CHANGELOG `[0.2.0] ### Tooling`) means cloud agents can't catch dialyzer regressions in PRs. Local review caught 2 such regressions Cursor introduced — the new `client/1` specs on both `Cartouche.Signer.CloudKMS` and `Cartouche.Solana.Signer.CloudKMS` referenced `Tesla.Env.client/0`, but Tesla is in `:plt_ignore_apps`, so dialyzer reports `unknown_type`; replaced with `term()` plus a TODO documenting the PLT trim constraint. CodeRabbit's three findings landed in revision before merge: `Cartouche.Recover.decode_signature/1` spec realigned `Curvy.Signature.t() | {:error, term()}` → `Curvy.Signature.t() | :invalid_hex` (matches `Hex.decode_hex/1` bare-atom error propagation through `with`); `test/support/solana_client.ex` `token_account_fixture/4` `amount` param `non_neg_integer()` → `String.t()` (callers pass `"1500000000"`-shaped strings; impl calls `String.to_integer(amount)`); `Cartouche.Solana.Transaction.CompiledInstruction` introduced an `account_index :: 0..255` type and applied it to both `program_id_index` and `accounts` list elements (matches 1-byte serialization via `<<ix.program_id_index>>` and `:binary.list_to_bin/1`). 16 pre-existing dialyzer warnings on `lib/mix/cartouche.gen.ex` documented as out-of-scope (development-inherited from earlier cloud-agent PRs that couldn't run dialyzer to catch them at submit time). New project-`CLAUDE.md` rule pins the no-cloud-dialyzer constraint going forward — dialyzer-narrowing tasks stay local until Task 76 (restore dialyzer to a separate workflow on a larger runner) lands. Local verification: `mix format --check-formatted` clean, `mix credo --strict` 7-issue baseline (TagTODO only), `mix test.json --quiet --exclude integration` 1013/1013 offline pass (29 `:integration` excluded), `mix doctor` 100%/77 modules, `mix sobelow` clean against `.sobelow-skips`, `mix dialyzer.json` zero PR-introduced warnings. Closes ROADMAP Task 75.
- `Cartouche.Transaction.V2.encode/1` clauses now share unsigned RLP list assembly via a private `unsigned_rlp_list/1` helper; the unsigned and signed paths previously held 10 lines of identical struct destructuring (Type I clone surfaced by `mix ex_dna`). `t()` widens `signature_y_parity` / `signature_r` / `signature_s` to allow `nil` so the unsigned clause can take a single struct shape through the helper. New unsigned doctest pins byte-exact equivalence with bare-address access list entries (Phase 8 / ROADMAP Tasks 29+30 / INE-40 / PR #49, delegated to Cursor). CodeRabbit follow-up landed in the merge: `normalize_access_list/1` widened to accept bare-address entries (`<<_::160>>`) alongside `{address, storage}` tuples — the new bare-address doctest exposed a latent crash (`FunctionClauseError`) on the signed path that pre-dated the refactor and would have surfaced any time a caller passed a bare-address list to `add_signature/2`-style flows. Focused ExUnit assertions added in a new `V2.encode/1 access_list shapes` describe block in `test/transaction_test.exs` (unsigned bare, signed bare, mixed tuple+bare) so the contract is pinned independently of doctest prose. Refactor-tier (D:3) — no runtime behavior change for previously-supported shapes; the access-list widening is a genuine bug fix (`normalize_access_list/1` previously crashed on bare-address entries in the signed path). Local verification: 1013 tests pass (29 integration excluded), `mix dialyzer.json` clean on `lib/cartouche/transaction.ex`, `mix doctor --raise` 100% coverage, `mix sobelow --config` clean with no `.sobelow-skips` drift, `mix credo --strict` 0 issues. The cartouche.gen.ex dialyzer debt that surfaced under the project-wide pre-commit gate (16 pre-existing warnings introduced by PRs #50 / #51 when CI's dialyzer carve-out couldn't catch them) is unrelated to this PR and tracked separately. Closes ROADMAP Tasks 29+30.
- `Cartouche.Typed.encode_value_map/3` `@spec` rewritten from `binary()` to `bitstring()` to match dialyzer's success typing for the `for {field, type} <- fields, into: <<>>` comprehension (Task 19+20 / Phase 4 / INE-39 / PR #50, delegated to Cursor). `find_type/2` left untouched after verification — its committed spec was already `{String.t(), Type.t()}` matching the impl, so the Linear issue body's claim of `Typed.Type.t()` was stale; the pinning ExUnit assertions Task 45 added (INE-21) confirm the tuple return shape across the no-match raise, single-match, and multi-match raise branches. Both functions stay `defp`; no `@doc false` discussion needed since they're already private. Spec-only — no runtime code path changes. Dialyzer drops the `typed.ex:578 invalid_contract` warning. CI's full harness ran dialyzer successfully on the merged PR (Cursor's narrow Dialyzer run on `Cartouche.Typed` + related BEAMs was clean; the cloud VM OOM-killed the full project run, but local CI gate passed). Copilot's low-confidence push-back that the spec should remain `binary()` to preserve the byte-alignment invariant `hash_struct/3`'s `<>` operator requires (`type_hash <> encode_data` would raise at runtime on a non-byte-aligned bitstring) was reviewed and accepted as a defensible internal-`defp` choice for now — every actual branch in `Type.encode_data_value/2` returns 32-byte aligned binary, so the impl IS byte-aligned in practice. The stricter durable fix (tighten the impl so dialyzer can prove `binary()`, restore the original spec) filed as Task 98 follow-up. Closes ROADMAP Tasks 19+20 / Phase 4.
- `Mix.Tasks.Cartouche.Gen` now emits `@doc` and `@spec` on every public `def` it generates (Task 50 / INE-37 / PR #51, delegated to Cursor). The generator attaches an ABI-derived doc string and a spec to each `encode_*`, `decode_*`, `*_selector`, `call_*`, `estimate_gas_*`, `call_log_*`, `exec_vm_*`, fallback/receive variant, and pre-intern helper. Doc strings derive from `FunctionSelector`-formatted signatures (literal `bytes` for synthesized fallback/receive calldata so the rendered prose isn't a misleading FunctionSelector dump). Specs derive via the existing ABI-type → Elixir-type mapping, with two contract-shape fixes the annotation pass surfaced: `decode_*_call/1` is typed `binary() :: <decoded inputs>` (calldata in, decoded inputs out — not output types as an earlier draft had it), and `exec_vm_*` returns track unwrapped runtime behaviour (`m when is_map(m) -> {:ok, m}; [decoded] -> {:ok, decoded}; els -> {:ok, els}` — the multi-clause unwrap that exists in the generator template, now reflected in the spec instead of being papered over with a flat `t()`). Tuple-return ABI types render as Elixir tuple AST (`{non_neg_integer(), boolean(), <<_::160>>}`) rather than a list. `.doctor.exs` `ignore_paths: [~r"^lib/cartouche/contract/"]` removed; `mix doctor` clean across the regenerated `Cartouche.Contract.IConsole` and `Cartouche.Contract.Sleuth`. New generator regression tests in `test/mix/cartouche_gen_test.exs` walk every public `def` the generator emits and bind `@doc NAME` → `@spec NAME` → `def NAME` via a same-name regex (`annotation_stanza/2`), so future drift fails per-function rather than passing on a loose pattern match. `.sobelow-skips` regenerated for line shifts in `lib/mix/cartouche.gen.ex`. Three bot-ensemble revision rounds resolved before merge: Codex GitHub bot's P1 (tuple typespec AST) and P2 (`decode_*_call/1` input types), Copilot's three line-level findings (fallback/receive doc using `FunctionSelector` for synthesized signatures, `exec_vm_*` spec inconsistency vs unwrapped return, regex weakness in test 218), and CodeRabbit's two findings (same regex weakness + `@spec` on private `build_preintern_*` builders); one CodeRabbit `.sobelow-skips` drift claim was a false positive (CI harness drift gate passed at the merged commit). Closes ROADMAP Task 50.
- Annotate Ethereum utilities + primitive bundle with descripex `api()` metadata (Phase 12 / ROADMAP Task 88 / INE-35 / PR #47, delegated to Cursor). `use Descripex` registered with namespaces under `/ethereum/` across the high-traffic utilities — `hex`, `erc20`, `sleuth` — and the small primitive co-domain — `hash`, `address`, `wei`, `chain`, `recovery_bit` — plus a sibling `/base58` namespace for `Cartouche.Base58` (shared between Ethereum-adjacent and Solana code paths, so neither `/ethereum/` nor `/solana/` claims it). `api()` blocks placed above each existing `@doc` so prose survives in slot 4 and hints land in slot 5. The 11 previously-undocced `Cartouche.Hex` defs and the 1 previously-undocced `Cartouche.Sleuth` def each get minimal `@doc` prose so doctor's documentation gate passes (closing the gap as a side effect of the annotation pass). `Cartouche.Hex` encode/decode pairs explicitly document the inverse relationship in `returns:` and pin input shape (`0x`-prefixed hex string vs raw binary) on every function — the highest-traffic agent-misuse vector for the module. `Cartouche.Wei` unit conversions annotate input/output unit explicitly (wei ↔ gwei ↔ ether) on every helper. The 9 spec modules expanded to 11 during review when Codex GitHub bot's P2 push-back on `Cartouche.Erc20.CallData` and `Cartouche.Erc20.Call` (both received `use Descripex` annotations during implementation but neither was registered in `@descripex_modules`, so `Cartouche.describe()` would never have surfaced them) was resolved by registering both submodules with `:erc20_call_data` / `:erc20_call` aliases following the existing `:solana_*` / `:transaction_v*` pattern — extends the spec slightly (9 → 11 modules) but keeps the existing annotation work intact rather than stripping `use Descripex` from the submodules. Three revision rounds resolved before merge: round 1 addressed three metadata correctness items from the bot ensemble — `Address.from_public_key/1` description corrected from "DER-encoded" to "uncompressed secp256k1 public key in SEC1 form" (the function pattern-matches `<<4, public_key_raw::binary>>` per SEC1, not ASN.1 DER; flagged by Copilot + CodeRabbit Major), the misplaced `api(:decode_hex_number, ...)` block above `decode_hex_number!/1` renamed to `api(:decode_hex_number!, ...)` with integer/raise semantics (flagged by Codex P2 + Copilot duplication warning), and `Cartouche.Erc20`'s `exec_trx` / `call_trx` `:errors` metadata reworded to say "defaults when absent" matching the actual `Keyword.put_new/3` semantics rather than "merges into caller options" (flagged by CodeRabbit Minor; defensible interpretation choice — realigned wording rather than mutating runtime semantics, since `:errors` defaults are an explicit metadata concern, not a runtime composition concern); round 2 rebased the PR onto `origin/development` after PR #46 (INE-36) merged, resolving conflicts in `lib/cartouche.ex` (preserved PR #46's custom Descripex alias/discovery layer alongside the new utility modules) and regenerating `.sobelow-skips` against the rebased source; round 3 resolved two remaining items — `address.ex:23`'s `@doc` body still drifted from the corrected `api()` block (DER vs SEC1) after round 1's metadata fix landed but the prose line directly below it stayed unchanged (flagged by user push-back + CodeRabbit follow-up; agents reading `Cartouche.describe(:address, :from_public_key)` would have seen SEC1 in hints but DER in the prose), and the discoverability scope question on the Erc20 submodules described above. `.sobelow-skips` regenerated for line shifts triggered by `Cartouche.Sleuth` metadata insertion (Sleuth is on the project's accepted-pending-fix `String.to_atom` list pending Task 48); harness sobelow-drift gate green on the merged PR. Metadata-only — no runtime code path changes. Tasks 89 (manifest wiring + README) and the five PR-flagged Phase 12 follow-ups (Tasks 93-97) remain.
- `Mix.Tasks.Cartouche.Gen` now derives separate `has_bytecode` (init) and `has_deployed_bytecode` flags from the artifact's bytecode declarations and routes generator emission accordingly (Task 41 / INE-36 / PR #46, delegated to Cursor). Constructor `abort?/3` continues to gate on init `has_bytecode`; the `:pure` clause of `select_emitted_fns/3` now matches a literal `true` on the deployed flag, so `exec_vm_*` only emits when deployed bytecode is actually present in the input. Asymmetric Solidity artifacts (init present + deployed absent, or vice versa) previously misbehaved — the first emitted `exec_vm_*` referencing an undefined `deployed_bytecode/0` and produced a `CompileError` at consumer load; the second skipped `exec_vm_*` even though the runtime would have worked. Pre-existing in upstream signet, preserved by Task 40's refactor, low trigger probability because Hardhat/Foundry artifacts always pair both bytecodes — caught now under deliberate asymmetric coverage. New `describe "bytecode shape coverage"` block in `test/mix/cartouche_gen_test.exs` covers both shapes with both string-match assertions (InitOnly: `refute "deployed_bytecode()"` catches the original `CompileError` class) and runtime `function_exported?/3` checks against the compiled module. `lib/cartouche/contract/{i_console,sleuth}.ex` regenerated zero-diff because both Hardhat artifacts ship paired bytecodes. `.sobelow-skips` regenerated for the line shifts in `lib/mix/cartouche.gen.ex` (4 of 6 fingerprints rotated; CI sobelow drift gate green on the merged PR). Closes ROADMAP Task 41 / INE-36.
- `Cartouche.VM.Context.init_from/2` `@spec` narrowed from the abstract `t()` return to a concrete `%__MODULE__{...}` struct literal whose field types match the function's actual initial-state construction — constants pinned where the function emits literals (`pc: 0`, `halted: false`, `stack: []`, `memory: <<>>`, `tstorage: %{}`, `reverted: false`, `return_data: <<>>`) and existing type aliases used for the varying fields (`code`, `code_encoded`, `op_map`, `ffis`). `Cartouche.VM.Context.@type t/0` deliberately stays broad — it describes mutated runtime contexts after `pc` advances / stack pushes / etc., consumed by callers operating on post-init state. Spec-only; runtime behavior unchanged. Dialyzer drops `lib/cartouche/vm.ex:104 invalid_contract`. Closes ROADMAP Task 23 / INE-29 and Phase 6.
- `Cartouche.Solana.RPC` now has permanent regression coverage for the previously-untested option/filter/encoding paths surfaced during INE-25 / PR #37 review. New `test/solana/rpc_test.exs` assertions ground the `:encoding` opt on `get_account_info/2`, `get_multiple_accounts/2`, and `get_transaction/2` against recorded JSON-RPC params (covering `:base58`, `:base64`, `:"base64+zstd"`, `:json_parsed`, plus binary-string passthrough); the `get_token_accounts_by_owner/3` `ArgumentError` raise when neither `:mint` nor `:program_id` filter is provided; and the `send_transaction/2` `:encoding` / `:skip_preflight` / `:preflight_commitment` / `:max_retries` opts. A `RecordingClient` test double captures outgoing JSON-RPC method + params via `send/2` to the test process so each path fails if the wire shape regresses. `Cartouche.Solana.RPC` coverage clears the standard ≥80% gate. Test-only — no `lib/cartouche/solana/rpc.ex` mutation. Closes ROADMAP Task 77 / INE-27.

### Added

- Raw transaction decode across V1/V2/V3/V4 (Phase 9 / ROADMAP Task 33 / INE-30 / PR #41). New `Cartouche.Transaction.decode/1` dispatcher routes by EIP-2718 envelope byte: `0x02` → `V2.decode/1` (EIP-1559), `0x03` → `V3.decode/1` (EIP-4844 blob), `0x04` → `V4.decode/1` (EIP-7702 set-code). Legacy V1 falls through to `V1.decode/1` when the leading byte is `>= 0x80` (RLP list prefix); empty input returns `{:error, :empty_transaction}`; reserved type bytes (`0x01`, plus the `< 0x80` envelope-byte range) return `{:error, :unknown_envelope_type}`. Each typed envelope's `decode/1` is a strict round-trip with the corresponding `encode/1` — RLP shape, address byte_size, signature `r`/`s` bounds, access lists, blob versioned hashes, authorization lists are all validated at parse time. Out of scope per the original issue body: EIP-4844 versioned-hash `0x01` version-byte enforcement (`VERSIONED_HASH_VERSION_KZG`) — Copilot flagged this on PR #41; filed as Task 90 (`[D:1/B:2/U:2 → Eff:2.0]` 🚀) since the encoder produces correct hashes and the strictness only matters when decoding adversarial mainnet payloads. Coverage for the new `decode/1` paths sits at the critical-tier (≥95%); the dispatcher and each `Vn.decode/1` are exercised against round-trips from their `encode/1` plus malformed-envelope rejection cases.
- Mainnet archive integration anchors for the four trace methods (`trace_transaction`, `trace_call`, `trace_callMany`, `debug_traceCall`) deferred from Task 61's v1 sweep. New `describe "trace methods"` block in `test/rpc_integration_test.exs` exercises every clause of `Cartouche.Trace.Action.deserialize/1`: the `"call"` clause via the existing type-0/type-2 receipt anchors, the `"init"` clause via a fresh CREATE anchor (block 18,000,000, contract-deployment tx — pins `type == "create"`, 20-byte `result_address`, non-empty `result_code`), and the `"refundAddress"` clause via a fresh pre-Cancun SELFDESTRUCT anchor (block 11,500,000, CHI gas-token free-up — pins suicide-action `refund_address` shape). A type-4 EIP-7702 anchor (block 23,600,000, post-Pectra delegation tx) confirms the wire-format `type` / `callType` strings remain CALL-family (no new opcode mnemonics) — closing the loop on Task 68's premise correction. `trace_call` and `debug_traceCall` reuse the WETH9 `totalSupply()` invariant at block 18,000,000 to pin output bytes against `@weth9_total_supply`; `trace_callMany` adds a second WETH9 read (`balanceOf(address(0))`) to exercise multi-call list shape. Assertions pin only fields that are deterministic across geth/reth/erigon (wrapper struct, `transaction_hash` round-trip, top-level type, deterministic outputs); internal `gas_used` / `subtraces` / `struct_logs` are shape-only since node implementations differ on those. Closes ROADMAP Task 62.
- Bootstrap descripex adoption (Phase 12 / ROADMAP Task 82). `:descripex` is now a direct dep instead of transitive-via-`:hieroglyph`, so consumer `mix.exs` files don't need to add it to use the discovery API. The top-level `Cartouche` module exposes `describe/0,1,2` and `__descripex_modules__/0` via `use Descripex.Discoverable` with an initially empty registered-module list. A new validation test in `test/descripex_validation_test.exs` walks the registered list and flunks-with-the-offending-function-name when any non-`@doc false` public function is missing `meta[:hints]` — trivially passes today, grows teeth as the Phase 12 annotation passes (Tasks 83-88) register modules. Tasks 83-89 are unblocked.
- Annotate `Cartouche.RPC` + response/trace decoders bundle with descripex `api()` metadata (Phase 12 / ROADMAP Task 84 / INE-31 / PR #44). `use Descripex` registered across all 7 modules with namespaces under `/ethereum/`: `rpc`, `block` (+ `block/withdrawal`), `receipt` (+ `receipt/log`), `fee_history`, `debug_trace` (+ `debug_trace/struct_log`), `trace` (+ `trace/action`), `trace_call`. All 11 module entries (7 primary + 4 nested struct modules) added to `Cartouche.@descripex_modules`, so `Cartouche.describe(:rpc)` / `.describe(:block)` / `.describe(:receipt)` / `.describe(:fee_history)` / `.describe(:debug_trace)` / `.describe(:trace)` / `.describe(:trace_call)` return Level-2 listings, and `.describe(:rpc, :get_block_by_number)` (etc.) returns Level-3 detail with non-empty `params`, `returns`, `description`. Each `api()` block sits *above* the existing `@doc` so prose remains in slot 4 while hints land in slot 5. Block-tag args document the post-Task 60 union shape (`"latest"` / `"pending"` / integer); `:exchange_data` params (e.g. `nonce`, `gas`) carry `source:` pointers to the upstream RPC method that produces them. Metadata-only — no runtime code path changes — except for one push-back fix the metadata exposed: `Cartouche.RPC.fee_history/1` now calls `normalize_block_param/1` on `:newest_block` before forwarding to `eth_feeHistory` (it previously sent the raw value unchanged, which would have produced `-32602 Invalid params` from real Ethereum nodes whenever an agent followed the metadata's documented integer support); regression coverage added in `test/rpc_test.exs` asserting `eth_feeHistory` sends `"0x37"` for `newest_block: 55`. Tasks 85-88 remain.
- Annotate `Cartouche.Transaction` + nested V1 + V2 modules with descripex `api()` metadata (Phase 12 / ROADMAP Task 85 / INE-32 / PR #42). `use Descripex` registered with three namespaces — `/ethereum/transaction` (top-level), `/ethereum/transaction/v1` (legacy V1), `/ethereum/transaction/v2` (EIP-1559 V2). 21 public defs annotated across the three modules; all three module entries added to `Cartouche.@descripex_modules`, so `Cartouche.describe(:transaction)` / `Cartouche.describe(:transaction_v1)` / `Cartouche.describe(:transaction_v2)` return Level-2 listings, and `.describe(:transaction_v2, :new)` (etc.) returns Level-3 detail with non-empty `params` / `returns` / `description`. V2's `new/9` and `new/12` arities each get their own `api()` block (different param surfaces — without/with explicit signature triplet); both packed `add_signature/2` and expanded `add_signature/4` forms get separate annotations. Top-level `Cartouche.Transaction` advertises `decode/1` (the EIP-2718 envelope dispatcher from Task 33) plus a synthetic `transaction_dispatch_detail/2` entry guiding consumers toward `V1.encode/1` / `V2.encode/1` for concrete encoding. Each `api()` block sits *above* the existing `@doc` so prose remains in slot 4 while hints land in slot 5. Three review rounds resolved before merge: round 1 restored two `TODO:` markers Cursor stripped (`block.ex:294`, `solana/transaction.ex:399-400`) and split `V2.new/12` annotation from `V2.new/9`; round 2 landed the rebase + sig-param removal from V2.new/9; round 3 surfaced five Phase 12 follow-ups (Tasks 93-97) per the established PR-flagged-follow-up precedent — phantom `Cartouche.Transaction.encode/1` in the synthetic dispatcher entry (Codex second-opinion), top-level `decode/1` return-shape advertised as V1-only when the dispatcher actually returns 7 outcomes (CodeRabbit Major + Codex), unannotated `Cartouche.describe/0,1,2` + `__descripex_modules__/0` discovery helpers (CodeRabbit Major), V1 `value` annotation drift (CodeRabbit Minor), validation-test gap that can't catch wrong physical hint attachment (Codex severity 5). Metadata-only — no runtime code path changes. Tasks 86-88 remain.
- Annotate Solana stack with descripex `api()` metadata (Phase 12 / ROADMAP Task 87 / INE-34 / PR #45). `use Descripex` registered with namespaces under `/solana/` across all 9 modules — `signer`, `transaction`, `keys`, `pda`, `ata`, `programs`, `system_program`, `token_program`, `token` — and `api()` blocks placed above each existing `@doc` so prose survives in slot 4 and hints land in slot 5; all 9 module entries added to `Cartouche.@descripex_modules`. An explicit `@descripex_aliases` map registers `:solana_signer` / `:solana_transaction` / `:solana_keys` / `:solana_pda` / `:solana_ata` / `:solana_programs` / `:solana_system_program` / `:solana_token_program` / `:solana_token` so Solana short names resolve without colliding with the Ethereum surface (`:signer` / `:keys` / `:transaction` continue to point at the Ethereum modules). `Cartouche.describe(:solana_transaction, :sign_partial)` returns Level-3 detail explicitly documenting the empty-signer placeholder return shape from Task 57 ("with required signer slots filled by signatures where provided and zero-filled placeholder signatures elsewhere; an empty signer map returns the unsigned transaction message with every required signature slot set to `<<0::512>>`"); regression coverage in `test/descripex_validation_test.exs` asserts the description matches verbatim. `Solana.Signer`'s 4 previously-undocced defs covered: `child_spec`/`start_link` get `api()`-generated `@doc` (closing the doctor gap as a side effect); GenServer `init`/`handle_call` get `@doc false` per the internal-surface convention. `lib/cartouche.ex` itself now declares `use Descripex, namespace: "/cartouche"` and registers `api()` blocks for the public discovery helpers `describe/0,1,2` (closing the CodeRabbit-flagged self-discoverability gap from Task 85's review); `__descripex_modules__/0` gets `@doc false` per the `__foo__/N` reserved-for-metadata convention. The `transaction_dispatch_detail/2` private helper drops the explicit `:transaction` short-name match — alias normalization at the public entry point now resolves it before dispatch. Two revision rounds resolved before merge: round 1 addressed CodeRabbit Round 1's three test-quality push-backs (alias loop strengthened to assert each alias resolves to its expected module via `==`; the async `:contracts` config test flipped to `async: false` and `on_exit` restores the prior value rather than deleting the whole key; `wrapped_sol_mint` return type corrected from `:solana_program_id` to `:solana_mint` since it returns a mint address, not a program id); round 2 resolved a `lib/cartouche.ex` merge conflict against newer `development` (Solana RPC + Ethereum aliases preserved alongside the new Solana builder aliases). Two CodeRabbit Round 2 quick-win nitpicks dropped per ceremony floor (>5 LOC cosmetic, no correctness impact) — per-arity `:hints` shape assertions and `describe/*` happy-path doctests; the existing ExUnit assertions cover the contract that matters. Codex GitHub bot's P1 (`alias` as loop var) was confirmed as a false positive — `alias` is a special form/macro, not a reserved keyword, and is valid as a variable name; CI compile + run proves it. Two pre-existing `Solana.Transaction` correctness gaps surfaced by the bot ensemble — `sign/2` doesn't validate `length(seeds) == message.header.num_required_signatures` (can produce signature-count-mismatched transactions Solana RPC rejects); `add_signature/3`'s `List.replace_at/3` silently no-ops on out-of-bounds index (no error to caller, partially-signed transaction looks complete) — out of scope per the explicit "no function-body changes" rule and filed as Tasks 91 + 92 (critical-tier 95% coverage gate before mutation). Metadata-only — no runtime code path changes. Task 88 remains.
- Annotate `Cartouche.Solana.RPC` with descripex `api()` metadata (Phase 12 / ROADMAP Task 86 / INE-33 / PR #43). `use Descripex, namespace: "/solana/rpc"` registered; 19 `api()` blocks placed above each existing `@doc` so prose survives in slot 4 and hints land in slot 5; `Cartouche.Solana.RPC` added to `Cartouche.@descripex_modules`. `Cartouche.describe(:solana_rpc)` returns Level-2 listings; `.describe(:solana_rpc, :get_balance)` (etc.) returns Level-3 detail with non-empty `params` / `returns` / `description`. Pubkey descriptions standardized on raw 32-byte binary form (`<<_::256>>`, Base58-encoded internally by `encode_pubkey/1`) — agents shouldn't pre-Base58 inputs. Three review rounds resolved before merge: round 1 corrected `send_rpc/3` return metadata (`type: :rpc_error` → `type: :term`) and aligned pubkey descriptions across `get_balance`, `get_account_info`, `get_multiple_accounts`, `get_token_account_balance`, `get_token_accounts_by_owner`, `get_recent_prioritization_fees`, `request_airdrop` with the actual binary `@spec`; round 2 fixed `replace_recent_blockhash` (was annotated `:exchange_data` with a `source:` pointer — it's a boolean flag) and `get_health` return shape (`:ok_error_tuple` was misleading — actual shape is `:ok | {:error, term()}` per Task 64); round 3 standardized the four remaining `:exchange_data` sites (`get_transaction.signature`, `send_transaction.transaction`, `simulate_transaction.transaction`, `send_and_confirm.transaction`) to `kind: :value` matching the `get_signature_statuses` precedent — caller-supplied wire-encoded payloads are values regardless of whether the agent obtained them via prior fetches, and `get_signature_statuses` already established the convention for the same shape. Post-merge cleanup: `get_token_accounts_by_owner/3` `@doc` realigned with the `api/2` block + implementation (impl uses `cond` checking `:mint` first, then `:program_id`, raises only when neither is provided — so both filters are allowed and `:mint` takes precedence; the prior `@doc` claimed "exactly one filter" which contradicted both surfaces). Metadata-only — no runtime code path changes. Tasks 87-88 remain.
- Annotate `Cartouche.Signer` + `Cartouche.Keys` with descripex `api()` metadata (Phase 12 / ROADMAP Task 83 / INE-28 / PR #39). `Cartouche.Signer` declares `use Descripex, namespace: "/ethereum/signer"` with `api()` blocks for `child_spec/1`, `start_link/1`, `sign/3`, `address/1`, `chain_id/1`, and `sign_direct/4`; `Cartouche.Keys` declares `namespace: "/ethereum/keys"` with an `api()` block for `generate_keypair/0`. Both modules now appear in `Cartouche.__descripex_modules__/0`, so `Cartouche.describe(:signer)` / `Cartouche.describe(:keys)` return Level-2 listings and `Cartouche.describe(:signer, :sign_direct)` (etc.) returns Level-3 detail with non-empty `params`, `returns`, `description`. Each `api()` block sits *above* the existing `@doc` so the human-readable prose remains in slot 4 while hints land in slot 5. Metadata-only — no runtime code path changes; param kinds use `:value` for caller-supplied inputs (chain id, signer name, MFA, message bytes) per the Task 83 instruction set. `sign_direct/4`'s `chain_id_or_name` description is "Ethereum chain id integer or configured chain atom" — explicitly excludes string inputs that `Cartouche.Chain.parse_id/1` would reject. Tasks 84-88 remain.

### Bumped

- `mix hex.outdated` refresh (the 0.2.1 publish set): `decimal` 3.1.0 → 3.1.1 (patch, inside the existing `~> 3.1` pin — no constraint change), `descripex` `~> 0.6.0` → `~> 0.7.0`, `ex_unit_json` `~> 0.4.3` → `~> 0.5.0`, `meck` `~> 1.1.1` → `~> 1.2.0`. Only `decimal` and `descripex` are runtime deps that reach the published package; `ex_unit_json` and `meck` are `only: [:dev, :test]` and never appear in the hex package's requirements. `ex_unit_json` 0.5 enables default flaky-retry healing — a bare run with failures re-runs only the failed tests once, healed flakes move to a top-level `flaky[]` array and stop blocking (exit 0 when every first-run failure heals); disable per-project with `config :ex_unit_json, retry: false`. `descripex` 0.7 compiles clean against `Cartouche.Manifest`'s `Descripex.Manifest.build/1` wrapper and the `api()`/`describe/0,1,2` surface (no source changes). Toolchain bumped to Elixir 1.20.0-rc.6 / OTP 29 (`.tool-versions`); under 1.20's set-theoretic type checker, styler collapsed three single-clause `when … , do:` guards in `transaction.ex` / `transaction/v3.ex` / `transaction/v4.ex`, and a `dynamic/1` identity helper was added in `wei_test.exs` to erase the static type on the intentional out-of-contract `Wei.to_wei({1.5, :eth})` input (the literal otherwise trips a compile-time `incompatible types` warning; the contract is enforced at runtime via `FunctionClauseError`). Local verification: `mix compile` clean, `mix test.json --quiet` 1085/1085 offline pass (31 `:integration` excluded; integration coverage not verified this run), `mix hex.outdated` clean (all rows up-to-date).
- `decimal` `~> 2.4.0` → `~> 3.1` and `doctor` `~> 0.22.0` → `~> 0.23.0` (paired bump; cartouche → 0.2.1). Decimal 3.0 (2026-05-07) tightens IEEE 754 decimal128 bounds — default precision raised 28 → 34, `emax`/`emin` capped at ±6_144, and `Decimal.parse/1` / `cast/1` reject inputs > 34 digits or > 6_144 absolute exponent (DoS-bounded — CVE-2026-32686 mitigations now standard). 3.1 (2026-05-08) added `Decimal.new/2` keyword opts forwarded to `parse/2` and fixed `Decimal.to_integer/1` infinite loop when coefficient is 0 with negative exponent (e.g. `Decimal.new("0.0")`) — would have bitten cartouche if any code path normalized zero-amount fees/balances through `to_integer`. The token-math audit blocker from the prior pin comment is cleared: no changes to rounding modes, comparison (`Decimal.cmp/2` / `compare/2`), or normalization semantics — only bounds tightened. Wei values (uint256 raw is ~78 digits; base-unit Decimals stay well under 34 sig figs in practice) fit comfortably under the new defaults, and the 6_178-char `to_string` cap is irrelevant for EVM amounts. `Inspect`, `String.Chars`, and `JSON.Encoder` protocols pass `max_digits: :infinity` so debug/serialization paths still succeed on any width. `doctor` 0.23.0 required `decimal ~> 3.1`, which was the load-bearing reason for the paired bump — bumping doctor alone would have failed resolution, holding decimal at 2.4 would have held doctor at 0.22. mix.exs decimal comment rewritten to record the audit verdict (CVE bounds + token-math no-op) so the next outdated pass doesn't re-litigate the question; the doctor "pinned to 0.22 because decimal" comment removed (no longer applies). Drive-by `:mint` added to `mix.exs` `:plt_add_apps` so `mix dialyzer` resolves `Mint.Types.status/0` / `Mint.Types.headers/0` referenced from `deps/finch/lib/finch/response.ex` (3 pre-existing `unknown_type` warnings cleared — surfaced by the prior `finch` 0.21 → 0.22 bump in `02334af` where mint's transitive type aliases joined finch's public type, and `plt_add_deps: :apps_direct` doesn't pull transitives). Local verification: `mix compile --warnings-as-errors` clean (Tesla 1.17.0 deprecation warning from `tesla/builder.ex` is pre-existing dep noise — not new from this bump), `mix test.json --quiet` 1085/1085 offline pass (31 `:integration` excluded; integration coverage not verified this run), `mix format --check-formatted` clean, `mix credo --strict` 5 design suggestions (all pre-existing TODO tags — tracked-debt convention per `feedback_todo_credos_visible.md`, unchanged from baseline), `mix sobelow --exit Low` clean, `mix doctor --summary --failed` 100% (79 modules, 0 failures — doctor 0.23 ran identically to 0.22 against cartouche's surface), `mix dialyzer.json --quiet` 0/0 warnings (was 3 on `development`; cleared by the `:mint` PLT addition). Decimal changelog: https://github.com/ericmj/decimal/blob/main/CHANGELOG.md.
- Dev/test dep refresh against `mix hex.outdated`: `reach` `~> 2.2.0` → `~> 2.7` (2.2.0 → 2.7.1 — picks up the 5-canonical-CLI surface documented in `~/.claude/includes/reach.md` and matches the include's stated minimum), `ex_ast` `~> 0.11.0` → `~> 0.12` (forced by reach 2.7's `ex_ast ~> 0.12.0` requirement; also brings cartouche in line with the global include recommendation), `finch` `~> 0.21.0` → `~> 0.22` (0.21.0 → 0.22.0); `mix deps.update` also picked up `bandit` 1.11.0 → 1.11.1 and `ex_doc` 0.40.1 → 0.40.3 patch bumps that were already inside the existing `~>` pins. Project-level `mix.exs` line 28 of `~/.claude/includes/development-commands.md` updated to match (ex_ast min version `~> 0.11` → `~> 0.12`). `doctor` deliberately held at `~> 0.22.0` — 0.23 requires `decimal ~> 3.1` which is blocked by cartouche's intentional `decimal ~> 2.4.0` pin (token-amount math semantics — re-evaluate together when a `decimal` 3.x audit task lands). `decimal` itself moved 2.4.0 → 2.4.1 (patch, inside the existing pin — no semver concern). Local verification: `mix compile --warnings-as-errors` clean (Tesla 1.17.0 deprecation warnings from `tesla/builder.ex` are pre-existing dep noise, not cartouche-side), `mix test.json --quiet` 1085/1085 offline pass (31 `:integration` excluded; integration coverage not verified this run), `mix doctor --raise` 100% / 79 modules, `mix hex.outdated` four blocking rows cleared (`decimal` + `doctor` remain "Update not possible" by the deliberate pins above). No source changes required — reach 2.x's "legacy mix tasks removed" notice is past-tense for cartouche (the only `mix reach.*` references in the repo are historical narrative in `ROADMAP.md` / `ROADMAP.old.md` / `cleanup.md` dated 2026-04-21 at reach 1.6.0; harness CI does not invoke reach).
- `finch` `mix.exs` pin tightened `~> 0.19` → `~> 0.21` (lockfile already on 0.21.0; no resolution churn). Audit verdict: no code-level adoption opportunities across 0.20 + 0.21 — every enhancement targets streaming (`Finch.stream/5`, `stream_while/5` halt + accumulator-on-failure), pool config (`get_pool_status/2`, manual termination, `start_pool_metrics?`), telemetry, or TLS (`:supported_groups`), none of which cartouche exercises. Cartouche's Finch surface is the simple subset (`Finch.build/3` + `client.request/3` + `Cartouche.HTTP.normalize_finch_result/1` pattern-matching `%Finch.Response{}` and `%Finch.Error{reason:}`) across 4 callsites in `application.ex`, `rpc.ex`, `solana/rpc.ex`, `open_chain.ex`, `http.ex`. The two changes cartouche silently benefits from in 0.21.0 are the HTTP/1 idle-pool termination fix (#292) and the HTTP/2 server-push crash guard (#333) — both bug fixes, not API additions. The pin tightening exists so downstream consumers' resolvers can't pick a pre-fix 0.19.x/0.20.x even though cartouche's CI runs on 0.21.0. Existing 4 tests in `test/http_test.exs` continue to cover the `Finch.Error` / `Finch.Response` shapes (unchanged across the upgrade range). Closes ROADMAP Tasks 27 + 28.

## [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 `@spec`s 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 `@spec`s 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 `send`ing 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/1`s 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](https://github.com/hayesgm/signet), originally authored by Geoffrey Hayes at Compound Labs, Inc. (2022). The upstream MIT license is preserved alongside the ZenHive copyright in `LICENSE`.