diff --git a/docs/build/api/_category_.json b/docs/build/api/_category_.json new file mode 100644 index 0000000..69cc463 --- /dev/null +++ b/docs/build/api/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "API", + "position": 3, + "link": { + "type": "generated-index" + }, + "collapsible": false, + "collapsed": false +} diff --git a/docs/build/api/contracts/_category_.json b/docs/build/api/contracts/_category_.json new file mode 100644 index 0000000..7cb0321 --- /dev/null +++ b/docs/build/api/contracts/_category_.json @@ -0,0 +1,10 @@ +{ + "label": "Contracts", + "position": 1, + "link": { + "type": "doc", + "id": "build/api/contracts/index" + }, + "collapsible": false, + "collapsed": false +} diff --git a/docs/contracts/api-reference/_category_.json b/docs/build/api/contracts/api-reference/_category_.json similarity index 100% rename from docs/contracts/api-reference/_category_.json rename to docs/build/api/contracts/api-reference/_category_.json diff --git a/docs/contracts/api-reference/app-registry.md b/docs/build/api/contracts/api-reference/app-registry.md similarity index 98% rename from docs/contracts/api-reference/app-registry.md rename to docs/build/api/contracts/api-reference/app-registry.md index d50ed36..a8d6abc 100644 --- a/docs/contracts/api-reference/app-registry.md +++ b/docs/build/api/contracts/api-reference/app-registry.md @@ -2,7 +2,7 @@ title: "AppRegistry" description: "App builder registry with slashing." sidebar_position: 4 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # AppRegistry diff --git a/docs/contracts/api-reference/faucet.md b/docs/build/api/contracts/api-reference/faucet.md similarity index 98% rename from docs/contracts/api-reference/faucet.md rename to docs/build/api/contracts/api-reference/faucet.md index eb4b4b3..4cc46a4 100644 --- a/docs/contracts/api-reference/faucet.md +++ b/docs/build/api/contracts/api-reference/faucet.md @@ -2,7 +2,7 @@ title: "Faucet" description: "Testnet token faucet." sidebar_position: 7 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Faucet diff --git a/docs/contracts/api-reference/interfaces/_category_.json b/docs/build/api/contracts/api-reference/interfaces/_category_.json similarity index 100% rename from docs/contracts/api-reference/interfaces/_category_.json rename to docs/build/api/contracts/api-reference/interfaces/_category_.json diff --git a/docs/contracts/api-reference/interfaces/ilock.md b/docs/build/api/contracts/api-reference/interfaces/ilock.md similarity index 99% rename from docs/contracts/api-reference/interfaces/ilock.md rename to docs/build/api/contracts/api-reference/interfaces/ilock.md index 5cc6ea4..0277883 100644 --- a/docs/contracts/api-reference/interfaces/ilock.md +++ b/docs/build/api/contracts/api-reference/interfaces/ilock.md @@ -2,7 +2,7 @@ title: "ILock" description: "Lock/unlock/withdraw interface." sidebar_position: 1 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # ILock diff --git a/docs/contracts/api-reference/interfaces/islash.md b/docs/build/api/contracts/api-reference/interfaces/islash.md similarity index 97% rename from docs/contracts/api-reference/interfaces/islash.md rename to docs/build/api/contracts/api-reference/interfaces/islash.md index ff4b6ed..a0f6a26 100644 --- a/docs/contracts/api-reference/interfaces/islash.md +++ b/docs/build/api/contracts/api-reference/interfaces/islash.md @@ -2,7 +2,7 @@ title: "ISlash" description: "Slashing interface." sidebar_position: 2 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # ISlash diff --git a/docs/contracts/api-reference/locker.md b/docs/build/api/contracts/api-reference/locker.md similarity index 98% rename from docs/contracts/api-reference/locker.md rename to docs/build/api/contracts/api-reference/locker.md index 586883c..65245f3 100644 --- a/docs/contracts/api-reference/locker.md +++ b/docs/build/api/contracts/api-reference/locker.md @@ -2,7 +2,7 @@ title: "Locker" description: "Abstract lock/unlock/withdraw state machine." sidebar_position: 2 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Locker diff --git a/docs/contracts/api-reference/node-registry.md b/docs/build/api/contracts/api-reference/node-registry.md similarity index 97% rename from docs/contracts/api-reference/node-registry.md rename to docs/build/api/contracts/api-reference/node-registry.md index fe94345..987498b 100644 --- a/docs/contracts/api-reference/node-registry.md +++ b/docs/build/api/contracts/api-reference/node-registry.md @@ -2,7 +2,7 @@ title: "NodeRegistry" description: "Node operator registry with voting power." sidebar_position: 3 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # NodeRegistry diff --git a/docs/contracts/api-reference/treasury.md b/docs/build/api/contracts/api-reference/treasury.md similarity index 97% rename from docs/contracts/api-reference/treasury.md rename to docs/build/api/contracts/api-reference/treasury.md index 3411c4e..1440a2a 100644 --- a/docs/contracts/api-reference/treasury.md +++ b/docs/build/api/contracts/api-reference/treasury.md @@ -2,7 +2,7 @@ title: "Treasury" description: "Secure vault for Foundation assets." sidebar_position: 6 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Treasury diff --git a/docs/contracts/api-reference/yellow-governor.md b/docs/build/api/contracts/api-reference/yellow-governor.md similarity index 99% rename from docs/contracts/api-reference/yellow-governor.md rename to docs/build/api/contracts/api-reference/yellow-governor.md index b7dc230..87cb0da 100644 --- a/docs/contracts/api-reference/yellow-governor.md +++ b/docs/build/api/contracts/api-reference/yellow-governor.md @@ -2,7 +2,7 @@ title: "YellowGovernor" description: "OpenZeppelin Governor for protocol parameters." sidebar_position: 5 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # YellowGovernor diff --git a/docs/contracts/api-reference/yellow-token.md b/docs/build/api/contracts/api-reference/yellow-token.md similarity index 95% rename from docs/contracts/api-reference/yellow-token.md rename to docs/build/api/contracts/api-reference/yellow-token.md index 4b2e46a..902c55f 100644 --- a/docs/contracts/api-reference/yellow-token.md +++ b/docs/build/api/contracts/api-reference/yellow-token.md @@ -2,7 +2,7 @@ title: "YellowToken" description: "ERC-20 token with fixed 10B supply." sidebar_position: 1 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # YellowToken diff --git a/docs/contracts/faq.md b/docs/build/api/contracts/faq.md similarity index 99% rename from docs/contracts/faq.md rename to docs/build/api/contracts/faq.md index 5a78b69..c442169 100644 --- a/docs/contracts/faq.md +++ b/docs/build/api/contracts/faq.md @@ -2,7 +2,7 @@ title: "FAQ" description: "Frequently asked questions about Yellow Network smart contracts." sidebar_position: 7 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Frequently Asked Questions diff --git a/docs/contracts/addresses.md b/docs/build/api/contracts/index.md similarity index 95% rename from docs/contracts/addresses.md rename to docs/build/api/contracts/index.md index b205a36..f79bcc9 100644 --- a/docs/contracts/addresses.md +++ b/docs/build/api/contracts/index.md @@ -1,8 +1,8 @@ --- title: "Deployed Addresses" description: "Mainnet and testnet contract addresses for Yellow Network." -sidebar_position: 2 -displayed_sidebar: contractsSidebar +sidebar_position: 1 +displayed_sidebar: buildSidebar --- # Deployed Addresses diff --git a/docs/contracts/integration/_category_.json b/docs/build/api/contracts/integration/_category_.json similarity index 100% rename from docs/contracts/integration/_category_.json rename to docs/build/api/contracts/integration/_category_.json diff --git a/docs/contracts/integration/deployment.md b/docs/build/api/contracts/integration/deployment.md similarity index 98% rename from docs/contracts/integration/deployment.md rename to docs/build/api/contracts/integration/deployment.md index 560ae51..eb32485 100644 --- a/docs/contracts/integration/deployment.md +++ b/docs/build/api/contracts/integration/deployment.md @@ -2,7 +2,7 @@ title: "Deployment" description: "Deploying contracts and configuration." sidebar_position: 1 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Deployment diff --git a/docs/contracts/integration/events.md b/docs/build/api/contracts/integration/events.md similarity index 99% rename from docs/contracts/integration/events.md rename to docs/build/api/contracts/integration/events.md index 1c62073..70bfcc4 100644 --- a/docs/contracts/integration/events.md +++ b/docs/build/api/contracts/integration/events.md @@ -2,7 +2,7 @@ title: "Events" description: "Contract events for real-time subscriptions." sidebar_position: 2 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Events diff --git a/docs/contracts/integration/ui-spec.md b/docs/build/api/contracts/integration/ui-spec.md similarity index 98% rename from docs/contracts/integration/ui-spec.md rename to docs/build/api/contracts/integration/ui-spec.md index 3acf506..20140f8 100644 --- a/docs/contracts/integration/ui-spec.md +++ b/docs/build/api/contracts/integration/ui-spec.md @@ -2,7 +2,7 @@ title: "UI Specification" description: "Frontend implementation guide." sidebar_position: 3 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # UI Specification diff --git a/docs/contracts/protocol/_category_.json b/docs/build/api/contracts/protocol/_category_.json similarity index 100% rename from docs/contracts/protocol/_category_.json rename to docs/build/api/contracts/protocol/_category_.json diff --git a/docs/contracts/protocol/governance.md b/docs/build/api/contracts/protocol/governance.md similarity index 99% rename from docs/contracts/protocol/governance.md rename to docs/build/api/contracts/protocol/governance.md index bf65e76..944fa07 100644 --- a/docs/contracts/protocol/governance.md +++ b/docs/build/api/contracts/protocol/governance.md @@ -2,7 +2,7 @@ title: "Governance" description: "On-chain parameter administration via YellowGovernor." sidebar_position: 2 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Protocol Parameter Administration diff --git a/docs/contracts/protocol/overview.md b/docs/build/api/contracts/protocol/overview.md similarity index 99% rename from docs/contracts/protocol/overview.md rename to docs/build/api/contracts/protocol/overview.md index 5dd9466..d3ee258 100644 --- a/docs/contracts/protocol/overview.md +++ b/docs/build/api/contracts/protocol/overview.md @@ -2,7 +2,7 @@ title: "Protocol Overview" description: "Architecture, contracts, and how they fit together." sidebar_position: 1 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Protocol Overview diff --git a/docs/contracts/protocol/slashing.md b/docs/build/api/contracts/protocol/slashing.md similarity index 98% rename from docs/contracts/protocol/slashing.md rename to docs/build/api/contracts/protocol/slashing.md index 394e729..0f88eaf 100644 --- a/docs/contracts/protocol/slashing.md +++ b/docs/build/api/contracts/protocol/slashing.md @@ -2,7 +2,7 @@ title: "Slashing" description: "Adjudicator slashing and cooldown mechanism." sidebar_position: 4 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Slashing diff --git a/docs/contracts/protocol/staking.md b/docs/build/api/contracts/protocol/staking.md similarity index 99% rename from docs/contracts/protocol/staking.md rename to docs/build/api/contracts/protocol/staking.md index f448f84..0049c71 100644 --- a/docs/contracts/protocol/staking.md +++ b/docs/build/api/contracts/protocol/staking.md @@ -2,7 +2,7 @@ title: "Collateral & Staking" description: "Lock/unlock state machine for NodeRegistry and AppRegistry." sidebar_position: 3 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Collateral diff --git a/docs/contracts/protocol/treasury.md b/docs/build/api/contracts/protocol/treasury.md similarity index 98% rename from docs/contracts/protocol/treasury.md rename to docs/build/api/contracts/protocol/treasury.md index 3558c0d..add28c0 100644 --- a/docs/contracts/protocol/treasury.md +++ b/docs/build/api/contracts/protocol/treasury.md @@ -2,7 +2,7 @@ title: "Treasury" description: "Foundation asset management." sidebar_position: 5 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # Treasury diff --git a/docs/contracts/sdk/_category_.json b/docs/build/api/contracts/sdk/_category_.json similarity index 83% rename from docs/contracts/sdk/_category_.json rename to docs/build/api/contracts/sdk/_category_.json index 6ea8e3e..3ece79c 100644 --- a/docs/contracts/sdk/_category_.json +++ b/docs/build/api/contracts/sdk/_category_.json @@ -1,6 +1,7 @@ { "label": "SDK", "position": 5, + "key": "contracts-sdk", "link": { "type": "generated-index" }, diff --git a/docs/contracts/sdk/api-reference.md b/docs/build/api/contracts/sdk/api-reference.md similarity index 95% rename from docs/contracts/sdk/api-reference.md rename to docs/build/api/contracts/sdk/api-reference.md index bdbd042..1be2702 100644 --- a/docs/contracts/sdk/api-reference.md +++ b/docs/build/api/contracts/sdk/api-reference.md @@ -2,7 +2,7 @@ title: "SDK API Reference" description: "All exports: ABIs, addresses, and types." sidebar_position: 2 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # SDK — API Reference @@ -86,4 +86,4 @@ type ContractAddresses = { ### Current Addresses -See [Deployed Addresses](../operations/addresses.md) for the full list. +See [Deployed Addresses](../index.md) for the full list. diff --git a/docs/contracts/sdk/examples.md b/docs/build/api/contracts/sdk/examples.md similarity index 99% rename from docs/contracts/sdk/examples.md rename to docs/build/api/contracts/sdk/examples.md index b00d999..c338051 100644 --- a/docs/contracts/sdk/examples.md +++ b/docs/build/api/contracts/sdk/examples.md @@ -2,7 +2,7 @@ title: "Examples" description: "Code samples for viem, ethers.js, and wagmi." sidebar_position: 3 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # SDK — Examples diff --git a/docs/contracts/sdk/getting-started.md b/docs/build/api/contracts/sdk/getting-started.md similarity index 98% rename from docs/contracts/sdk/getting-started.md rename to docs/build/api/contracts/sdk/getting-started.md index c49e6d1..8f5e48f 100644 --- a/docs/contracts/sdk/getting-started.md +++ b/docs/build/api/contracts/sdk/getting-started.md @@ -2,7 +2,7 @@ title: "Getting Started" description: "Install, import, and use the contracts SDK." sidebar_position: 1 -displayed_sidebar: contractsSidebar +displayed_sidebar: buildSidebar --- # SDK — Getting Started diff --git a/docs/build/quick-start/index.md b/docs/build/quick-start/index.md index d397f78..75cad82 100644 --- a/docs/build/quick-start/index.md +++ b/docs/build/quick-start/index.md @@ -347,7 +347,7 @@ await app.sendPayment('100000', '0xPartnerAddress'); // Send 0.1 USDC Congratulations! You've built your first Yellow App. Here's what to explore next: -- **[Advanced Topics](../../learn/advanced/architecture)**: Learn about architecture, multi-party applications, and production deployment +- **[Advanced Topics](../../learn/introduction/architecture-at-a-glance)**: Learn about architecture, multi-party applications, and production deployment - **[API Reference](../../api-reference)**: Explore all available SDK methods and options ## Need Help? diff --git a/docs/contracts/index.md b/docs/contracts/index.md deleted file mode 100644 index b3602af..0000000 --- a/docs/contracts/index.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -title: "Smart Contracts" -description: "Overview of Yellow Network smart contracts, governance, and on-chain infrastructure." -sidebar_position: 1 -displayed_sidebar: contractsSidebar ---- - -# What Is Yellow Network? - -A plain-language guide to Yellow Network, the YELLOW token, and how the system works. - ---- - -## The Problem - -Today's crypto ecosystem is fragmented. Assets live on dozens of separate blockchains — Ethereum, Arbitrum, Base, Polygon, BNB Chain, Linea, and more. If you want to move value between them, you typically rely on bridges (slow, often hacked) or centralised exchanges (single points of failure). Developers building apps face the same issue: they have to pick one chain and lose access to users and liquidity on every other chain. - -There is no shared infrastructure that lets brokers, exchanges, and applications transact across all of these networks in real time — the way internet service providers share a common routing layer to move data. - -## The Solution - -Yellow Network is that shared infrastructure. It is a **clearing and settlement layer** that sits on top of existing blockchains (a "Layer 3") and lets participants move digital assets across multiple chains through a single, unified system — without trusting a central intermediary. - -Think of it like the interbank clearing system (SWIFT, ACH) but for crypto: independent operators run the network, transactions clear in sub-second time off-chain, and final settlement is anchored to the security of public blockchains. - -All of the software, tools, and services that make up Yellow Network are developed, maintained, and supplied by **Layer3 Fintech Ltd.** - ---- - -## How It Works — The Three Layers - -Yellow Network has a three-layer architecture. Each layer has a distinct role: - -### Layer 1 — The Blockchain Foundation - -This is the base: public blockchains like Ethereum, Base, Arbitrum, Linea, BNB Chain, and Polygon. Yellow deploys smart contracts on each of these chains to handle: - -- **Asset custody** — when you deposit assets into Yellow Network, they are held in audited smart contracts on the blockchain, not by a company or individual. -- **Node registration** — node operators register on-chain by posting YELLOW tokens as a security deposit. -- **Dispute enforcement** — if someone cheats, the blockchain is the final court. Fraud proofs are submitted on-chain, and the cheater's collateral is automatically seized. - -You can think of Layer 1 as the vault and the judge — it holds the real assets and enforces the rules. - -### Layer 2 — The Clearnet (Off-Chain Ledger) - -This is where the speed comes from. Instead of recording every transaction on a blockchain (which is slow and expensive), Yellow Network runs an off-chain peer-to-peer ledger called the **Yellow Clearnet**. - -Here's how it works: - -1. **Independent node operators** run open-source software (called a "clearnode") on their own servers. There is no central server — the network is formed by these independent operators. - -2. **Every user account is guarded by a group of nodes**, not a single one. These nodes are selected algorithmically based on proximity in a shared address space (using a system called Kademlia, the same technology behind BitTorrent). The group collectively manages the account using **threshold cryptography** — meaning a supermajority of the group must agree before any balance can change. No single node can steal funds. - -3. **Security scales with value.** A small account might be guarded by 3 nodes. A high-value account could be guarded by up to 256. The protocol automatically ensures that the total collateral posted by the nodes guarding an account always exceeds the value in that account — so cheating always costs more than it gains. - -4. **A separate ring of watcher nodes** independently verifies every transaction. If the primary group tries to process a fraudulent transaction, the watchers catch it, produce a cryptographic fraud proof, and submit it to the blockchain. The cheating nodes lose their collateral automatically. - -The result: transactions clear in sub-second time (compared to minutes or hours on-chain), while retaining the security guarantees of the underlying blockchains. - -### Layer 3 — Applications - -On top of the Clearnet, developers build applications using the **Yellow SDK**. This is the user-facing layer: - -- **Yellow App Store** — a registry of applications built on the network. -- **Developer tools** — the SDK abstracts away the complexity of state channels, multi-chain settlement, and cryptographic signing. A developer can build an app that works across six blockchains without dealing with any of that directly. -- **Dispute resolution** — if there is a disagreement between a user and an application, independent arbitration forums can adjudicate the dispute, with outcomes enforced on-chain. - ---- - -## What Actually Happens When You Use It - -Here is a concrete example of a cross-chain transfer: - -1. **Alice** has 100 USDC on Ethereum deposited into Yellow Network. -2. She wants to send 50 USDC to **Bob**, who uses Base. -3. Alice's node cluster debits her account and produces a signed certificate. -4. The certificate is routed through the peer-to-peer network to Bob's node cluster. -5. Bob's cluster verifies the certificate and credits Bob's account. -6. Bob can now withdraw 50 USDC on Base (or any other supported chain). - -This entire process takes less than a second. No bridge. No centralised exchange. No on-chain gas fees for the transfer itself. The blockchains are only used for deposits, withdrawals, and dispute resolution. - ---- - -## The YELLOW Token - -YELLOW is the utility token that provides access to the goods and services supplied by Layer3 Fintech Ltd. within the Yellow Network. It has three specific functions: - -### 1. Mandatory Security Deposit for Node Operators - -Every node operator must post YELLOW tokens as collateral to register on the network. This is not optional — it is the mechanism that makes the network secure. - -- **Prevents spam attacks** — you cannot cheaply flood the network with malicious nodes because each one requires real collateral. -- **Deters fraud** — if a node participates in a fraudulent transaction, its collateral is automatically seized ("slashed") through on-chain fraud proofs. -- **Scales with responsibility** — as a node guards higher-value accounts, the protocol requires more collateral at risk. - -The minimum collateral starts at 10,000 YELLOW and scales up to 125,000 YELLOW as the network grows. - -### 2. Service Access Fee - -All network services — clearing, settlement, data delivery, app subscriptions — require the consumption of YELLOW as a service access fee. Users who hold YELLOW pay fees directly at a discounted rate. For users who do not yet hold YELLOW, an optional convenience mechanism allows payment in other assets (like ETH or USDT); independent third-party liquidity providers convert the payment into YELLOW before the protocol consumes it. - -Protocol fees from clearing and trading operations are locked into the collateral of the nodes that processed them — increasing those operators' slashing exposure. This strengthens network security over time. There is no fee distribution to passive token holders. - -### 3. Dispute Resolution Access - -App builders who register applications on the network post YELLOW as a service quality guarantee. Users who have disputes with an application pay a processing fee in YELLOW to access independent arbitration. If the dispute is upheld, the app builder's collateral can be slashed. - -### What YELLOW Is Not - -- It does not represent ownership in Layer3 Fintech Ltd. or any affiliated entity. -- It does not entitle holders to dividends, profit-sharing, or any form of financial return. -- It is not designed to maintain a stable value — there is no peg, no reserve backing, and no stabilisation mechanism. -- Holding YELLOW alone does not grant participation in protocol parameter administration — that requires actively operating a node. - -The total supply is fixed at **10 billion YELLOW**. No new tokens can ever be created, and there is no burn mechanism. - ---- - -## Who Runs the Network? - -Yellow Network is operated by **independent node operators** who run the open-source clearnode software on their own infrastructure. Layer3 Fintech Ltd. develops and maintains the software — but it does not operate the network itself. This is similar to how a software company distributes server software that thousands of independent hosting providers run on their own hardware. - -The protocol's on-chain smart contracts contain configurable parameters (security thresholds, fee levels, supported chains) that need to be updated as the network evolves. These parameters are administered by active node operators through a distributed multi-signature process — replacing what would otherwise be a single administrator key (a security risk). This parameter administration is an operational duty of running a node, not a right that comes with holding the token. - ---- - -## Key Numbers - -| Metric | Value | -|---|---| -| Total YELLOW supply | 10,000,000,000 (fixed) | -| Supported blockchains | Ethereum, Base, Arbitrum, Linea, BNB Chain, Polygon | -| Minimum node collateral | 10,000 YELLOW (scales to 125,000) | -| Max nodes per account | 256 | -| Min nodes per account | 3 | -| Collateral unlock period | 14 days | -| Transaction speed | Sub-second (off-chain clearing) | -| Fee range | 0.1% — 0.4% (dynamic) | - -## Token Allocation - -| Allocation | Percentage | Purpose | -|---|---|---| -| Founders | 10% | Subject to 6-month cliff and 60-month linear vesting | -| Token Sales | 12.5% | Distributed to participants who require YELLOW for service access | -| Community Treasury | 30% | Grants for app builders who consume YELLOW for services | -| Foundation Treasury | 20% | Funds ongoing R&D and delivery of Yellow Network services | -| Network Growth Incentives | 25% | Distributed automatically based on network scale | -| Ecosystem Accessibility Reserve | 2.5% | Ensures YELLOW remains accessible for its intended utility | - -The Foundation controls 50% of total supply (Community Treasury + Foundation Treasury), subject to linear vesting with quarterly reporting on all movements. - ---- - -## Security and Audits - -Yellow Network's smart contracts have been independently audited: - -- **Hacken (2024)** — Security assessment of the Ethereum smart contracts. No critical issues found. [Full report](https://hacken.io/audits/openware-yellow-network/sca-yellow-network-vault-sept-2024/) -- **GuardianAudits (ongoing)** — Auditing the decentralised ledger (Yellow Clearnet). [Reports](https://github.com/GuardianAudits/Audits/tree/main/Yellow%20Network/) - -The core state channel technology builds on academic research from statechannels.org and the VirtualApp framework, developed in collaboration with Consensys and other open-source contributors. - ---- - -## Where to Learn More - -- **Website:** [yellow.org](https://yellow.org/) -- **Developer docs:** [docs.yellow.org](https://docs.yellow.org/) -- **Protocol source code:** [github.com/layer-3/clearnet](https://github.com/layer-3/clearnet) -- **Documentation source:** [github.com/layer-3/docs](https://github.com/layer-3/docs) - ---- - -## Legal Entity - -Yellow Network's goods and services are supplied by **Layer3 Fintech Ltd.**, a company registered in the British Virgin Islands (Registration: 2092094), with its parent entity **Layer3 Foundation** based in the Cayman Islands. The sole director is Paul Parker. The applicable law and competent court for the token offering is Ireland. - -YELLOW is classified as a **utility token** under EU Regulation 2023/1114 (MiCA), Article 3(1)(9) — a token that is only intended to provide access to a good or a service supplied by its issuer. It is not a financial instrument, not an asset-referenced token, not an e-money token, and not a security. diff --git a/docs/guides/index.md b/docs/guides/index.md index 6b80a03..5f86ab5 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -11,3 +11,11 @@ displayed_sidebar: guidesSidebar **[Multi-Party App Sessions](/docs/guides/multi-party-app-sessions)** - Learn how to create, manage, and close multi-party application sessions using the Yellow Network and VirtualApp protocol. + +## Manuals + +**[Running Clearnode Locally](/docs/guides/manuals/running-clearnode-locally)** - Run a Clearnode locally using Docker Compose for development and testing. + +**[Request Asset Support](/docs/guides/manuals/request-asset-support)** - Guide for requesting asset and token support in Clearnode environments. + +**[Request Blockchain Support](/docs/guides/manuals/request-blockchain-support)** - Guide for requesting blockchain network support in Clearnode environments. diff --git a/docs/guides/manuals/_category_.json b/docs/guides/manuals/_category_.json new file mode 100644 index 0000000..d553862 --- /dev/null +++ b/docs/guides/manuals/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Manuals", + "position": 10, + "link": { + "type": "generated-index" + }, + "collapsible": false, + "collapsed": false +} diff --git a/docs/manuals/request-asset-support.md b/docs/guides/manuals/request-asset-support.md similarity index 100% rename from docs/manuals/request-asset-support.md rename to docs/guides/manuals/request-asset-support.md diff --git a/docs/manuals/request-blockchain-support.md b/docs/guides/manuals/request-blockchain-support.md similarity index 100% rename from docs/manuals/request-blockchain-support.md rename to docs/guides/manuals/request-blockchain-support.md diff --git a/docs/manuals/running-clearnode-locally.md b/docs/guides/manuals/running-clearnode-locally.md similarity index 100% rename from docs/manuals/running-clearnode-locally.md rename to docs/guides/manuals/running-clearnode-locally.md diff --git a/docs/learn/introduction/supported-chains.mdx b/docs/learn/introduction/supported-chains.mdx index 72ac7a1..d89c8b6 100644 --- a/docs/learn/introduction/supported-chains.mdx +++ b/docs/learn/introduction/supported-chains.mdx @@ -257,8 +257,8 @@ Contract addresses vary by blockchain. See the [deployment repository](https://g Need support for a blockchain or asset not listed here? -- **[Request Blockchain Support](/docs/manuals/request-blockchain-support)** — Guide for adding new blockchain networks -- **[Request Asset Support](/docs/manuals/request-asset-support)** — Guide for adding new tokens/assets +- **[Request Blockchain Support](/docs/guides/manuals/request-blockchain-support)** — Guide for adding new blockchain networks +- **[Request Asset Support](/docs/guides/manuals/request-asset-support)** — Guide for adding new tokens/assets --- diff --git a/docs/manuals/_category_.json b/docs/manuals/_category_.json deleted file mode 100644 index 176732f..0000000 --- a/docs/manuals/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Manuals", - "position": 4, - "link": { - "type": "doc", - "id": "manuals/index" - } -} \ No newline at end of file diff --git a/docs/manuals/index.md b/docs/manuals/index.md deleted file mode 100644 index 04d75bf..0000000 --- a/docs/manuals/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Manuals -description: Comprehensive manuals and documentation -displayed_sidebar: manualsSidebar ---- - -# Manuals - -:::info Work in Progress -This section is currently under development. Comprehensive manuals and documentation will be available soon. -::: - -Coming soon: Detailed manuals covering all aspects of the platform. \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 31b37d6..b575108 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -92,9 +92,6 @@ const config: Config = { mermaid: true, }, themes: ['@docusaurus/theme-mermaid'], - clientModules: [ - './src/clientModules/hideContractsOn05x.js', - ], plugins: [ [ 'docusaurus-lunr-search', @@ -139,18 +136,6 @@ const config: Config = { label: 'Protocol', position: 'left', }, - { - to: '/docs/contracts', - label: 'Contracts', - position: 'left', - className: 'navbar-contracts-link', - }, - { - type: 'doc', - docId: 'manuals/index', - label: 'Manuals', - position: 'left', - }, { type: 'doc', docId: 'guides/index', @@ -200,10 +185,6 @@ const config: Config = { label: 'Build', to: '/docs/build/quick-start', }, - { - label: 'Manuals', - to: '/docs/manuals', - }, { label: 'Guides', to: '/docs/guides', diff --git a/i18n/en/docusaurus-theme-classic/footer.json b/i18n/en/docusaurus-theme-classic/footer.json index a351286..d6cc919 100644 --- a/i18n/en/docusaurus-theme-classic/footer.json +++ b/i18n/en/docusaurus-theme-classic/footer.json @@ -23,10 +23,6 @@ "message": "Build", "description": "The label of footer link with label=Build linking to /docs/build/quick-start" }, - "link.item.label.Manuals": { - "message": "Manuals", - "description": "The label of footer link with label=Manuals linking to /docs/manuals" - }, "link.item.label.Guides": { "message": "Guides", "description": "The label of footer link with label=Guides linking to /docs/guides" diff --git a/scripts/sync-contracts-docs.js b/scripts/sync-contracts-docs.js index aa35d0f..7e98cc8 100644 --- a/scripts/sync-contracts-docs.js +++ b/scripts/sync-contracts-docs.js @@ -1,20 +1,20 @@ /** * Syncs smart-contract documentation from vendors/yellow/docs - * into docs/contracts/ with Docusaurus-compatible frontmatter + * into docs/build/api/contracts/ with Docusaurus-compatible frontmatter * and category metadata. * - * Generates the Deployed Addresses page from @yellow-org/contracts. + * Generates the Deployed Addresses page (as index) from @yellow-org/contracts. * * Usage: node scripts/sync-contracts-docs.js * - * Safe to re-run — it wipes docs/contracts/ and rebuilds from source. + * Safe to re-run — it wipes docs/build/api/contracts/ and rebuilds from source. */ const fs = require('fs'); const path = require('path'); const ROOT = path.resolve(__dirname, '..'); const SRC = path.join(ROOT, 'vendors', 'yellow', 'docs'); -const DEST = path.join(ROOT, 'docs', 'contracts'); +const DEST = path.join(ROOT, 'docs', 'build', 'api', 'contracts'); // --------------------------------------------------------------------------- // On-chain addresses from @yellow-org/contracts @@ -104,7 +104,7 @@ function copyWithFrontmatter(srcFile, destFile, { title, description, sidebarPos `title: "${title}"`, `description: "${description}"`, `sidebar_position: ${sidebarPosition}`, - `displayed_sidebar: contractsSidebar`, + `displayed_sidebar: buildSidebar`, '---', '', '', @@ -117,11 +117,12 @@ function copyWithFrontmatter(srcFile, destFile, { title, description, sidebarPos /** * Write a Docusaurus _category_.json file. */ -function writeCategory(dir, { label, position, link }) { +function writeCategory(dir, { label, position, link, key }) { ensureDir(dir); const data = { label, position, + ...(key && { key }), link: link || { type: 'generated-index' }, collapsible: false, collapsed: false, @@ -138,8 +139,8 @@ function generateAddressesPage() { '---', 'title: "Deployed Addresses"', 'description: "Mainnet and testnet contract addresses for Yellow Network."', - 'sidebar_position: 2', - 'displayed_sidebar: contractsSidebar', + 'sidebar_position: 1', + 'displayed_sidebar: buildSidebar', '---', '', '', @@ -194,19 +195,13 @@ function generateAddressesPage() { // --------------------------------------------------------------------------- const DOCS = { - // Top-level pages - index: { - src: 'what-is-yellow.md', - title: 'Smart Contracts', - description: 'Overview of Yellow Network smart contracts, governance, and on-chain infrastructure.', - sidebarPosition: 1, - }, - // 'addresses' is generated from @yellow-org/contracts — not copied from vendor + // 'index' (Deployed Addresses) is generated from @yellow-org/contracts — not copied from vendor + // README / what-is-yellow.md is intentionally skipped faq: { src: 'FAQ.md', title: 'FAQ', description: 'Frequently asked questions about Yellow Network smart contracts.', - sidebarPosition: 7, + sidebarPosition: 2, }, // Protocol @@ -343,10 +338,17 @@ const CATEGORIES = [ { dir: 'protocol', label: 'Protocol', position: 3 }, { dir: 'api-reference', label: 'Contract API Reference', position: 4 }, { dir: 'api-reference/interfaces', label: 'Interfaces', position: 8 }, - { dir: 'sdk', label: 'SDK', position: 5 }, + { dir: 'sdk', label: 'SDK', position: 5, key: 'contracts-sdk' }, { dir: 'integration', label: 'Integration', position: 6 }, ]; +// Parent category written outside DEST (in docs/build/api/) +const API_CATEGORY = { + dir: path.join(ROOT, 'docs', 'build', 'api'), + label: 'API', + position: 3, +}; + // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- @@ -359,12 +361,25 @@ function main() { process.exit(1); } - console.log('Syncing smart-contract docs from vendors/yellow/docs...\n'); + console.log('Syncing smart-contract docs from vendors/yellow/docs into docs/build/api/contracts/...\n'); // Clean and recreate destination cleanDir(DEST); - // Write category files + // Write parent API category (docs/build/api/) + writeCategory(API_CATEGORY.dir, { + label: API_CATEGORY.label, + position: API_CATEGORY.position, + }); + + // Write Contracts category at DEST root + writeCategory(DEST, { + label: 'Contracts', + position: 1, + link: { type: 'doc', id: 'build/api/contracts/index' }, + }); + + // Write sub-category files for (const cat of CATEGORIES) { writeCategory(path.join(DEST, cat.dir), { label: cat.label, @@ -374,11 +389,11 @@ function main() { // Generate addresses page from @yellow-org/contracts const addressesPage = generateAddressesPage(); - fs.writeFileSync(path.join(DEST, 'addresses.md'), addressesPage); + fs.writeFileSync(path.join(DEST, 'index.md'), addressesPage); if (addresses) { - console.log(' generated addresses.md (from @yellow-org/contracts)'); + console.log(' generated index.md (Deployed Addresses, from @yellow-org/contracts)'); } else { - console.warn(' generated addresses.md (WARNING: @yellow-org/contracts not installed)'); + console.warn(' generated index.md (Deployed Addresses, WARNING: @yellow-org/contracts not installed)'); } // Copy and transform each document from vendor @@ -406,7 +421,7 @@ function main() { } } - console.log(`\nSynced ${count} vendor docs + 1 generated into docs/contracts/`); + console.log(`\nSynced ${count} vendor docs + 1 generated into docs/build/api/contracts/`); console.log('\nStructure:'); // Print tree @@ -430,7 +445,7 @@ function main() { }); } - console.log('docs/contracts/'); + console.log('docs/build/api/contracts/'); printTree(DEST, ''); } diff --git a/sidebars.ts b/sidebars.ts index 5fee934..2462c88 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -84,14 +84,6 @@ const sidebars: SidebarsConfig = { }, ], - // Manuals section sidebar - manualsSidebar: [ - { - type: 'autogenerated', - dirName: 'manuals', - }, - ], - // Tutorials section sidebar tutorialsSidebar: [ { @@ -124,14 +116,6 @@ const sidebars: SidebarsConfig = { }, ], - // Contracts section sidebar - contractsSidebar: [ - { - type: 'autogenerated', - dirName: 'contracts', - }, - ], - // Default sidebar for standalone pages defaultSidebar: [ ], diff --git a/src/clientModules/hideContractsOn05x.js b/src/clientModules/hideContractsOn05x.js deleted file mode 100644 index 2b50d8e..0000000 --- a/src/clientModules/hideContractsOn05x.js +++ /dev/null @@ -1,22 +0,0 @@ -const CONTRACTS_CLASS = 'navbar-contracts-link'; -const LEGACY_PATH = '/docs/0.5.x/'; - -function toggle() { - const el = document.querySelector(`.${CONTRACTS_CLASS}`)?.closest('.navbar__item'); - if (!el) return; - el.style.display = window.location.pathname.startsWith(LEGACY_PATH) ? 'none' : ''; -} - -if (typeof window !== 'undefined') { - toggle(); - - const observer = new MutationObserver(toggle); - observer.observe(document.querySelector('#__docusaurus') || document.body, { - childList: true, - subtree: true, - }); -} - -export function onRouteDidUpdate() { - toggle(); -} diff --git a/src/components/HomepageFeatures/index.tsx b/src/components/HomepageFeatures/index.tsx index ad2eca8..7047bc4 100644 --- a/src/components/HomepageFeatures/index.tsx +++ b/src/components/HomepageFeatures/index.tsx @@ -50,7 +50,7 @@ const FeatureList: FeatureItem[] = [ and contribute to decentralized infrastructure. ), - link: '/docs/manuals', + link: '/docs/guides/manuals/running-clearnode-locally', }, { title: 'Join the Community', diff --git a/src/pages/whitepaper.md b/src/pages/whitepaper.md index f5eb288..d5078fa 100644 --- a/src/pages/whitepaper.md +++ b/src/pages/whitepaper.md @@ -37,7 +37,7 @@ The Foundation controls 50% of total supply, subject to linear vesting. --- -## About the Offeror +## About the Issuer **Layer3 Fintech Ltd.** @@ -81,14 +81,7 @@ Yellow aims to create a decentralised clearing and settlement framework where bu Yellow is an open-source software framework developed through multi-entity collaboration: -| Entity | Function | -|---|---| -| Layer3 Fintech Ltd. (BVI) | Integration, Maintenance, and Supply of Goods and Services (Issuer) | -| Clearsync Ltd. (UK) | Core Technology Development | -| Helios Technologies SAS (France) | Core Technology Development | -| Openware SAS (France) | Core Technology Development | - -The core state channel technology builds on academic research from statechannels.org and the VirtualApp framework, developed in collaboration with Consensys and other open-source contributors. Approximately 60 core developers contribute across the open-source codebase, with over 100 third-party applications launched on the network in 2025. +The core state channel technology builds on academic research from statechannels.org and the Nitro framework, developed in collaboration with Consensys and other open-source contributors. Approximately 60 core developers contribute across the open-source codebase, with over 100 third-party applications launched on the network in 2025. ### Token Utility @@ -108,6 +101,7 @@ YELLOW is consumed when accessing protocol services: each protocol operation req **Reached:** **2024:** + - State Channel and Account Abstraction R&D - Launch of the Yellow Smart Account - Launch of the Yellow Wallet @@ -116,6 +110,7 @@ YELLOW is consumed when accessing protocol services: each protocol operation req - Finalization of the Core Protocol Architecture **2025:** + - Production Release of the Yellow SDK - Network Expansion to 6 New EVM Chains - Official Launch of the Yellow Builder Program @@ -124,6 +119,7 @@ YELLOW is consumed when accessing protocol services: each protocol operation req **Outlook:** **2025-2026:** + - Public Release of the NeoDAX Brokerage Software - Finalization of the Clearing Network Architecture - Public Release of the Yellow Clearing Network @@ -182,16 +178,19 @@ Applications built on top of the Ledger Layer. Application-level state updates a ### Protocols and Technical Standards **Layer 1 — On-chain standards** + - ERC-20 token standard on Ethereum - Custody smart contracts for on-chain asset custody and withdrawal settlement - NodeRegistry and AppRegistry contracts for node/application registration and collateral management **Layer 2 — Ledger Layer protocols** + - Peer-to-peer network protocol with deterministic, decentralised routing - Threshold signature protocol (BLS) requiring supermajority for state updates - Virtual State Channel protocol for off-chain balance management and cross-chain clearing **Layer 3 — Application Layer standards** + - AppLayer RPC API for application-to-clearnode interaction - AppLayerClient library for Virtual State Channel control and cryptographic signing - Yellow SDK abstracting channel management, multi-chain settlement, and unified balances (e.g., 50 USDC on Ethereum + 50 USDC on Base = 100 USDC unified balance) @@ -295,6 +294,10 @@ Governance is non-transferable, non-delegable, and terminates immediately upon c - [github.com/layer-3/clearnet](https://github.com/layer-3/clearnet) — Yellow network node repository (open-source client software and smart contracts) - [github.com/layer-3/docs](https://github.com/layer-3/docs) — Documentation website repository ---- +## MiCA White Paper Filing History + +The following versions of the YELLOW crypto-asset white paper have been filed under the Markets in Crypto-Assets Regulation (EU) 2023/1114: -*This is a public-facing summary of the Yellow Network Whitepaper v2.0. For the full regulatory whitepaper including MiCA compliance details, sustainability indicators, and complete legal disclosures, please contact [legal@layer3.foundation](mailto:legal@layer3.foundation).* +| Version | Date of Notification | Status | Document | +|---|---|---|---| +| v1.2 | 2025-11-14 | Current | [YELLOW MiCA White Paper v1.2 (PDF)](/assets/YELLOW_MiCA_White_Paper_v.1.2.pdf) | diff --git a/versioned_docs/version-0.5.x/build/quick-start/index.md b/versioned_docs/version-0.5.x/build/quick-start/index.md index d397f78..75cad82 100644 --- a/versioned_docs/version-0.5.x/build/quick-start/index.md +++ b/versioned_docs/version-0.5.x/build/quick-start/index.md @@ -347,7 +347,7 @@ await app.sendPayment('100000', '0xPartnerAddress'); // Send 0.1 USDC Congratulations! You've built your first Yellow App. Here's what to explore next: -- **[Advanced Topics](../../learn/advanced/architecture)**: Learn about architecture, multi-party applications, and production deployment +- **[Advanced Topics](../../learn/introduction/architecture-at-a-glance)**: Learn about architecture, multi-party applications, and production deployment - **[API Reference](../../api-reference)**: Explore all available SDK methods and options ## Need Help? diff --git a/versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx b/versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx index 55e0560..0e58ebe 100644 --- a/versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx +++ b/versioned_docs/version-0.5.x/learn/introduction/supported-chains.mdx @@ -253,8 +253,8 @@ Contract addresses vary by blockchain. See the [deployment repository](https://g Need support for a blockchain or asset not listed here? -- **[Request Blockchain Support](/docs/manuals/request-blockchain-support)** — Guide for adding new blockchain networks -- **[Request Asset Support](/docs/manuals/request-asset-support)** — Guide for adding new tokens/assets +- **[Request Blockchain Support](../../manuals/request-blockchain-support)** — Guide for adding new blockchain networks +- **[Request Asset Support](../../manuals/request-asset-support)** — Guide for adding new tokens/assets ---