-
Notifications
You must be signed in to change notification settings - Fork 24
docs: refresh protocol understanding section #454
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.
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
MuncleUscles
wants to merge
2
commits into
main
Choose a base branch
from
docs/protocol-understanding-refresh
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| name: Check Protocol Documentation | ||
|
|
||
| on: | ||
| pull_request: | ||
| paths: | ||
| - "pages/understand-genlayer-protocol.mdx" | ||
| - "pages/understand-genlayer-protocol/**" | ||
| - "pages/api-references/genlayer-node/gen/gen_getTransactionStatus.mdx" | ||
| - "scripts/check-protocol-docs.js" | ||
| - "PROTOCOL_DOCUMENTATION.md" | ||
| push: | ||
| branches: [main] | ||
| paths: | ||
| - "pages/understand-genlayer-protocol.mdx" | ||
| - "pages/understand-genlayer-protocol/**" | ||
| - "pages/api-references/genlayer-node/gen/gen_getTransactionStatus.mdx" | ||
| - "scripts/check-protocol-docs.js" | ||
| - "PROTOCOL_DOCUMENTATION.md" | ||
|
|
||
| jobs: | ||
| check: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 22 | ||
| - run: node scripts/check-protocol-docs.js | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| # Protocol documentation maintenance | ||
|
|
||
| Use this guide when changing `pages/understand-genlayer-protocol.mdx` or `pages/understand-genlayer-protocol/`. That section explains the protocol to readers; it must not become a second, independently evolving specification or API reference. | ||
|
|
||
| ## Source precedence | ||
|
|
||
| When sources disagree, use this order and resolve the inconsistency before publishing: | ||
|
|
||
| 1. Deployed consensus contracts and the matching contract interfaces define executable state, enums, and transitions. | ||
| 2. The consensus specification explains intended protocol behavior. Verify high-risk details against the implementation. | ||
| 3. GenLayer Node and GenVM code and their repository documentation define component behavior. | ||
| 4. Developer documentation in this repository defines the public SDK and Intelligent Contract APIs. | ||
| 5. Architecture articles and blog posts can supply narrative and motivation, but they are not normative. | ||
|
|
||
| Never copy a deployment default into a timeless rule. Label values such as timeouts, committee limits, minimum stake, weights, rewards, and slash percentages as current defaults or configurable parameters. | ||
|
|
||
| ## Page ownership | ||
|
|
||
| Keep each fact in one primary place and link to it elsewhere. | ||
|
|
||
| | Topic | Primary page type | | ||
| | --- | --- | | ||
| | Architecture, roles, lifecycle, and mental models | Understand GenLayer Protocol | | ||
| | Python APIs, code patterns, and contract restrictions | Intelligent Contract developer guides | | ||
| | SDK methods and frontend code | DApp developer guides and SDK reference | | ||
| | RPC fields, numeric codes, and response schemas | API reference | | ||
| | Node installation and operations | Validator documentation | | ||
|
|
||
| Concept pages can summarize an API, but they should not duplicate long code examples or response payloads. API pages can link back to concepts instead of redefining consensus semantics. | ||
|
|
||
| ## Writing style | ||
|
|
||
| Follow the [Google developer documentation style guide](https://developers.google.com/style) unless GenLayer terminology requires an exception. | ||
|
|
||
| - Put the reader's question or outcome first. | ||
| - Use sentence case for headings. | ||
| - Prefer active voice, present tense, and short paragraphs. | ||
| - Define a term before using its abbreviation. | ||
| - Use **Intelligent Contract**, **GenLayer Chain**, **GenVM**, **Ghost**, and **Optimistic Democracy** consistently. | ||
| - Distinguish `Accepted` from `Finalized` and consensus status from execution result. | ||
| - Use meaningful link text. Link to the canonical page rather than “here.” | ||
| - Give every image useful alternative text. Prefer Mermaid for protocol flows that are likely to change. | ||
| - Separate protocol guarantees from current deployment configuration and future plans. | ||
|
|
||
| ## Review triggers | ||
|
|
||
| Review the affected concept pages when any of these sources change: | ||
|
|
||
| | Source change | Pages to review | | ||
| | --- | --- | | ||
| | `ITransactions.TransactionStatus` or phase contracts | Transaction execution, statuses, appeals, finality | | ||
| | Committee selection or round sizing | Validators, Optimistic Democracy, appeals | | ||
| | Staking, rewards, epochs, or slash contracts | Economic model, staking, slashing, unstaking | | ||
| | GenVM sandbox, runner, or host interface | GenVM, non-deterministic operations, LLM and web pages | | ||
| | Ghost, messages, or account queues | Architecture, accounts, transactions, finality | | ||
| | Node RPC receipt/status schema | Transaction pages and API reference | | ||
|
|
||
| Run `npm run check:protocol-docs` after editing these pages. The check intentionally keeps a local snapshot of the public status enum because CI does not have the sibling consensus repository. Update the snapshot only after verifying the deployed-compatible consensus interface. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,66 @@ | ||
| --- | ||
| description: "Optimistic Democracy consensus in GenLayer: validator selection, recomputation, and AI-driven transaction validation." | ||
| description: "Understand GenLayer architecture, Intelligent Contract execution, Optimistic Democracy, transactions, and protocol economics." | ||
| --- | ||
| ## What is GenLayer? | ||
|
|
||
| GenLayer is the first AI-native blockchain built for AI-powered smart contracts—called Intelligent Contracts—capable of reasoning and adapting to real-world data. Its foundation is the Optimistic Democracy consensus mechanism, an enhanced Delegated Proof of Stake (dPoS) model where validators connect directly to Large Language Models (LLMs). This setup allows for non-deterministic operations—such as processing text prompts, fetching live web data, and executing AI-based decision-making—while preserving the reliability and security of a traditional blockchain. | ||
| import { Card, Cards } from "nextra-theme-docs"; | ||
|
|
||
| ## Core Technology | ||
| # Discover the GenLayer protocol | ||
|
|
||
| GenLayer is an intelligent blockchain for applications that need consensus on outcomes derived from natural language, live web data, or other non-deterministic inputs. | ||
|
|
||
| At the heart of GenLayer lies Optimistic Democracy—an enhanced Delegated Proof of Stake (dPoS) consensus mechanism that integrates AI models directly into validator operations. This synergy delivers three capabilities traditional blockchains cannot match: | ||
| Intelligent Contracts divide execution into deterministic code and isolated non-deterministic operations. A selected leader proposes an execution result, a validator committee evaluates it under the contract's equivalence rule, and the onchain consensus system coordinates appeals and finality. | ||
|
|
||
| 1. **On-Chain AI Processing** | ||
| ## Start here | ||
|
|
||
| Validators connect to leading AI models (GPT, LLaMA, Meta, etc.) to execute complex reasoning on-chain, from natural language comprehension to data-driven predictions. | ||
| <Cards> | ||
| <Card title="What is GenLayer?" href="/understand-genlayer-protocol/what-is-genlayer" /> | ||
| <Card title="How GenLayer works" href="/understand-genlayer-protocol/optimistic-democracy-how-genlayer-works" /> | ||
| <Card title="Use cases" href="/understand-genlayer-protocol/typical-use-cases" /> | ||
| <Card title="Core concepts" href="/understand-genlayer-protocol/core-concepts" /> | ||
| </Cards> | ||
|
|
||
| 2. **Consensus-Backed Security** | ||
| ## Architecture at a glance | ||
|
|
||
| Multiple validators vote on outcomes, ensuring collective agreement and robust reliability for every transaction—even those involving non-deterministic AI outputs. | ||
| ```mermaid | ||
| %%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 44, "rankSpacing": 54, "htmlLabels": true}}}%% | ||
| flowchart TB | ||
| App(["Application"]) | ||
| Chain["GenLayer Chain<br/>orders and coordinates"] | ||
| Worker["Validator node<br/>performs assigned duty"] | ||
| VM["GenVM<br/>executes or validates"] | ||
| Action["Signed proposal or vote"] | ||
| State(["Updated onchain state"]) | ||
|
|
||
| 3. **Intelligent Contracts** | ||
| App -->|"1 · submit transaction"| Chain | ||
| Chain -->|"2 · publish assignment"| Worker | ||
| Worker -->|"3 · run contract"| VM | ||
| VM -->|"4 · return result"| Action | ||
| Action -->|"5 · record consensus action"| State | ||
|
|
||
| Smart contracts in GenLayer gain reasoning abilities, allowing them to understand natural language, process real-world data, and adapt to evolving conditions. | ||
| classDef actor fill:#F7F8FC,stroke:#8B95A7,color:#202536,stroke-width:1.5px; | ||
| classDef chain fill:#EFEDFF,stroke:#6D5DF5,color:#251E63,stroke-width:2px; | ||
| classDef compute fill:#EAF7FF,stroke:#2686C4,color:#113F59,stroke-width:2px; | ||
| class App actor; | ||
| class Chain,Action,State chain; | ||
| class Worker,VM compute; | ||
| linkStyle default stroke:#7C879C,stroke-width:1.8px; | ||
| ``` | ||
|
|
||
| ## Technical Implementation | ||
| - **GenLayer Chain** orders actions and stores the authoritative consensus state. | ||
| - **Validator nodes** watch the chain, maintain derived Intelligent Contract state, and perform assigned consensus duties. | ||
| - **GenVM** runs Intelligent Contracts in a WebAssembly sandbox and isolates web and LLM operations. | ||
|
|
||
| To integrate AI seamlessly with the blockchain, GenLayer employs a distributed neural consensus network, wherein validators run specialized software connected via API to advanced AI models. This approach unifies: | ||
| Each Intelligent Contract has an EVM-facing Ghost contract at the same address. The Ghost routes calls and messages between GenLayer Chain and GenVM. | ||
|
|
||
| - Delegated Proof of Stake (dPoS) for efficient block production and governance. | ||
| - Neural Consensus for non-deterministic transactions requiring advanced AI reasoning. | ||
| ## Explore by topic | ||
|
|
||
| This architecture supports autonomous DAOs, self-executing prediction markets, and dynamic DeFi protocols that react to real-world data in real time. | ||
| <Cards> | ||
| <Card title="Architecture and GenVM" href="/understand-genlayer-protocol/core-concepts/rollup-integration" /> | ||
| <Card title="Non-deterministic operations" href="/understand-genlayer-protocol/core-concepts/non-deterministic-operations-handling" /> | ||
| <Card title="Optimistic Democracy" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy" /> | ||
| <Card title="Equivalence Principle" href="/understand-genlayer-protocol/core-concepts/optimistic-democracy/equivalence-principle" /> | ||
| <Card title="Transactions and finality" href="/understand-genlayer-protocol/core-concepts/transactions" /> | ||
| <Card title="Protocol economics" href="/understand-genlayer-protocol/core-concepts/economic-model" /> | ||
| </Cards> | ||
|
|
||
| # Optimistic Democracy: How Consensus Works | ||
|
|
||
| Optimistic Democracy is GenLayer's consensus mechanism for merging probabilistic AI systems with deterministic blockchain rules so the network can reach secure and accurate consensus at scale. Inspired by **[Condorcet's Jury Theorem](https://jury-theorem.genlayer.com/)** (click the link to check out our interactive model), the process uses validator recomputation and majority agreement as a safety net for AI-driven computations. | ||
|
|
||
| <img src="/studio/Diagram MAIN.jpg" alt="GenLayer Optimistic Democracy Consensus Diagram" width="100%" /> | ||
|
|
||
| 1. **User Submits a Transaction** | ||
| A user sends a transaction request to the network (see the diagram's Step 1). | ||
|
|
||
| 2. **Leader (Validator) Proposes Result** | ||
| The network selects a Leader, who processes the request and proposes an outcome (Step 2). | ||
|
|
||
| 3. **Validators Recompute** | ||
| A group of Validators independently re-compute the transaction (Step 3). If the output aligns with the Leader's proposal, they approve; otherwise, they deny. | ||
|
|
||
| ## Validator Selection Mechanism | ||
| Token holders bolster network security by delegating tokens to validator candidates. A deterministic function f(x) then randomly designates Leader-Validator and Validators for each transaction. This process promotes fairness, helps decentralize validation power, and strengthens GenLayer's security and trustlessness. | ||
|
|
||
| ## Validator Operational Framework | ||
| Each GenLayer validator node integrates: | ||
|
|
||
| - **Validator Software** | ||
| Handles core blockchain functions: networking, block production, and transaction management. | ||
|
|
||
| - **AI Model Integration** | ||
| Connects to Large Language Models (LLMs) or other AI services for complex reasoning, natural language processing, and real-time data retrieval. | ||
|
|
||
| Validators seamlessly manage both: | ||
|
|
||
| 1. **Deterministic Transactions** typical of traditional blockchains. | ||
| 2. **Non-Deterministic Transactions** that leverage AI-driven logic (e.g., searching the internet, analyzing data, making probabilistic inferences). | ||
|
|
||
| By splitting tasks between standard deterministic transactions and advanced AI-powered transactions, GenLayer ensures high performance without compromising on security. | ||
|
|
||
| ## Putting It All Together | ||
| With Optimistic Democracy guiding consensus and validators empowered by AI, GenLayer enables a new class of blockchain applications. From DAOs that self-govern based on real-time data to DeFi protocols that dynamically adjust parameters in response to market changes, developers can now build truly intelligent decentralized solutions. | ||
| For the extended architectural rationale, read [Making GenLayer 100% Secure, Part 1: The Architecture](https://genlayer.com/blog/making-genlayer-100-percent-secure-part-1-the-architecture). |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not persist checkout credentials in this job.
This job executes change-controlled repository code.
actions/checkoutcan retain its token in local Git configuration. Restrict the token to read-only repository content and remove persisted credentials before the script runs.Proposed fix
📝 Committable suggestion
🧰 Tools
🪛 zizmor (1.29.0)
[warning] 24-24: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
🤖 Prompt for AI Agents
Source: Linters/SAST tools