Skip to content

feat!: migrate RPC methods to context-first signatures - #44

Merged
neverDefined merged 1 commit into
mainfrom
phase-2/context-first-rpc
Apr 23, 2026
Merged

feat!: migrate RPC methods to context-first signatures#44
neverDefined merged 1 commit into
mainfrom
phase-2/context-first-rpc

Conversation

@neverDefined

@neverDefined neverDefined commented Apr 23, 2026

Copy link
Copy Markdown
Owner

Phase 2 PR C — the largest breaking change in the roadmap. Every mutating RPC wrapper now takes `context.Context` as its first parameter, so callers can enforce per-call deadlines and cancellation.

Summary

Breaking (pre-1.0; will bump the next minor tag):

  • 18 methods gain a leading `ctx context.Context`: `MineBlock`, `SetNextBlockTimestamp`, `IncreaseTime`, `SetBalance`, `Impersonate`, `StopImpersonating`, `Snapshot`, `Revert`, `SetCode`, `SetStorageAt`, `SetNonce`, `Mine`, `DropTransaction`, `SetAutomine`, `SetIntervalMining`, `AutoImpersonate`, `ResetFork`, `ResetState`.
  • Internal calls migrated from `rpcClient.Call(nil, ...)` to `rpcClient.CallContext(ctx, ...)`.
  • `EthereumTestEnvironment` interface updated to match.

Additive:

  • `(*Anvil).WaitForMemPoolEmpty(ctx, timeout)` — method variant that honors both ctx and an explicit timeout; uses the instance's own client.

Deprecated:

  • Free function `MemPoolEmpty(ctx, client)` — kept as a shim for one release with `// Deprecated:` godoc tag.

Docs updated:

  • `CHANGELOG.md` — Changed / Added / Deprecated sections with a migration snippet.
  • `CLAUDE.md` — replaced the "pending migration" note with the current API shape and a template for new RPC wrappers.
  • `README.md` — Quick Start and every Usage Examples snippet updated to pass `ctx`.

Migration

```go
// before
anvil.MineBlock()
anvil.SetBalance(addr, bal)
snapshotID, _ := anvil.Snapshot()

// after
ctx := context.Background() // or t.Context() in tests, or ctx with a timeout
anvil.MineBlock(ctx)
anvil.SetBalance(ctx, addr, bal)
snapshotID, _ := anvil.Snapshot(ctx)
```

Test plan

  • `go build ./...` clean
  • `go vet ./...` clean
  • `golangci-lint run ./...` — 0 issues
  • `go test -race ./...` — green locally, 30s, against anvil 1.5.0 (includes 2 new WaitForMemPoolEmpty subtests: success path + ctx-cancel path)
  • CI: all three jobs (test / vuln / lint) green on the matrix

Scope notes

  • Pre-existing examples outside this repo will need to add `ctx` arguments — the one migration snippet above covers the transformation.
  • `WaitForBlock` already takes a `timeout` and constructs its own ctx internally; its signature is unchanged.
  • Pure Go getters (`Client`, `RPCClient`, `Metrics`, `Accounts`) do not take ctx — they don't call RPC.
  • Lifecycle methods (`Start`, `Stop`, `Close`) are unchanged.

Closes #36
Closes #39

Follow-ups in this phase

🤖 Generated with Claude Code

Every mutating RPC wrapper now takes context.Context as its first
parameter and forwards to a.rpcClient.CallContext(ctx, ...). A hung
RPC no longer blocks the caller indefinitely — callers can enforce
deadlines and cancellation per operation.

Affected methods (breaking):
  MineBlock, SetNextBlockTimestamp, IncreaseTime, SetBalance,
  Impersonate, StopImpersonating, Snapshot, Revert, SetCode,
  SetStorageAt, SetNonce, Mine, DropTransaction, SetAutomine,
  SetIntervalMining, AutoImpersonate, ResetFork, ResetState.

EthereumTestEnvironment interface updated to match.

MemPoolEmpty helper promoted to (*Anvil).WaitForMemPoolEmpty(ctx,
timeout) so it uses the instance's own client and honors both ctx
deadlines and an explicit timeout. The free function MemPoolEmpty is
kept as a Deprecated shim for one release.

Tests migrated to pass t.Context() everywhere; the former
anvil.context escape hatch used in test bodies is no longer needed.
Two new subtests cover WaitForMemPoolEmpty success and ctx-cancel
paths.

Docs updated: CHANGELOG entries under Changed / Added / Deprecated
with a migration snippet; CLAUDE.md's "pending migration" section
replaced with the current-API shape and an example; README quick
start and usage examples updated to use ctx.

Locally verified: go build / go vet clean, golangci-lint 0 issues,
go test -race ./... green in ~30s.

Closes #36
Closes #39

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@neverDefined
neverDefined merged commit 47433de into main Apr 23, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[phase-2] promote MemPoolEmpty to *Anvil method with ctx + timeout [phase-2] migrate RPC methods to context-first signatures (breaking)

1 participant