From edd9ef8c792d18f8ec15743b6bf26fc46f986d6d Mon Sep 17 00:00:00 2001 From: rfxfxfx Date: Mon, 31 Aug 2026 13:41:50 +0800 Subject: [PATCH] docs: replace inherited Frontier branding and disclosure policy The docs site and the security policy were carried over from Frontier and still describe that project rather than this one. - SECURITY.md routed vulnerability reports to security@bitarray.dev and to "the Frontier repo", so a report about the shielded pool would have reached Frontier's maintainers rather than Orbinum's. Rewritten around security@orbinum.net, the address CONTRIBUTING.md already names, with a scope section covering the node, orbinum/circuits, and the SDKs, and a note routing genuine upstream Frontier issues back to Frontier. - docs/.vitepress/config.mts set title "Frontier", base '/frontier', a GitHub link to polkadot-evm/frontier, an API link to Frontier's rustdocs, and a "Copyright Frontier developers" footer. - docs/index.md and docs/overview.md were Frontier's landing page and its explanation of Frontier's three EVM integration models, neither of which applies here. Replaced with an Orbinum overview drawn from the repository README and the pallet documentation: the public/private domains, the commitment and nullifier construction, what the transfer proof establishes, gasless submission, note recovery, and the crate layout. - CONTRIBUTING.md gave a fixed "estimated opening date" for external contributions that has now passed. Replaced with a pointer to Discussions so the section does not silently go stale again, and linked SECURITY.md from the vulnerability-reporting line. Documentation only. No code or configuration outside docs/ is touched. Co-Authored-By: Claude Opus 5 --- CONTRIBUTING.md | 7 ++- SECURITY.md | 36 ++++++++++--- docs/.vitepress/config.mts | 14 ++--- docs/index.md | 22 ++++---- docs/overview.md | 101 +++++++++++++++++++++++++------------ 5 files changed, 123 insertions(+), 57 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 919f4645..2835a775 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,11 +8,14 @@ Thank you for your interest in contributing to Orbinum Network Node! This docume Orbinum Network Node is in early development phase and the core team is working on establishing the base architecture and completing the initial security audit. -**Estimated opening date:** Q2 2026 +We will update this section when that changes. If you are reading this well +after the date of the last commit and it still says contributions are closed, +please ask in [GitHub Discussions](https://github.com/orbinum/node/discussions) +rather than assuming it is stale. **In the meantime, you can:** - Star the project to follow updates -- Report critical security vulnerabilities to: security@orbinum.net +- Report security vulnerabilities privately to security@orbinum.net (see [SECURITY.md](SECURITY.md)) - Participate in [GitHub Discussions](https://github.com/orbinum/node/discussions) - Review documentation and suggest minor improvements diff --git a/SECURITY.md b/SECURITY.md index 20a5be77..fda57067 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,14 +2,38 @@ ## Supported versions -Currently, only the latest master commit pin is supported. This will be extended back to releases as soon as we fix the Substrate release pipeline. +Only the latest commit on `main` is supported. Support will be extended back to +tagged releases once the release pipeline is stable. -## Reporting vulnerabilities +## Reporting a vulnerability -For medium or high severity security vulnerabilities, please report them by email to security@bitarray.dev. +Report suspected vulnerabilities privately by email to **security@orbinum.net**. -For low severity security vulnerabilities, you can either follow the above reporting pipeline or open an issue in the Frontier repo directly. If you are unsure about the severity of the vulnerability you're reporting, please reach out to [Wei](mailto:wei@bitarray.dev). +Please do not open a public issue, pull request, or discussion thread for a +security report. Orbinum holds user funds in a shielded pool, so a public report +is a disclosure. -## Advisory announcements +Useful things to include, as far as you have them: -Due to the nature of open source, security vulnerability fixes are public. An announcement room at #frontier-security:matrix.org is available. The room is invite only and is only for ecosystem users who require immediate and urgent actions when an advisory is available. Please contact [Wei](mailto:wei@bitarray.dev) for invites. +- the affected component and the commit you tested against +- what an attacker gains, and what they need in order to get it +- reproduction steps, or a proof-of-concept if you have one +- whether you have shared the report with anyone else + +We will acknowledge receipt and let you know whether we are treating the report +as a vulnerability. If you would like a coordinated disclosure date, say so and +we will agree one with you. + +There is currently no bug bounty program. Reports are welcome regardless. + +## Scope + +This policy covers the Orbinum node and runtime in this repository, the +zero-knowledge circuits in [orbinum/circuits](https://github.com/orbinum/circuits), +and the client SDKs published under the [orbinum](https://github.com/orbinum) +organization. + +Orbinum builds on [Frontier](https://github.com/polkadot-evm/frontier). A +vulnerability in unmodified upstream Frontier or Polkadot SDK code should be +reported to those projects. If you are unsure which applies, send it to us and +we will route it. diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index e56e0f6a..30c1c4f4 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -3,9 +3,9 @@ import { footnote } from "@mdit/plugin-footnote"; // https://vitepress.dev/reference/site-config export default defineConfig({ - title: "Frontier", - description: "Ethereum and EVM compatibility layer for Polkadot", - base: '/frontier', + title: "Orbinum", + description: "Privacy-focused Substrate network with EVM compatibility and a ZK shielded pool", + base: '/node', cleanUrls: true, themeConfig: { @@ -14,7 +14,7 @@ export default defineConfig({ nav: [ { text: 'Home', link: '/' }, { text: 'Overview', link: '/overview' }, - { text: 'API', link: 'https://polkadot-evm.github.io/frontier/rustdocs/pallet_evm/' } + { text: 'API', link: 'https://orbinum.github.io/node/rustdocs/pallet_shielded_pool/' } ], sidebar: [ @@ -35,12 +35,12 @@ export default defineConfig({ ], socialLinks: [ - { icon: 'github', link: 'https://github.com/polkadot-evm/frontier' } + { icon: 'github', link: 'https://github.com/orbinum/node' } ], footer: { - message: 'Legal notice', - copyright: 'Copyright © 2018-present, Frontier developers' + message: 'Dual-licensed under Apache-2.0 and GPL-3.0', + copyright: 'Copyright © 2025-present, Orbinum contributors' }, }, diff --git a/docs/index.md b/docs/index.md index ac6562b4..1c58584e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,21 +3,21 @@ layout: home hero: - name: "Frontier" - text: "Polkadot EVM backbone" - tagline: Frontier is the Ethereum and EVM compatibility layer for Polkadot. + name: "Orbinum" + text: "Private transactions on Substrate" + tagline: A privacy-focused network combining a Groth16 shielded pool with full EVM compatibility. actions: - theme: brand text: Overview link: /overview features: -- title: EVM contract - details: Frontier allows you to run EVM contracts natively in Substrate, tightly integrated with the rest of the Substrate ecosystem. -- title: Full compatibility - details: Frontier provides full compatibility. This means that tools and dapps from the Ethereum ecosystem can be used unmodified. -- title: Substrate Module - details: Frontier can be easily integrated in your existing Substrate application as a runtime module. -- title: Optional PolkaVM support - details: Frontier provides an optional PolkaVM support. The format is built on top of EIP-3541, enabling seamless integration. +- title: Shielded pool + details: A UTXO-model privacy layer where value lives as Poseidon commitments in a Merkle forest. Shield, transfer, and unshield, each backed by a Groth16 proof verified on-chain. +- title: EVM compatibility + details: Built on Frontier, so Solidity contracts, MetaMask, and the standard Ethereum RPC surface work unmodified. EVM and Substrate accounts share one balance. +- title: Gasless privacy + details: Private transfers and withdrawals are unsigned and carry their fee inside the proof, so a relayer can pay gas without learning who is transacting. +- title: Selective disclosure + details: Encrypted memos let an owner recover their notes by scanning, and value proofs let them prove what a commitment encodes without revealing the blinding factor. --- diff --git a/docs/overview.md b/docs/overview.md index cbff4ab0..38aefeb7 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,46 +1,85 @@ # Overview -Frontier is the suite that provides an Ethereum compatibility layer for Substrate. It has two components that can be activated separately: +Orbinum is a Substrate-based network that pairs a zero-knowledge shielded pool +with a full Ethereum compatibility layer. The transparent side behaves like any +EVM chain; the private side holds value as cryptographic commitments that reveal +neither amounts nor participants. -- Pallet EVM: - This is the pallet that enables functionality of running EVM contracts. - Existing EVM code can be used from there, using addresses and values mapped directly to Substrate. -- Pallet Ethereum with Ethereum compatible RPC methods: - The pallet, combined with the RPC module, enables Ethereum block emulation, validates Ethereum-encoded transactions, - and allows existing dapps to be deployed on a Substrate blockchain with minimal modifications. +## The two domains -## EVM execution only +Value moves between a public domain and a private one: -In many situations, a Substrate blockchain may only want to include EVM execution capabilities. -In this way, it functions similarly to `pallet-contracts`, integrates with Substrate better and is less intrusive. -The module, and its EVM execution capabilities, can be added or removed at any moment via forkless upgrades. -With EVM execution only, Substrate uses its account model fully and signs transactions on behalf of EVM accounts. +- **Public.** An `AccountId` with a visible balance, usable from Solidity + contracts and standard Ethereum tooling. +- **Private.** A note, represented on-chain only by a Poseidon commitment + `Poseidon4(value, asset_id, owner_pubkey, blinding)` inserted as a leaf in a + Merkle tree. Nothing about the note is visible beyond the commitment itself. -In this model, however, Ethereum RPCs are not available, and dapps must rewrite their frontend using the Substrate API. -If this is the intended way of usage, take a look at the [`pallet-evm`](https://github.com/polkadot-evm/frontier/tree/master/frame/evm) documentation. +Three operations connect them: -## Post-block generation +| Operation | Direction | What it reveals | +|---|---|---| +| `shield` | public to private | depositor and amount | +| `private_transfer` | private to private | the asset and the relay fee | +| `unshield` | private to public | recipient and amount | -On other situations, a full emulation of Ethereum may be desired so that Ethereum RPCs become available. -In this model, a full Ethereum block is emulated within the Substrate runtime, and is generated post-block for the consumption rest of the APIs. -In addition to Substrate account signing, traditional Ethereum transactions are also processed and validated. +Spending a note publishes its nullifier, `Poseidon2(commitment, spending_key)`. +The chain records nullifiers in a set and rejects repeats, which prevents +double-spending without linking the nullifier back to the commitment it came +from. -If this is the intended way of usage, take a look at the [`pallet-ethereum`](https://github.com/polkadot-evm/frontier/tree/master/frame/ethereum) documentation. +## Proofs -## Pre-block feeding +Every private operation carries a Groth16 proof over BN254, verified in the +runtime by `pallet-zk-verifier`. The circuits are written in Circom and live in +[orbinum/circuits](https://github.com/orbinum/circuits); the runtime stores only +their verification keys, versioned per circuit and rotatable by governance. -An Ethereum-based blockchain can use the pre-block feeding strategy to migrate to Substrate. -In the post-block generation model, the Ethereum block is generated *after* runtime execution. -In the pre-block feeding model, the Ethereum block is fed in *before* runtime execution. +A transfer proof establishes, without revealing the notes involved, that: -A blockchain can first use pre-block feeding with empty extrinsic requirement. -In this way, because no other external information is fed, combined with a suitable consensus engine, one Ethereum block will have an exact corresponding Substrate block. -This is called the [wrapper block](https://corepaper.org/substrate/wrapper/) strategy, and it allows Frontier to function as a normal Ethereum client. +- each input commitment is a member of a known Merkle root +- the spender owns each input note, via an EdDSA signature over the commitment +- each published nullifier matches its input note +- each output commitment is correctly formed +- value is conserved: `sum(inputs) == sum(outputs) + fee` +- every note in the transaction uses the same asset -With a sufficient number of the network running a Frontier node, the blockchain can then initiate a hard fork, allowing extrinsic to be added in. -From there on, the blockchain is migrated to Substrate and can enjoy Substrate-specific features like on-chain governance and forkless upgrade. +## Gasless submission -A complete in-storage pre-block feeding requires using Substrate's child storage. -It can also be implemented using the stateless client strategy to eliminate that need. +`private_transfer` and `unshield` are unsigned extrinsics. A signature would +identify the sender, so instead the proof itself authorises the operation and +the fee is deducted from the note value inside the circuit. A relayer submits +the transaction, pays gas, and accrues the fee as a credit it can later claim as +a shielded note of its own. -Pre-block feeding is still work-in-progress. +Relayers can be reached through the shielded-pool EVM precompile, which takes +the caller's address as the fee recipient, or through a node running the +built-in relay RPC. + +## Note recovery + +Because a commitment hides its own contents, a wallet cannot tell which notes +belong to it by looking at the chain. Each commitment therefore carries an +encrypted memo holding the note's preimage, encrypted with ChaCha20-Poly1305 +under a key derived by BabyJubJub ECDH between the sender's ephemeral key and +the recipient's incoming viewing key. A wallet scans memos and keeps the ones it +can decrypt. + +## Components + +| Crate | Role | +|---|---| +| `pallet-shielded-pool` | Commitments, nullifiers, the Merkle forest, and the three operations | +| `pallet-zk-verifier` | Versioned verification keys and Groth16 verification | +| `pallet-relayer` | Relay configuration, the EVM-to-Substrate relayer registry, and fee accounting | +| `pallet-validator-set` | Two-phase validator registration behind governance approval | +| `orbinum-zk-core` | Poseidon hashing and field-element handling, shared by runtime and clients | +| `orbinum-encrypted-memo` | Memo layout, key derivation, and memo encryption | + +## Relationship to Frontier + +The EVM pallets, the Ethereum RPC layer, and much of the client infrastructure +are derived from [Frontier](https://github.com/polkadot-evm/frontier). Orbinum +adds the privacy stack above and a precompile that bridges Solidity calls into +the shielded pool. See the [attribution note](https://github.com/orbinum/node#attribution) +in the repository README.