feat!: track the rollups-node JSON-RPC API changes

Mirror the JSON-RPC API changes of the Cartesi node in @cartesi/rpc, and
bubble them down to @cartesi/client and @cartesi/react.

Derived from cartesi/rollups-node#793, which has since merged into
next/2.0 as 7558af6, so this is no longer a forward-looking port. It was
verified against the merged jsonrpc-discover.json rather than the pull
request diff: @cartesi/rpc declares exactly the 28 methods the merged
specification defines, and every schema and parameter change between the
pre-793 base (9bdd988) and merged next/2.0 is reflected here.
Cross-checked against internal/jsonrpc/api/params.go,
internal/jsonrpc/jsonrpc.go and internal/model/models.go.

New methods:

- cartesi_getEpochByVirtualIndex, fetching an epoch by its dense
  insertion rank (getEpochByVirtualIndex / useEpochByVirtualIndex)
- cartesi_getExecutedOutputCount and
  cartesi_getPendingExecutableOutputCount (getExecutedOutputCount /
  useExecutedOutputCount, getPendingExecutableOutputCount /
  usePendingExecutableOutputCount). The executed count is monotone and
  meant to be polled for change detection; the pending count is a gauge
  and is not.
- cartesi_getNodeInfo, returning the chain id, the node version and the
  node's default block tag in one call (getNodeInfo / useNodeInfo). It
  replaces cartesi_getChainId and cartesi_getNodeVersion, which the node
  deprecated and which are now marked @deprecated here too.

New listing filters:

- from/to inclusive index ranges on listEpochs, listInputs, listOutputs
  and listReports
- a list of statuses on listEpochs, and a list of output types plus the
  new executed flag on listOutputs

The node rejects an empty status or output_type list with invalid
params, so the list-valued filters are typed as NonEmptyArray<T> rather
than T[]: `status: []` and `outputType: []` are compile errors instead
of failed requests. listOutputs maps the output types to selectors
through the head of the list separately, so the result stays non-empty
for the type checker, which Array.prototype.map would widen back to
Hex[]. The constraint is guarded by a *.test-d.ts suite in
@cartesi/client, which needed vitest type testing enabled there — CI
runs `pnpm test` but no `tsc --noEmit` over the test files, so without
it the constraint would go unchecked.

Input completion changes, which landed on next/2.0 alongside but not as
part of #793:

- InputStatus loses its resource-limit members. The node collapsed
  OUTPUTS_LIMIT_EXCEEDED, REPORTS_LIMIT_EXCEEDED, CYCLE_LIMIT_EXCEEDED,
  TIME_LIMIT_EXCEEDED and PAYLOAD_LENGTH_LIMIT_EXCEEDED into the
  remaining outcomes, leaving NONE, ACCEPTED, REJECTED, EXCEPTION and
  MACHINE_HALTED. waitForInput listed four of them under rejectErrors;
  it now aborts on EXCEPTION, MACHINE_HALTED and REJECTED, which is
  every terminal status other than ACCEPTED — and no longer omits a
  failure status the way the old list omitted REPORTS_LIMIT_EXCEEDED.
- Input gains exception_data / exceptionData, the raw guest-provided
  CMIO exception payload, non-null only when the status is EXCEPTION and
  empty-encoded as 0x. The bytes are passed through undecoded, matching
  how raw_data is handled.

Breaking changes:

- cartesi_getMatchAdvanced is now cartesi_getMatchAdvance, so the
  getMatchAdvanced action is getMatchAdvance, the useMatchAdvanced hook
  is useMatchAdvance and the GetMatchAdvanced* types are GetMatchAdvance*
- the node's application-level error codes moved out of the JSON-RPC
  reserved range (-31001/-31002 instead of -32001/-32002); they are now
  exported from @cartesi/rpc as errorCodes, along with the new batch
  (-32040), timeout (-32070), response-size-limit (-31003) and
  batch-list-work (-31004) codes, plus the maxBatchSize (100),
  maxBatchListWork (10000) and defaultListLimit (50) constants that
  bound a batch
- InputStatus shrank, as described above

Batch requests needed no transport change — the underlying json-rpc-2.0
client already batches — so they are documented rather than implemented,
including the two budgets that apply beyond the entry count: the
response-size budget closes once exhausted, so every later entry gets
-31003 even if its response would still have fit, and the list-work
budget rejects the whole batch with a single -31004 before dispatching
anything. Neither meters the COUNT queries behind pagination nor offset
traversal, so a deep offset over a broad filter can still make the
database scan and discard rows before the requested page.

Two OpenRPC typing fixes needed no code change: prev_randao and voucher
value are now UnsignedInteger256 in the specification, and both were
already 256-bit-safe here.

Also reformats four @cartesi/react hooks that biome was already
reporting as unformatted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UJpa3KXxvUarBGpHvW8Qdb

Author: claude

.changeset/tricky-pianos-shake.md

@@ -0,0 +1,31 @@
+---
+"@cartesi/rpc": major
+"@cartesi/client": major
+"@cartesi/react": major
+---
+
+Track the JSON-RPC API changes of rollups-node.
+
+New methods:
+
+- `cartesi_getEpochByVirtualIndex` — fetch an epoch by its dense insertion rank, exposed as `getEpochByVirtualIndex` / `useEpochByVirtualIndex`.
+- `cartesi_getExecutedOutputCount` and `cartesi_getPendingExecutableOutputCount`, exposed as `getExecutedOutputCount` / `useExecutedOutputCount` and `getPendingExecutableOutputCount` / `usePendingExecutableOutputCount`. The executed count is monotone and meant to be polled for change detection; the pending count is a gauge and is not.
+- `cartesi_getNodeInfo` — chain ID, node version and the node's default block tag in one call, exposed as `getNodeInfo` / `useNodeInfo`. It replaces `getChainId` and `getNodeVersion`, which the node deprecated and which are now marked `@deprecated`.
+
+New filters on the listing methods:
+
+- `from` and `to`, an inclusive index range, on `listEpochs`, `listInputs`, `listOutputs` and `listReports`.
+- `listEpochs` takes a list of statuses (`status?: EpochStatus | NonEmptyArray<EpochStatus>`), so unsettled epochs can be watched by filtering on the non-terminal ones.
+- `listOutputs` takes a list of output types (`outputType?: OutputType | NonEmptyArray<OutputType>`) and a new `executed?: boolean` filter. Because executions happen out of index order, `executed` must not be used to build a resume cursor keyed on the output index — poll `getExecutedOutputCount` instead.
+
+The node rejects an empty filter list with invalid params, so both list-valued filters use the new `NonEmptyArray` type exported by `@cartesi/rpc` (and re-exported by `@cartesi/client`): `status: []` and `outputType: []` are compile errors rather than failed requests.
+
+Input completion changes:
+
+- `InputStatus` lost its resource-limit members. The node collapsed `OUTPUTS_LIMIT_EXCEEDED`, `REPORTS_LIMIT_EXCEEDED`, `CYCLE_LIMIT_EXCEEDED`, `TIME_LIMIT_EXCEEDED` and `PAYLOAD_LENGTH_LIMIT_EXCEEDED` into the remaining outcomes, so the union is now `NONE | ACCEPTED | REJECTED | EXCEPTION | MACHINE_HALTED`. Code that switches on the removed members no longer compiles; `waitForInput` with `rejectErrors` now aborts on `EXCEPTION`, `MACHINE_HALTED` and `REJECTED`, which is every terminal status other than `ACCEPTED`.
+- `Input` gained `exceptionData: Hex | null` (`exception_data` on the wire), the raw guest-provided CMIO exception payload. It is non-null only when `status` is `EXCEPTION`, and an empty payload is `0x`. The bytes are passed through undecoded.
+
+Breaking changes:
+
+- `cartesi_getMatchAdvanced` was renamed to `cartesi_getMatchAdvance`, following the node. The `getMatchAdvanced` action is now `getMatchAdvance`, the `useMatchAdvanced` hook is now `useMatchAdvance` (with `matchAdvanceOptions` / `matchAdvanceQueryKey`), and `GetMatchAdvancedParams` / `GetMatchAdvancedReturnType` are now `GetMatchAdvanceParams` / `GetMatchAdvanceReturnType`.
+- The node's application-level error codes moved out of the JSON-RPC reserved range: application not found is now `-31002` (was `-32002`) and resource not found is now `-31001` (was `-32001`). `@cartesi/rpc` exports them as `errorCodes`, along with the new batch (`-32040`), timeout (`-32070`), response-size-limit (`-31003`) and batch-list-work (`-31004`) codes, plus the `maxBatchSize`, `maxBatchListWork` and `defaultListLimit` constants that bound a batch.

apps/docs/pages/client/getEpochByVirtualIndex.mdx

@@ -0,0 +1,39 @@
+# getEpochByVirtualIndex
+
+Fetches a single epoch by its virtual index, which is the epoch's dense
+insertion rank — 0, 1, 2, … with no gaps by construction. Use it to walk the
+epochs of an application contiguously, where the epoch index itself can skip
+values.
+
+## Usage
+
+```ts twoslash
+import { http } from "viem";
+import { createCartesiPublicClient } from "@cartesi/client";
+
+const publicClientL2 = createCartesiPublicClient({
+  transport: http("http://127.0.0.1:6751/rpc"),
+});
+
+const epoch = await publicClientL2.getEpochByVirtualIndex({
+  application: "0x...",
+  virtualIndex: 42n,
+});
+```
+
+## Parameters
+
+```ts twoslash
+import type { GetEpochByVirtualIndexParams } from "@cartesi/client";
+// {
+//   application: Address | string;
+//   virtualIndex: bigint;
+// }
+```
+
+## Return Type
+
+```ts twoslash
+import type { GetEpochByVirtualIndexReturnType, Epoch } from "@cartesi/client";
+// GetEpochByVirtualIndexReturnType = Epoch;
+```

apps/docs/pages/client/getExecutedOutputCount.mdx

@@ -0,0 +1,46 @@
+# getExecutedOutputCount
+
+Number of outputs of an application that were already executed.
+
+The count is monotone, so an unchanged value means no new executions have been
+observed and it is a sound change signal to poll. When it changes, re-query the
+bounded executable-output working set with
+[`listOutputs`](/client/listOutputs) using `executed: false` and
+`outputType: ["Voucher", "DelegateCallVoucher"]`, then diff that pending set
+against the previous result to identify the executions.
+
+Neither this count, nor an output index, nor a pagination offset is a valid
+resume cursor: executions are observed out of output-index order, so a late
+execution can land behind one. The node documents a race-free execution cursor
+as expected in a future ingestion API.
+
+## Usage
+
+```ts twoslash
+import { http } from "viem";
+import { createCartesiPublicClient } from "@cartesi/client";
+
+const publicClientL2 = createCartesiPublicClient({
+  transport: http("http://127.0.0.1:6751/rpc"),
+});
+
+const executedOutputCount = await publicClientL2.getExecutedOutputCount({
+  application: "0x...",
+});
+```
+
+## Parameters
+
+```ts twoslash
+import type { GetExecutedOutputCountParams } from "@cartesi/client";
+// {
+//   application: Address | string;
+// }
+```
+
+## Return Type
+
+```ts twoslash
+import type { GetExecutedOutputCountReturnType } from "@cartesi/client";
+// GetExecutedOutputCountReturnType = bigint;
+```

…s/docs/pages/client/getMatchAdvanced.mdx …ps/docs/pages/client/getMatchAdvance.mdxapps/docs/pages/client/getMatchAdvanced.mdx renamed to apps/docs/pages/client/getMatchAdvance.mdx apps/docs/pages/client/getMatchAdvanced.mdx renamed to apps/docs/pages/client/getMatchAdvance.mdx

@@ -1,4 +1,4 @@
-# getMatchAdvanced
+# getMatchAdvance
 
 ## Usage
 
@@ -10,7 +10,7 @@ const publicClientL2 = createCartesiPublicClient({
   transport: http("http://127.0.0.1:6751/rpc"),
 });
 
-const matchAdvanced = await publicClientL2.getMatchAdvanced({
+const matchAdvance = await publicClientL2.getMatchAdvance({
   application: "0x...",
   epochIndex: 1n,
   tournamentAddress: "0x...",
@@ -22,7 +22,7 @@ const matchAdvanced = await publicClientL2.getMatchAdvanced({
 ## Parameters
 
 ```ts twoslash
-import type { GetMatchAdvancedParams } from "@cartesi/client";
+import type { GetMatchAdvanceParams } from "@cartesi/client";
 // {
 //   application: Address | string;
 //   epochIndex: bigint;
@@ -35,6 +35,6 @@ import type { GetMatchAdvancedParams } from "@cartesi/client";
 ## Return Type
 
 ```ts twoslash
-import type { GetMatchAdvancedReturnType, MatchAdvanced } from "@cartesi/client";
-// GetMatchAdvancedReturnType = MatchAdvanced;
+import type { GetMatchAdvanceReturnType, MatchAdvanced } from "@cartesi/client";
+// GetMatchAdvanceReturnType = MatchAdvanced;
 ```

apps/docs/pages/client/getNodeInfo.mdx

@@ -0,0 +1,30 @@
+# getNodeInfo
+
+Fetches the chain ID, the semantic node version and the blockchain block tag the
+node reads the base layer at, in a single call.
+
+It replaces `getChainId` and `getNodeVersion`, which are both deprecated.
+
+## Usage
+
+```ts twoslash
+import { http } from "viem";
+import { createCartesiPublicClient } from "@cartesi/client";
+
+const publicClientL2 = createCartesiPublicClient({
+  transport: http("http://127.0.0.1:6751/rpc"),
+});
+
+const { chainId, version, defaultBlock } = await publicClientL2.getNodeInfo();
+```
+
+## Return Type
+
+```ts twoslash
+import type { GetNodeInfoReturnType, NodeInfo } from "@cartesi/client";
+// NodeInfo = {
+//   chainId: number;
+//   version: string;
+//   defaultBlock: DefaultBlock; // FINALIZED | SAFE | LATEST | PENDING
+// }
+```

apps/docs/pages/client/getPendingExecutableOutputCount.mdx

@@ -0,0 +1,40 @@
+# getPendingExecutableOutputCount
+
+Number of executable outputs of an application that are still pending execution.
+
+This is a gauge, not a change signal or a resume cursor: it grows with new
+executable outputs and shrinks with executions, so it can return to a previous
+value while work happened in between. Poll
+[`getExecutedOutputCount`](/client/getExecutedOutputCount) instead and diff the
+pending set on change.
+
+## Usage
+
+```ts twoslash
+import { http } from "viem";
+import { createCartesiPublicClient } from "@cartesi/client";
+
+const publicClientL2 = createCartesiPublicClient({
+  transport: http("http://127.0.0.1:6751/rpc"),
+});
+
+const pending = await publicClientL2.getPendingExecutableOutputCount({
+  application: "0x...",
+});
+```
+
+## Parameters
+
+```ts twoslash
+import type { GetPendingExecutableOutputCountParams } from "@cartesi/client";
+// {
+//   application: Address | string;
+// }
+```
+
+## Return Type
+
+```ts twoslash
+import type { GetPendingExecutableOutputCountReturnType } from "@cartesi/client";
+// GetPendingExecutableOutputCountReturnType = bigint;
+```

apps/docs/pages/client/listEpochs.mdx

@@ -14,7 +14,7 @@ const { data, pagination } = await publicClientL2.listEpochs({
   application: "0x...",
   limit: 10,
   offset: 0,
-  // status (optional)
+  // status, from, to (optional)
 });
 ```
 
@@ -24,7 +24,9 @@ const { data, pagination } = await publicClientL2.listEpochs({
 import type { ListEpochsParams } from "@cartesi/client";
 // {
 //   application: Address | string;
-//   status?: EpochStatus;
+//   status?: EpochStatus | NonEmptyArray<EpochStatus>;
+//   from?: bigint;
+//   to?: bigint;
 //   limit?: number;
 //   offset?: number;
 //   descending?: boolean;
@@ -40,3 +42,7 @@ import type { ListEpochsReturnType, Epoch, Pagination } from "@cartesi/client";
 //   pagination: Pagination;
 // }
 ```
+
+The node rejects an empty status list with invalid params, so `status` is typed
+as a non-empty array — `status: []` is a compile error rather than a failed
+request.

apps/docs/pages/client/listInputs.mdx

@@ -14,7 +14,7 @@ const { data, pagination } = await publicClientL2.listInputs({
     application: "0x...",
     limit: 10,
     offset: 0,
-    // epochIndex, sender (optional)
+    // epochIndex, sender, from, to (optional)
 });
 ```
 
@@ -27,6 +27,8 @@ import type { ListInputsParams } from "@cartesi/client";
 //   epochIndex?: bigint;
 //   sender?: Address;
 //   transactionHash?: Hash;
+//   from?: bigint;
+//   to?: bigint;
 //   limit?: number;
 //   offset?: number;
 //   descending?: boolean;

apps/docs/pages/client/listOutputs.mdx

@@ -14,7 +14,7 @@ const { data, pagination } = await publicClientL2.listOutputs({
   application: "0x...",
   limit: 10,
   offset: 0,
-  // epochIndex, inputIndex, outputType, voucherAddress (optional)
+  // epochIndex, inputIndex, outputType, voucherAddress, from, to, executed (optional)
 });
 ```
 
@@ -26,14 +26,45 @@ import type { ListOutputsParams } from "@cartesi/client";
 //   application: Address | string;
 //   epochIndex?: bigint;
 //   inputIndex?: bigint;
-//   outputType?: OutputType;
+//   outputType?: OutputType | NonEmptyArray<OutputType>;
 //   voucherAddress?: Address;
+//   from?: bigint;
+//   to?: bigint;
+//   executed?: boolean;
 //   limit?: number;
 //   offset?: number;
 //   descending?: boolean;
 // }
 ```
 
+`outputType` accepts a list, and `executed` filters by execution status, so the
+outputs still waiting to be executed can be fetched in one call. The node
+rejects an empty list with invalid params, so the list is typed as a non-empty
+array — `outputType: []` is a compile error rather than a failed request:
+
+```ts twoslash
+import { http } from "viem";
+import { createCartesiPublicClient } from "@cartesi/client";
+
+const publicClientL2 = createCartesiPublicClient({
+  transport: http("http://127.0.0.1:6751/rpc"),
+});
+// ---cut---
+const { data: pending } = await publicClientL2.listOutputs({
+  application: "0x...",
+  outputType: ["Voucher", "DelegateCallVoucher"],
+  executed: false,
+});
+```
+
+::::warning
+Executions happen out of index order — an old voucher can be executed long after
+newer ones — so a resume cursor keyed on the output index over this filter
+silently skips those late executions. Poll
+[`getExecutedOutputCount`](/client/getExecutedOutputCount) for change detection
+instead.
+::::
+
 ## Return Type
 
 ```ts twoslash

apps/docs/pages/client/listReports.mdx

@@ -14,7 +14,7 @@ const { data, pagination } = await publicClientL2.listReports({
   application: "0x...",
   limit: 10,
   offset: 0,
-  // epochIndex, inputIndex (optional)
+  // epochIndex, inputIndex, from, to (optional)
 });
 ```
 
@@ -26,6 +26,8 @@ import type { ListReportsParams } from "@cartesi/client";
 //   application: Address | string;
 //   epochIndex?: bigint;
 //   inputIndex?: bigint;
+//   from?: bigint;
+//   to?: bigint;
 //   limit?: number;
 //   offset?: number;
 //   descending?: boolean;