feat(cli): add contract diagnostic tool for direct on-chain inspection by vfusco · Pull Request #765 · cartesi/rollups-node

vfusco · 2026-03-20T14:02:45Z

Read-only CLI tool that queries Ethereum contracts directly via eth_call
and eth_getLogs — no database required.

Nine subcommands: summary, app, consensus, inputbox, tournament, epoch,
output, commitment, match. Auto-discovers contract tree from application
address, detects consensus type via ERC-165, uses FindTransitions for
efficient event discovery, and supports --tree for recursive tournament
traversal.

Copilot

Pull request overview

Adds an experimental, read-only contract diagnostics subtree to cartesi-rollups-cli that inspects Cartesi Rollups contracts directly via RPC (eth_call / eth_getLogs), plus supporting utilities and bindings.

Changes:

Introduces cartesi-rollups-cli contract ... with subcommands for application/consensus/inputbox/tournament/epoch/summary/output/commitment/match inspection.
Adds JSON-RPC error extraction + revert-selector matching utilities and reuses them in PRT tournament handling.
Extends generated contract bindings to include IAuthority and IQuorum.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
pkg/ethutil/rpcerror.go	Adds JSON-RPC error info extraction and selector-matching helpers.
pkg/contracts/iquorum/iquorum.go	New generated Go binding for `IQuorum`.
pkg/contracts/iauthority/iauthority.go	New generated Go binding for `IAuthority`.
pkg/contracts/generate/main.go	Updates binding generator to include `IAuthority` and `IQuorum`.
internal/prt/util.go	Re-exports JSON-RPC error helpers from `pkg/ethutil` for backward compatibility.
internal/prt/itournament_adapter.go	Uses shared JSON-RPC error helpers and selector matching for “no winner” revert detection.
cmd/cartesi-rollups-cli/root/root.go	Registers new `contract` command under the CLI root.
cmd/cartesi-rollups-cli/root/contract/contract.go	Implements `contract` parent command, shared RPC client setup, consensus detection, and common helpers.
cmd/cartesi-rollups-cli/root/contract/types.go	Defines JSON output types for all `contract` subcommands.
cmd/cartesi-rollups-cli/root/contract/app.go	Implements `contract app` (IApplication inspection + JSON/text output).
cmd/cartesi-rollups-cli/root/contract/consensus.go	Implements `contract consensus` (auto-detect Authority/Quorum/DaveConsensus).
cmd/cartesi-rollups-cli/root/contract/inputbox.go	Implements `contract inputbox` (discover + query InputBox).
cmd/cartesi-rollups-cli/root/contract/tournament.go	Implements `contract tournament` (tournament state, events, and optional tree traversal).
cmd/cartesi-rollups-cli/root/contract/epoch.go	Implements `contract epoch` (event-based epoch/claim history across consensus types).
cmd/cartesi-rollups-cli/root/contract/summary.go	Implements `contract summary` (parallel snapshot across app/consensus/inputbox/tournament).
cmd/cartesi-rollups-cli/root/contract/output.go	Implements `contract output` (output execution checks).
cmd/cartesi-rollups-cli/root/contract/commitment.go	Implements `contract commitment` (commitment state lookup in current tournament).
cmd/cartesi-rollups-cli/root/contract/match.go	Implements `contract match` (match state + commitment discovery via events).
cmd/cartesi-rollups-cli/root/contract/selectors.go	Defines selector constants and sentinel errors used by the tool.
cmd/cartesi-rollups-cli/root/contract/format.go	Adds formatting + text-output helper primitives.
cmd/cartesi-rollups-cli/root/contract/contract_test.go	Unit tests for shared helpers (safeUint64/parseBlockFlag/validateHash/consensusType).
cmd/cartesi-rollups-cli/root/contract/format_test.go	Unit tests for formatting and printer output.
cmd/cartesi-rollups-cli/root/contract/epoch_test.go	Unit tests for epoch history helpers (block range + merge).
cmd/cartesi-rollups-cli/root/contract/tournament_test.go	Unit tests for tournament event formatting and commitment registry resolution.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cmd/cartesi-rollups-cli/root/contract/tournament.go

pkg/ethutil/rpcerror.go

cmd/cartesi-rollups-cli/root/contract/contract.go

cmd/cartesi-rollups-cli/root/contract/epoch.go

cmd/cartesi-rollups-cli/root/contract/tournament.go

vfusco · 2026-03-24T14:34:58Z

Examples:

$ ./cartesi-rollups-cli contract summary 0x611aaf21ec80e0c9036b8189e053f58ba9ca8cf4
Application  0x611aaf21eC80e0c9036b8189e053F58ba9Ca8cF4
    Template Hash           0xe980d69ba94684e7d7c6662834e85681402161f5edf4e522a1a22a8cc765115d
    Owner                   0x0000000000000000000000000000000000000000
    Deployment Block        231
    Executed Outputs        1
    Consensus               0x07fB3e285e6051AdeE8D09162063F7D0033e054a (DaveConsensus (PRT))
    Data Availability       0xb12c9ede0000000000000000000000001b51e2992a2755ba4d6f7094032df91991a0cfac

DaveConsensus  0x07fB3e285e6051AdeE8D09162063F7D0033e054a
    Deployment Block        231
    Tournament Finished     yes (winner: 0x955a3e973718547a84efb4b4940c61b941ecf1788ba4c5266f0751a46810edc4)
    Current Sealed Epoch    2
    Root Tournament         0x684bF26D2Dd8E04fA31174213665184097ab0Bef

Root Tournament  0x684bF26D2Dd8E04fA31174213665184097ab0Bef  (level 0/3)
    Status                  FINISHED
    Finished                yes (block 1135)
    Winner                  0x955a3e973718547a84efb4b4940c61b941ecf1788ba4c5266f0751a46810edc4
    Final Machine Hash      0x79ab88bab491c427173a91277dd3d9b64b5a4c136fe7125d32004d5004bfda05
    Bond                    0.232198 ETH
    Commitments Joined      1
    Matches Created         0
    Matches Advanced        0
    Matches Deleted         0
    Inner Tournaments       0

InputBox
    Total Inputs            1

State at block            14252 (chain ID: 31337)

Note: this is an experimental diagnostic tool. Values are read directly from on-chain contracts
and may not reflect finalized state. Verify critical information independently.

Authority:

$ ./cartesi-rollups-cli contract summary 0x4e773357aea8b36ed5c01737b8c4a301e0a48a47
Application  0x4E773357AeA8b36Ed5C01737b8C4a301e0a48A47
    Template Hash           0xe980d69ba94684e7d7c6662834e85681402161f5edf4e522a1a22a8cc765115d
    Owner                   0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
    Deployment Block        210
    Executed Outputs        1
    Consensus               0x7E6764634d47b70AEF4E18AEF7A03909Ae9C5dA1 (Authority)
    Data Availability       0xb12c9ede0000000000000000000000001b51e2992a2755ba4d6f7094032df91991a0cfac

Authority  0x7E6764634d47b70AEF4E18AEF7A03909Ae9C5dA1
    Owner (Validator)       0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
    Epoch Length            10 blocks
    Accepted Claims         1

InputBox
    Total Inputs            1

State at block            14454 (chain ID: 31337)

Note: this is an experimental diagnostic tool. Values are read directly from on-chain contracts
and may not reflect finalized state. Verify critical information independently.

vfusco · 2026-03-24T14:35:36Z

$ ./cartesi-rollups-cli contract tournament 0x611aaf21ec80e0c9036b8189e053f58ba9ca8cf4 --events --timestamps
Application  0x611aaf21eC80e0c9036b8189e053F58ba9Ca8cF4
    Epoch                   2

Root Tournament  0x684bF26D2Dd8E04fA31174213665184097ab0Bef  (level 0/3)
    Status                  FINISHED
    Finished                yes (block 1135)
    Winner                  0x955a3e973718547a84efb4b4940c61b941ecf1788ba4c5266f0751a46810edc4
    Final Machine Hash      0x79ab88bab491c427173a91277dd3d9b64b5a4c136fe7125d32004d5004bfda05
    Bond                    0.232198 ETH
    Commitments Joined      1
    Matches Created         0
    Matches Advanced        0
    Matches Deleted         0
    Inner Tournaments       0

Commitments Joined:

    [1] Commitment  0x955a3e973718547a84efb4b4940c61b941ecf1788ba4c5266f0751a46810edc4
        Submitter               0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
        Final State             0x79ab88bab491c427173a91277dd3d9b64b5a4c136fe7125d32004d5004bfda05
        Block                   839
        Tx                      0x24dc0dd9d8091f6c8cefe512d963b6d7aa9693543c6f7423a18cbf0dd317f6de

State at block            14262 (chain ID: 31337) (2026-03-20 02:31:24 UTC)

Note: this is an experimental diagnostic tool. Values are read directly from on-chain contracts
and may not reflect finalized state. Verify critical information independently.

vfusco · 2026-03-24T14:37:24Z

$ ./cartesi-rollups-cli contract --help
[Experimental] Read on-chain contract state directly via eth_call and eth_getLogs

Usage:
  cartesi-rollups-cli contract [flags]
  cartesi-rollups-cli contract [command]

Available Commands:
  app         Query application contract state (IApplication)
  commitment  Read a commitment's on-chain state from the current tournament
  consensus   Query consensus contract state (auto-detects Authority/Quorum/DaveConsensus)
  epoch       Show epoch history (claims, sealed epochs, events)
  inputbox    Query InputBox contract state (total inputs for application)
  match       Inspect a specific match's bisection state
  output      Check output execution status
  summary     Full diagnostic snapshot (composes app + consensus + inputbox + root tournament)
  tournament  Query tournament contract state (PRT dispute resolution)

Flags:
      --block string     Query view functions at this block number (default: latest, pinned at startup) (default "latest")
  -h, --help             help for contract
      --json             Machine-readable JSON output
      --timeout string   Context deadline for the entire command execution (default "30s")
      --timestamps       Resolve block numbers to wall-clock times (extra RPC calls)

Global Flags:
      --blockchain-http-endpoint string   Blockchain HTTP endpoint
      --inputbox string                   Input Box contract address

Use "cartesi-rollups-cli contract [command] --help" for more information about a command.

Read-only diagnostic tool that queries Cartesi Ethereum smart contracts directly.
No database required — only an RPC endpoint and an application address.

Experimental:
This tool is experimental and may produce inaccurate results. Values are read
directly from on-chain contracts and may not reflect finalized state. Verify
critical information independently before acting on it.

Supported Environment Variables:
  CARTESI_BLOCKCHAIN_HTTP_ENDPOINT    Ethereum RPC endpoint URL
  CARTESI_CONTRACTS_INPUT_BOX_ADDRESS InputBox contract address (optional override)

Read-only CLI tool that queries Ethereum contracts directly via eth_call and eth_getLogs — no database required. Nine subcommands: summary, app, consensus, inputbox, tournament, epoch, output, commitment, match. Auto-discovers contract tree from application address, detects consensus type via ERC-165, uses FindTransitions for efficient event discovery, and supports --tree for recursive tournament traversal.

mpolitzer · 2026-03-24T21:04:02Z

cmd/cartesi-rollups-cli/root/contract/contract.go

+// parseBlockFlag parses the --block flag value into a *big.Int.
+// Returns nil for "latest" (the caller resolves it via eth_blockNumber).
+func parseBlockFlag(s string) (*big.Int, error) {
+	if s == "" || s == "latest" {


what about "finalized" and "safe", should it handle those as well?

mpolitzer · 2026-03-24T21:13:46Z

cmd/cartesi-rollups-cli/root/contract/epoch.go

+		// Note: ClaimSubmitted has indexed topics (submitter, appContract).
+		// We cannot use appTopic here because it would filter on submitter (topic1),
+		// not appContract (topic2). Instead, fetch all and filter in Go.
+		subQ, qErr := buildEventFilterQuery(


I'm not sure I understood the restriction from the comment.
Won't nil, appContract for topics solve it?

FilterLogs & ChunkedFilterLogs support matching only the second index if I understood this comment correctly.

vfusco added this to the 2.0.0 milestone Mar 20, 2026

vfusco requested review from Copilot and mpolitzer March 20, 2026 14:02

vfusco self-assigned this Mar 20, 2026

vfusco added this to Rollups SDK Mar 20, 2026

github-project-automation bot moved this to Todo in Rollups SDK Mar 20, 2026

Copilot started reviewing on behalf of vfusco March 20, 2026 14:03 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

vfusco force-pushed the feature/contract-helper-tool branch 3 times, most recently from 66f4738 to 8e20357 Compare March 20, 2026 14:52

vfusco changed the base branch from next/2.0 to fix/advancer-snapshot-sync March 20, 2026 14:52

vfusco force-pushed the fix/advancer-snapshot-sync branch 4 times, most recently from dc91e3e to c0094d6 Compare March 23, 2026 14:36

vfusco force-pushed the feature/contract-helper-tool branch from 8e20357 to ab963f0 Compare March 23, 2026 14:55

vfusco requested review from guidanoli and renatomaia March 23, 2026 15:33

vfusco marked this pull request as ready for review March 23, 2026 15:34

Base automatically changed from fix/advancer-snapshot-sync to next/2.0 March 23, 2026 22:42

vfusco force-pushed the feature/contract-helper-tool branch from ab963f0 to 28c9c3c Compare March 24, 2026 15:40

renatomaia approved these changes Mar 24, 2026

View reviewed changes

github-project-automation bot moved this from Todo to Waiting Merge in Rollups SDK Mar 24, 2026

mpolitzer approved these changes Mar 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add contract diagnostic tool for direct on-chain inspection#765

feat(cli): add contract diagnostic tool for direct on-chain inspection#765
vfusco wants to merge 1 commit intonext/2.0from
feature/contract-helper-tool

vfusco commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vfusco commented Mar 24, 2026 •

edited

Loading

Uh oh!

vfusco commented Mar 24, 2026

Uh oh!

vfusco commented Mar 24, 2026

Uh oh!

mpolitzer Mar 24, 2026

Uh oh!

mpolitzer Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

vfusco commented Mar 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vfusco commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vfusco commented Mar 24, 2026

Uh oh!

vfusco commented Mar 24, 2026

Uh oh!

mpolitzer Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

mpolitzer Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vfusco commented Mar 24, 2026 •

edited

Loading