Skip to content

docs(genlayer-js): document where consensus results live on a transaction #445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
theboyplunger0x wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(genlayer-js): document where consensus results live on a transaction #445

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b146808
docs(genlayer-js): document where consensus results live on a transac…
theboyplunger0x Jul 20, 2026
b9079f1
docs: hedge the deploy-then-write note, scope the receipt caveat to g…
theboyplunger0x Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions pages/api-references/genlayer-js/transactions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,3 +94,51 @@ 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`) has been observed as a transient
state rather than an error: keep polling rather than treating it as a failure.

### A generic EVM receipt helper will not find the transaction

`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.
Comment on lines +125 to +130

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Avoid stating the receipt limitation unconditionally.

The PR objective scopes this behavior to generic EVM clients potentially returning "not found". Change “will not find” and “returns” to “may not find” and “may return”; keep waitForTransactionReceipt as the preferred supported helper.

Proposed wording 
-### A generic EVM receipt helper will not find the transaction
+### A generic EVM receipt helper may not find the transaction
...
-returns
+may return
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### A generic EVM receipt helper will not find the transaction
`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.
### A generic EVM receipt helper may not find the transaction
`getTransactionReceipt` from a generic EVM client (for example Viem's) may return
"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.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pages/api-references/genlayer-js/transactions.md` around lines 125 - 130,
Update the “A generic EVM receipt helper will not find the transaction” note to
use conditional wording: generic EVM clients may not find GenLayer transactions
and may return “not found.” Preserve the distinction that this applies to the
EVM client’s getTransactionReceipt, while genlayer-js’s
waitForTransactionReceipt remains the preferred supported helper.


### A write fired right after a deploy may revert

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

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Hyphenate “25-second.”

Use “a 25-second post-deploy delay” for correct compound-adjective grammar.

🧰 Tools
🪛 LanguageTool

[grammar] ~140-~140: Use a hyphen to join words.
Context: ...ve also seen this revert occur with a 25 second post-deploy delay. The practical ...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pages/api-references/genlayer-js/transactions.md` at line 140, Update the
sentence near “prevents” to hyphenate “25-second” when it modifies
“post-deploy,” using the phrasing “a 25-second post-deploy delay” while
preserving the existing meaning.

Source: Linters/SAST tools

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.

---