From 5bbd7aab4d5724a613541ec3f7bf17f308ea2837 Mon Sep 17 00:00:00 2001 From: Edgars Date: Tue, 27 Jan 2026 16:37:55 +0000 Subject: [PATCH 1/3] docs: add GenLayer Linter API reference - Add /api-references/genlayer-linter.mdx with full CLI reference - Update tooling-setup.mdx to mention linter as recommended dev tool - Add linter to _meta.json navigation --- pages/api-references/_meta.json | 1 + pages/api-references/genlayer-linter.mdx | 237 ++++++++++++++++++ .../intelligent-contracts/tooling-setup.mdx | 24 +- 3 files changed, 261 insertions(+), 1 deletion(-) create mode 100644 pages/api-references/genlayer-linter.mdx diff --git a/pages/api-references/_meta.json b/pages/api-references/_meta.json index 90fe8c5fc..5f382a53d 100644 --- a/pages/api-references/_meta.json +++ b/pages/api-references/_meta.json @@ -3,6 +3,7 @@ "genlayer-js": "GenLayerJS", "genlayer-py": "GenLayerPY", "genlayer-test": "GenLayer Test", + "genlayer-linter": "GenLayer Linter", "genlayer-node": "GenLayer Node API", "genlayer-sdk": { "title": "GenLayer SDK", diff --git a/pages/api-references/genlayer-linter.mdx b/pages/api-references/genlayer-linter.mdx new file mode 100644 index 000000000..646e1a535 --- /dev/null +++ b/pages/api-references/genlayer-linter.mdx @@ -0,0 +1,237 @@ +# GenLayer Linter Reference + +The GenLayer Linter (`genvm-linter`) is a command-line tool for validating Intelligent Contracts and extracting ABI schemas. It performs static analysis to catch common errors before deployment. + +## Installation + +```bash +pip install genvm-linter +``` + +## Command Line Syntax + +```bash +genvm-lint [options] +``` + +## Commands + +### check + +The default validation workflow that runs both lint and validate checks. + +```bash +USAGE: + genvm-lint check [options] + +OPTIONS: + --json Output results in JSON format + +EXAMPLES: + genvm-lint check my_contract.py + genvm-lint check my_contract.py --json +``` + +### lint + +Fast AST-based static analysis (~50ms). Checks for common issues without requiring the GenLayer SDK. + +```bash +USAGE: + genvm-lint lint [options] + +OPTIONS: + --json Output results in JSON format + +EXAMPLES: + genvm-lint lint my_contract.py + genvm-lint lint my_contract.py --json +``` + +**Checks performed:** +- Forbidden imports (`random`, `os`, `sys`, `subprocess`, etc.) +- Non-deterministic patterns (float usage) +- Contract header structure + +### validate + +Semantic validation using the GenLayer SDK (~200ms). Requires downloading GenVM artifacts. + +```bash +USAGE: + genvm-lint validate [options] + +OPTIONS: + --json Output results in JSON format + +EXAMPLES: + genvm-lint validate my_contract.py + genvm-lint validate my_contract.py --json +``` + +**Validates:** +- Types exist in SDK +- Decorators correctly applied +- Storage fields have valid types +- Method signatures correct + +### schema + +Extract the ABI schema from an Intelligent Contract. + +```bash +USAGE: + genvm-lint schema [options] + +OPTIONS: + --json Output results in JSON format + --output Write schema to file + +EXAMPLES: + genvm-lint schema my_contract.py + genvm-lint schema my_contract.py --json + genvm-lint schema my_contract.py --output abi.json +``` + +### download + +Pre-download GenVM artifacts for offline validation. + +```bash +USAGE: + genvm-lint download [options] + +OPTIONS: + --version Download a specific version + --list Show cached versions + +EXAMPLES: + genvm-lint download # Download latest + genvm-lint download --version v0.2.12 # Download specific version + genvm-lint download --list # Show cached versions +``` + +## Output Formats + +### Human-readable (default) + +``` +✓ Lint passed (3 checks) +✓ Validation passed + Contract: MyContract + Methods: 26 (16 view, 10 write) +``` + +### JSON (--json flag) + +```json +{ + "ok": true, + "lint": { + "ok": true, + "passed": 3 + }, + "validate": { + "ok": true, + "contract": "MyContract", + "methods": 26, + "view_methods": 16, + "write_methods": 10, + "ctor_params": 5 + } +} +``` + +### Error Output (JSON) + +When validation fails: + +```json +{ + "ok": false, + "lint": { + "ok": false, + "errors": [ + { + "code": "E001", + "message": "Forbidden import: random", + "line": 3 + } + ] + } +} +``` + +## Exit Codes + +| Code | Description | +|------|-------------| +| `0` | All checks passed | +| `1` | Lint or validation errors | +| `2` | Contract file not found | +| `3` | SDK download failed | + +## Common Lint Errors + +### Forbidden Imports + +The following modules are forbidden in Intelligent Contracts as they introduce non-determinism: + +- `random` - Use `gl.random` instead +- `os`, `sys`, `subprocess` - System access not allowed +- `socket`, `urllib`, `requests` - Use `gl.get_webpage()` instead +- `time`, `datetime` - Use `gl.block_timestamp` instead + +### Non-deterministic Patterns + +- **Float usage**: Floating-point arithmetic can produce different results across validators. Use `Decimal` or integer math. +- **Dictionary iteration**: In Python < 3.7, dict ordering was non-deterministic. Use `sorted()` when iterating. + +## Integration Examples + +### CI/CD Pipeline + +```yaml +# GitHub Actions example +- name: Validate contracts + run: | + pip install genvm-linter + genvm-lint check contracts/*.py --json +``` + +### Pre-commit Hook + +```yaml +# .pre-commit-config.yaml +repos: + - repo: local + hooks: + - id: genvm-lint + name: GenVM Linter + entry: genvm-lint check + language: python + files: \.py$ + additional_dependencies: ['genvm-linter'] +``` + +### Programmatic Usage + +```python +import subprocess +import json + +result = subprocess.run( + ['genvm-lint', 'check', 'my_contract.py', '--json'], + capture_output=True, + text=True +) + +validation = json.loads(result.stdout) +if not validation['ok']: + print("Validation failed:", validation) +``` + +## Related Tools + +- [GenLayer Test](/api-references/genlayer-test) - Testing framework for Intelligent Contracts +- [GenLayer CLI](/api-references/genlayer-cli) - CLI for deploying and managing contracts diff --git a/pages/developers/intelligent-contracts/tooling-setup.mdx b/pages/developers/intelligent-contracts/tooling-setup.mdx index 98e8def2c..1de2ef5ef 100644 --- a/pages/developers/intelligent-contracts/tooling-setup.mdx +++ b/pages/developers/intelligent-contracts/tooling-setup.mdx @@ -51,7 +51,29 @@ Ensure you have the following installed and updated: npm install -g genlayer ``` -2. **Initialize GenLayer Environment** +2. **Install GenLayer Linter (Recommended)** + + The GenLayer Linter validates your contracts before deployment, catching common errors early: + + ```bash + pip install genvm-linter + ``` + + Run validation on your contracts: + + ```bash + genvm-lint check my_contract.py + ``` + + The linter checks for: + - Forbidden imports (`random`, `os`, `sys`, etc.) + - Non-deterministic patterns + - SDK type validation + - Method signature correctness + + See the [GenLayer Linter Reference](/api-references/genlayer-linter) for full documentation. + +3. **Initialize GenLayer Environment** Run the following command to set up your development environment: From ae506f538c2918768fe03d467fcb4d1c37f821fc Mon Sep 17 00:00:00 2001 From: Edgars Date: Tue, 27 Jan 2026 17:58:44 +0000 Subject: [PATCH 2/3] docs: add VS Code extension to tooling setup --- .../intelligent-contracts/tooling-setup.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/pages/developers/intelligent-contracts/tooling-setup.mdx b/pages/developers/intelligent-contracts/tooling-setup.mdx index 1de2ef5ef..533f68249 100644 --- a/pages/developers/intelligent-contracts/tooling-setup.mdx +++ b/pages/developers/intelligent-contracts/tooling-setup.mdx @@ -73,7 +73,20 @@ Ensure you have the following installed and updated: See the [GenLayer Linter Reference](/api-references/genlayer-linter) for full documentation. -3. **Initialize GenLayer Environment** +3. **Install VS Code Extension (Recommended)** + + The GenLayer VS Code extension provides syntax highlighting, snippets, and real-time linting for intelligent contracts: + + - Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=genlayer-labs.genlayer) + - Or search "GenLayer" in VS Code Extensions + + Features: + - Syntax highlighting for `.gpy` files + - Code snippets for common patterns + - Real-time error detection + - Integrated linting + +4. **Initialize GenLayer Environment** Run the following command to set up your development environment: From fc3dd1967357bed33371414be83f2c3199cb600c Mon Sep 17 00:00:00 2001 From: Edgars Date: Tue, 27 Jan 2026 18:05:49 +0000 Subject: [PATCH 3/3] docs: fix VS Code extension description --- pages/developers/intelligent-contracts/tooling-setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/developers/intelligent-contracts/tooling-setup.mdx b/pages/developers/intelligent-contracts/tooling-setup.mdx index 533f68249..6e87fb8f1 100644 --- a/pages/developers/intelligent-contracts/tooling-setup.mdx +++ b/pages/developers/intelligent-contracts/tooling-setup.mdx @@ -81,7 +81,7 @@ Ensure you have the following installed and updated: - Or search "GenLayer" in VS Code Extensions Features: - - Syntax highlighting for `.gpy` files + - Auto-detects GenLayer contracts by header - Code snippets for common patterns - Real-time error detection - Integrated linting