Skip to content

DXP-346: Explained code snippets for factory, web-to-LLM, and cross-contract read/write - #962

Open
jmlago wants to merge 2 commits into
mainfrom
legatus/dxp-346
Open

jmlago wants to merge 2 commits into
mainfrom
legatus/dxp-346

Conversation

@jmlago

@jmlago jmlago commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Resolves DXP-346.

What changed

  • New page pages/developers/intelligent-contracts/examples/snippets.mdx ("Code Snippets", first entry under Examples). It has four complete contracts, each followed by a "How it works" walkthrough:

    • Factory Pattern: MarketFactory deploys Market children with gl.deploy_contract (deterministic salt_nonce, args, on=) and keeps a registry.
    • Pass Web Content to an LLM: PageClassifier fetches a page, prompts the LLM with response_format="json", and reaches consensus with gl.vm.run_nondet_unsafe and a validator function. The leader rejects malformed or off-list labels with gl.vm.UserError, and the validator rejects off-list leader values. Includes a prompt-injection warning.
    • Read from Another Contract: typed (@gl.contract_interface) and untyped (gl.get_contract_at) .view() calls.
    • Write to Another Contract: .emit(on="finalized" | "accepted"), with notes on why nothing is returned, idempotency, payable calls and sender_address.
  • Fix in features/interacting-with-intelligent-contracts.mdx: the deploy_contract example passed salt=, but the SDK parameter is salt_nonce=. The page now also links to the new snippets page.

  • Regression tests in scripts/test-snippets.py. They extract PageClassifier from the MDX and run it against a mocked genlayer module. Cases: a valid label is stored; {"label": "hacked"} is rejected even when the leader and validators agree; the validator rejects an off-list leader value; malformed responses ({}, a list, null label) are rejected; disagreeing labels are rejected. scripts/lint-code-examples.py runs these tests, so the existing Lint Code Examples CI job covers them.

How it was tested

  • python scripts/test-snippets.py: 5/5 pass. Against the previous version of the snippet, 3 of the 5 fail, including hacked being stored.
  • python scripts/lint-code-examples.py (the CI "Lint Code Examples" job): all checks pass, including the 4 new contracts.
  • genvm-lint check on each new contract against the pinned runner py-genlayer:1jb45aa8…: lint and SDK validation pass. I also checked the deploy_contract, emit and exec_prompt(response_format=...) signatures against that SDK's source.
  • node scripts/generate-full-docs.js, node scripts/check-llm-exports.js, npm run check:protocol-docs: OK.
  • next build compiles and produces /developers/intelligent-contracts/examples/snippets.
  • Playwright tests/docs.e2e.spec.ts for the new page, the edited page and a control page: 3 passed; after the review fix, all 171 passed. These ran locally with a Nix-provided Chromium because the bundled browser can't start on this host.

Assumptions

  • "Snippets" means short, complete, explained example contracts. I put them on a single Code Snippets page, first under Intelligent Contracts → Examples, rather than four separate pages.
  • The snippets use the same pinned runner hash and the same gl.* API names (gl.deploy_contract, gl.get_contract_at) as the rest of the docs, not the newer runner.
  • The factory embeds the child source as a string constant so the snippet works as one file. The explanation mentions the alternatives (a bundled file, or code passed to the constructor).
  • Web→LLM uses a custom validator (run_nondet_unsafe) that compares a constrained label, which follows the Equivalence Principle page's recommendation. It links to the non-comparative approach for free-text output.
  • The snippet tests run from lint-code-examples.py rather than as their own workflow step, because the push token here can't modify .github/workflows. As a result, a PR that changes only scripts/test-snippets.py won't trigger the job. Any change to an MDX page or to lint-code-examples.py will.
  • An off-list LLM answer makes the leader fail the transaction rather than fall back to "other", so bad output is never stored silently.
  • The existing short fragments on the Interacting page stay as they are, apart from the salt_nonce fix and the new link.

🤖 Generated with Claude Code

@netlify

netlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for genlayer-docs ready!

Name Link
🔨 Latest commit 664b134
🔍 Latest deploy log https://app.netlify.com/projects/genlayer-docs/deploys/6afec0b67484979ee4d8f734
😎 Deploy Preview https://deploy-preview-962--genlayer-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 51 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 71d1b83f-164e-42c5-8ada-79a01fa493fb
Commits

Reviewing files that changed from the base of the PR and between cc42620 and 664b134.

Files selected for processing: 5

  • pages/developers/intelligent-contracts/examples/_meta.json
  • pages/developers/intelligent-contracts/examples/snippets.mdx
  • pages/developers/intelligent-contracts/features/interacting-with-intelligent-contracts.mdx
  • scripts/lint-code-examples.py
  • scripts/test-snippets.py
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Changes requested (commit 0c05bd7)

  • P2 — Enforce the classifier’s allowed labels — pages/developers/intelligent-contracts/examples/snippets.mdx:116–122. The code accepts any matching LLM responses, despite claiming output is constrained to four labels. Executing the extracted functions with mocked responses of {"label":"hacked"} returned "hacked" and validator acceptance True. Validate the response structure and label membership before returning it, and reject invalid leader values. Include a regression check for out-of-set labels.

Validation: snippet lint passed; all 171 E2E tests passed in a Playwright container. Worktree removed. Nothing pushed or merged.

LEGATUS-TICKET
team: DXP
title: Docs release checker crashes when Python is unavailable
blocks: no
Running npm run test:e2e without python3 caused scripts/check-v06-release-docs.js:222 to throw TypeError: Cannot read properties of null (reading 'trim'). The script accesses result.stderr.trim() after spawnSync fails to launch Python. Expected an actionable missing-dependency error. Handle result.error and nullable stderr. Supplying Python allowed validation to continue. This file is unchanged by the PR.
LEGATUS-END

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Approved (commit dbb51d3)

No blocking findings. The previous label-validation issue is fixed, with regression coverage for invalid labels, malformed responses, and validator disagreement.

Validation passed: snippet linting, all five regression tests, additional malformed-response checks, and all 171 E2E tests. Audit worktree removed; nothing pushed or merged.

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

/run-e2e all

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Approved (commit dbb51d3)

No blocking findings. The head and diff are unchanged from the previously approved revision.

Fresh validation passed: snippet linting, all five regression tests, and all 171 E2E tests. Worktree removed; nothing pushed or merged.

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

/run-e2e all

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Approved (commit dbb51d3)

No blocking findings. Verified the remote head and full diff are unchanged.

Previous results for this exact commit remain valid: snippet linting, five regression tests, and 171 E2E tests passed. Tests were not rerun this turn. Audit worktree removed; nothing pushed or merged.

@jmlago

jmlago commented Nov 18, 2026

Copy link
Copy Markdown
Member Author

/run-e2e all

@jmlago
jmlago requested a review from danieljrc888 November 18, 2026 22:53
jmlago and others added 2 commits November 19, 2026 09:20
Add a Code Snippets page with complete, explained contracts for the
factory pattern, passing web content to an LLM, and reading from and
writing to another contract. Fix the deploy_contract example that used
salt= instead of salt_nonce=, and link the new page from the
Interacting with Intelligent Contracts page.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The PageClassifier snippet claimed its output was constrained to four
labels but accepted any value on which leader and validators agreed.
The leader now rejects malformed or off-list LLM responses with
gl.vm.UserError, and the validator rejects off-list leader values.

Add scripts/test-snippets.py, which executes the snippet from the MDX
against a mocked genlayer module, with regression cases for off-list,
malformed and disagreeing labels. lint-code-examples.py runs it, so the
existing Lint Code Examples CI job covers it.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@jmlago

jmlago commented Nov 19, 2026

Copy link
Copy Markdown
Member Author

Legatus audit: Approved (commit 664b134)

No blocking findings. The rebase preserves the reviewed snippets and validation fix.

Lint, regression tests, and export tests passed. E2E: 171 passed, one unrelated intermittent failure; all 13 Studio tests passed on retry. Worktree removed; nothing merged.

LEGATUS-TICKET
team: DXP
title: Docs Studio rendering test intermittently fails on compute-pressure console error
blocks: no
At 664b134, npm run test:e2e failed in tests/docs.e2e.spec.ts:34 for /developers/intelligent-contracts/tools/genlayer-studio with “Permissions policy violation: compute-pressure is not allowed in this document.” Expected no console errors. This page and test are unchanged by the PR. Rerunning with --grep genlayer-studio passed all 13 tests; hosted E2E also passed. Investigate the intermittent browser-console failure.
LEGATUS-END

@jmlago

jmlago commented Nov 19, 2026

Copy link
Copy Markdown
Member Author

/run-e2e all

This branch has not been deployed

No deployments
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.

1 participant