From b14680831dae2a2d8d6486f92a4d491059d71f75 Mon Sep 17 00:00:00 2001 From: Marc Date: Mon, 20 Jul 2026 18:58:27 -0300 Subject: [PATCH 1/2] docs(genlayer-js): document where consensus results live on a transaction --- .../genlayer-js/transactions.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/pages/api-references/genlayer-js/transactions.md b/pages/api-references/genlayer-js/transactions.md index 66baa4dc..846fac45 100644 --- a/pages/api-references/genlayer-js/transactions.md +++ b/pages/api-references/genlayer-js/transactions.md @@ -94,3 +94,45 @@ Estimates gas required for a transaction. --- + +## Reading consensus results + +`getTransaction` returns consensus details, but the fields most people need are +nested and easy to miss. On a decided transaction: + +| Field | Meaning | +|-------|---------| +| `resultName` | The consensus verdict, e.g. `AGREE`. | +| `txExecutionResultName` | What the code did, e.g. `FINISHED_WITH_RETURN`, `FINISHED_WITH_ERROR`. | +| `lastRound.validatorVotes` | Per-validator vote vector, e.g. `[1, 1, 1, 1, 1]`. | +| `lastRound.validatorVotesName` | The same votes as labels, e.g. `AGREE` / `DISAGREE`. | +| `lastRound.votesCommitted` / `lastRound.votesRevealed` | Vote counts for the round. | +| `lastRound.validatorResultHash` | Per-validator result hashes; compare them to detect a split. | +| `txDataDecoded.contractAddress` | Contract address after a deploy. | + +Reading `resultName` alone is not enough to know a run was healthy. A +transaction can be `ACCEPTED` while validators split underneath, and it can be +`ACCEPTED` with every validator agreeing that the contract *raised*. Inspect the +vote vector and `txExecutionResultName` together. + +### Statuses seen while polling + +`COMMITTING` and `REVEALING` are in-flight. `ACCEPTED`, `FINALIZED`, +`UNDETERMINED` and `CANCELED` are decided. A numeric `status` value that has no +name in your SDK version (for example `14`) is a transient state, not an error: +keep polling rather than treating it as a failure. + +### Do not reach for an EVM receipt helper + +`getTransactionReceipt` from a generic EVM client returns "not found" for +GenLayer transactions. Use `getTransaction`. + +### Allow a deploy to settle before calling a write method + +Calling a write method immediately after a successful deploy can revert at the +EVM level against the consensus contract, even when the deploy itself returned a +unanimous AGREE. The same call to the same contract address succeeds once the +deploy has settled. If you are scripting deploy-then-write cycles, insert a +short wait between the two rather than chaining them directly. + +--- From b9079f1363ca472bc01ecb2e144664e1f46f8a7a Mon Sep 17 00:00:00 2001 From: Marc Date: Mon, 20 Jul 2026 20:03:08 -0300 Subject: [PATCH 2/2] docs: hedge the deploy-then-write note, scope the receipt caveat to generic EVM clients --- .../genlayer-js/transactions.md | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/pages/api-references/genlayer-js/transactions.md b/pages/api-references/genlayer-js/transactions.md index 846fac45..4ed59a08 100644 --- a/pages/api-references/genlayer-js/transactions.md +++ b/pages/api-references/genlayer-js/transactions.md @@ -119,20 +119,26 @@ vote vector and `txExecutionResultName` together. `COMMITTING` and `REVEALING` are in-flight. `ACCEPTED`, `FINALIZED`, `UNDETERMINED` and `CANCELED` are decided. A numeric `status` value that has no -name in your SDK version (for example `14`) is a transient state, not an error: -keep polling rather than treating it as a failure. +name in your SDK version (for example `14`) has been observed as a transient +state rather than an error: keep polling rather than treating it as a failure. -### Do not reach for an EVM receipt helper +### A generic EVM receipt helper will not find the transaction -`getTransactionReceipt` from a generic EVM client returns "not found" for -GenLayer transactions. Use `getTransaction`. +`getTransactionReceipt` from a generic EVM client (for example Viem's) returns +"not found" for GenLayer transactions. Use genlayer-js's `getTransaction`. This +note is about the EVM client's method, not about genlayer-js's own +`waitForTransactionReceipt`, which is supported. -### Allow a deploy to settle before calling a write method +### A write fired right after a deploy may revert -Calling a write method immediately after a successful deploy can revert at the -EVM level against the consensus contract, even when the deploy itself returned a -unanimous AGREE. The same call to the same contract address succeeds once the -deploy has settled. If you are scripting deploy-then-write cycles, insert a -short wait between the two rather than chaining them directly. +Calling a write method seconds after a successful deploy can revert at the EVM +level against the consensus contract, even when the deploy itself returned a +unanimous AGREE. We observed this ~2.2s after a deploy, with the identical call +to the identical address succeeding after a wait. + +Treat it as a flake to retry through rather than something a delay reliably +prevents: we have also seen this revert occur with a 25 second post-deploy +delay. The practical point is that a revert here may have nothing to do with +your contract logic, so it is not the first place to look. ---