From 9e80b0c121caec5005b50542427447d6e72126ac Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Thu, 31 Jul 2025 19:46:11 +0300 Subject: [PATCH 1/8] feat(nix-shell): Add repomix This is an useful tool for preparing code listing for LLMs: https://repomix.com/ --- nix/shells/pkg-sets/dev-shell.nix | 1 + 1 file changed, 1 insertion(+) diff --git a/nix/shells/pkg-sets/dev-shell.nix b/nix/shells/pkg-sets/dev-shell.nix index 76a94ba9e4..22f27cb40f 100644 --- a/nix/shells/pkg-sets/dev-shell.nix +++ b/nix/shells/pkg-sets/dev-shell.nix @@ -18,6 +18,7 @@ process-compose coreutils ripgrep + repomix ]; # NOTE: throughout the code, we're relying on `$GIT_ROOT` to be set From 80a749f52d63395cd6f20258c72d6ccaf2a2e8f1 Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Fri, 1 Aug 2025 02:35:45 +0300 Subject: [PATCH 2/8] feat(spec): Integrate Quartz for publishing the upcoming spec files --- flake.lock | 45 +++++++++- flake.nix | 5 ++ nix/pkgs/default.nix | 6 ++ nix/shells/default.nix | 4 + nix/shells/pkg-sets/spec-docs.nix | 20 +++++ package.json | 3 +- spec/content/README.md | 145 ++++++++++++++++++++++++++++++ spec/content/index.md | 58 ++++++++++++ spec/package.json | 12 +++ spec/quartz.config.ts | 84 +++++++++++++++++ spec/quartz.layout.ts | 51 +++++++++++ spec/quartz/build.ts | 91 +++++++++++++++++++ yarn.lock | 6 ++ 13 files changed, 528 insertions(+), 2 deletions(-) create mode 100644 nix/shells/pkg-sets/spec-docs.nix create mode 100644 spec/content/README.md create mode 100644 spec/content/index.md create mode 100644 spec/package.json create mode 100644 spec/quartz.config.ts create mode 100644 spec/quartz.layout.ts create mode 100644 spec/quartz/build.ts diff --git a/flake.lock b/flake.lock index c4ae33823d..446f848bda 100644 --- a/flake.lock +++ b/flake.lock @@ -1080,6 +1080,48 @@ "type": "github" } }, + "quartz": { + "flake": false, + "locked": { + "lastModified": 1753893816, + "narHash": "sha256-HnCPItXUv4kVCBqohAdXK1k17//Rnb3Yoroa+YAaGLs=", + "owner": "jackyzha0", + "repo": "quartz", + "rev": "efddd798e83705b0e17e074fe344b2d491051ba2", + "type": "github" + }, + "original": { + "owner": "jackyzha0", + "ref": "v4", + "repo": "quartz", + "type": "github" + } + }, + "quartz-nix": { + "inputs": { + "flake-utils": [ + "mcl-blockchain", + "flake-utils" + ], + "nixpkgs": [ + "nixpkgs" + ], + "quartz": "quartz" + }, + "locked": { + "lastModified": 1754004279, + "narHash": "sha256-WJo8ulWjD3oDjOwDPKHh9dReZWKvhugB/AN03fnIuiE=", + "owner": "blocksense-network", + "repo": "nix-quartz", + "rev": "0f19638c293ee5fa34aff76335eb230b5e19baed", + "type": "github" + }, + "original": { + "owner": "blocksense-network", + "repo": "nix-quartz", + "type": "github" + } + }, "root": { "inputs": { "blama": "blama", @@ -1118,7 +1160,8 @@ "nixpkgs-unstable": [ "mcl-blockchain", "nixpkgs-unstable" - ] + ], + "quartz-nix": "quartz-nix" } }, "rust-analyzer-src": { diff --git a/flake.nix b/flake.nix index 6f13db5365..191d4305ea 100644 --- a/flake.nix +++ b/flake.nix @@ -32,6 +32,11 @@ url = "github:blocksense-network/blama"; flake = false; }; + quartz-nix = { + url = "github:blocksense-network/nix-quartz"; + inputs.nixpkgs.follows = "nixpkgs"; + inputs.flake-utils.follows = "mcl-blockchain/flake-utils"; + }; }; outputs = diff --git a/nix/pkgs/default.nix b/nix/pkgs/default.nix index 5f6ae1ea71..fc6d563635 100644 --- a/nix/pkgs/default.nix +++ b/nix/pkgs/default.nix @@ -70,6 +70,12 @@ inherit blocksense-rs; inherit blama; inherit wit-converter; + + # Specification website using Quartz + specification-website = inputs.quartz-nix.lib.${pkgs.system}.mkQuartzSite { + name = "blocksense-specification"; + src = ../../spec; + }; }; legacyPackages = { oracle-scripts = { diff --git a/nix/shells/default.nix b/nix/shells/default.nix index 2013ccaf90..1856fc188b 100644 --- a/nix/shells/default.nix +++ b/nix/shells/default.nix @@ -39,6 +39,10 @@ module = ./pkg-sets/js.nix; shellName = "JS"; }; + docs = createShell { + module = ./pkg-sets/spec-docs.nix; + shellName = "Documentation"; + }; pre-commit = createShell { module = ./pkg-sets/pre-commit.nix; shellName = "Lint"; diff --git a/nix/shells/pkg-sets/spec-docs.nix b/nix/shells/pkg-sets/spec-docs.nix new file mode 100644 index 0000000000..96619cd0cc --- /dev/null +++ b/nix/shells/pkg-sets/spec-docs.nix @@ -0,0 +1,20 @@ +{ inputs', ... }: +{ + packages = [ + inputs'.quartz-nix.packages.quartz-cli + ]; + + enterShell = '' + echo "πŸ“š Blocksense Documentation Environment" + echo "======================================" + echo "" + echo "Available tools:" + echo " quartz create - Initialize a new Quartz site" + echo " quartz build - Build the specification website" + echo " quartz sync - Sync content with remote" + echo "" + echo "Specification content is in: ./spec/" + echo "To build the website: nix build .#specification-website" + echo "" + ''; +} diff --git a/package.json b/package.json index 85563ec36d..89517b838a 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,8 @@ "workspaces": [ "apps/*", "libs/ts/*", - "libs/aztec_contracts/" + "libs/aztec_contracts/", + "spec/website" ], "scripts": { "clean": "git clean -fdx -e .env -e .direnv -e .yarn -e .vscode -e .pre-commit-config.yaml -- $(git rev-parse --show-toplevel)", diff --git a/spec/content/README.md b/spec/content/README.md new file mode 100644 index 0000000000..1cd278c905 --- /dev/null +++ b/spec/content/README.md @@ -0,0 +1,145 @@ +# Blocksense Protocol Specification + +This repository contains the complete technical specification for the Blocksense Protocol, designed as an executable specification with implementations in multiple languages and formal verification. + +## Overview + +The specification is structured as an Obsidian vault with heavy cross-linking and is automatically published as a website at [specification.blocksense.network](https://specification.blocksense.network) using Quartz v4. + +## Directory Structure + +``` +spec/ +β”œβ”€β”€ README.md # This file +β”œβ”€β”€ obsidian/ # Obsidian vault configuration +β”‚ β”œβ”€β”€ .obsidian/ # Obsidian settings +β”‚ └── templates/ # Note templates +β”œβ”€β”€ core/ # Core protocol specifications +β”‚ β”œβ”€β”€ consensus/ # Consensus mechanisms +β”‚ β”œβ”€β”€ architecture/ # System architecture +β”‚ β”œβ”€β”€ cryptography/ # Cryptographic primitives +β”‚ └── state-model/ # State management +β”œβ”€β”€ data-feeds/ # Oracle and data feed specifications +β”œβ”€β”€ networking/ # Network layer specifications +β”œβ”€β”€ economics/ # Economic model and tokenomics +β”œβ”€β”€ smart-contracts/ # On-chain contract specifications +β”œβ”€β”€ node-operations/ # Node operator specifications +β”œβ”€β”€ api/ # API specifications +β”œβ”€β”€ testing/ # Testing specifications +β”œβ”€β”€ implementation/ # Language-specific implementations +β”‚ β”œβ”€β”€ typescript/ # TypeScript implementation +β”‚ β”œβ”€β”€ rust/ # Rust implementation with Verus +β”‚ └── lean4/ # Lean4 formal verification +β”œβ”€β”€ schemas/ # Global schema definitions +β”œβ”€β”€ simulations/ # Economic and performance simulations +β”œβ”€β”€ governance/ # Protocol governance +└── website/ # Quartz website generation + β”œβ”€β”€ quartz.config.ts # Quartz configuration + β”œβ”€β”€ quartz.layout.ts # Site layout + └── content/ # Generated content +``` + +## Getting Started + +### Prerequisites + +- Nix with flakes enabled +- Node.js v22+ and npm v10.9.2+ (managed via Nix) +- Obsidian (optional, for editing) + +### Setup + +1. **Enter the development environment:** + + ```bash + nix develop + ``` + +2. **Initialize the website generation:** + + ```bash + cd website + npm install + npx quartz create + ``` + +3. **Start local development server:** + + ```bash + npx quartz build --serve + ``` + +4. **Open in Obsidian (optional):** + - Open Obsidian + - Open the `spec/` directory as a vault + - Install recommended plugins for better cross-linking + +### Working with the Specification + +- **Editing:** Use any Markdown editor or Obsidian for rich editing experience +- **Cross-linking:** Use `[[Note Name]]` syntax for internal links +- **Math:** Use LaTeX syntax `$inline$` or `$$block$$` +- **Code:** Use standard Markdown code blocks with language hints +- **Diagrams:** Use Mermaid syntax in code blocks + +### Building and Publishing + +```bash +# Build the static website +npx quartz build + +# Serve locally for testing +npx quartz build --serve + +# Deploy to GitHub Pages (when ready) +npx quartz sync --no-pull +``` + +## Implementation Languages + +### TypeScript + +- **Purpose:** Reference implementation and SDK +- **Testing:** Jest with comprehensive unit tests +- **Location:** `implementation/typescript/` + +### Rust (Verus) + +- **Purpose:** Performance-critical components with light formal verification +- **Testing:** Standard Rust testing + Verus verification +- **Location:** `implementation/rust/` + +### Lean4 + +- **Purpose:** Heavy formal verification and mathematical proofs +- **Testing:** Lean theorem proving +- **Location:** `implementation/lean4/` + +## Website Features + +The generated website includes: + +- **Full-text search** across all specification documents +- **Interactive graph view** showing relationships between concepts +- **Wikilink support** with hover previews +- **LaTeX rendering** for mathematical expressions +- **Syntax highlighting** for code blocks +- **Mobile-responsive** design +- **Dark/light mode** support + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes following the specification structure +4. Ensure all implementations pass their respective tests +5. Update cross-links and documentation +6. Submit a pull request + +## License + +This specification is licensed under [LICENSE TO BE DETERMINED]. + +--- + +For detailed technical specifications, start with [[Core Architecture Overview]] or browse the [[Index]] of all specification documents. diff --git a/spec/content/index.md b/spec/content/index.md new file mode 100644 index 0000000000..efa10b0aa1 --- /dev/null +++ b/spec/content/index.md @@ -0,0 +1,58 @@ +--- +title: 'Blocksense Protocol Specification' +description: 'Complete technical specification for the Blocksense Protocol - a universal verification layer for Web3 and Web2' +tags: ['protocol', 'specification', 'blocksense'] +--- + +# Blocksense Protocol Specification + +Welcome to the complete technical specification for the Blocksense Protocol. This specification serves as an executable reference implementation with formal verification, designed to be the authoritative source for understanding and implementing the Blocksense system. + +## Overview + +Blocksense is a universal verification layer that solves two fundamental barriers in blockchain technology: + +1. **The Connectivity Barrier** - Secure integration with real-world data and computation +2. **The Throughput Barrier** - Boundless scalability through parallel architecture + +## Navigation + +### Core Protocol + +- [[Core Architecture Overview]] - High-level system design +- [[zkSchellingCoin Consensus]] - Bribery-resistant consensus mechanism +- [[DSMR Architecture]] - Decoupled State Machine Replication +- [[Cryptographic Primitives]] - ZK proofs, MPC, and signature schemes + +### Data Feeds & Oracles + +- [[Oracle Scripts]] - WebAssembly-based data feed creation +- [[Intersubjective Consensus]] - Resolving subjective truths +- [[Data Aggregation]] - Multi-source data combination algorithms + +### Implementation + +- [[TypeScript Implementation]] - Reference implementation and SDK +- [[Rust Implementation]] - Performance-critical components with Verus +- [[Lean4 Verification]] - Formal mathematical proofs + +### Smart Contracts + +- [[ADFS Architecture]] - Aggregated Data Feed Store +- [[Chainlink Compatibility]] - Drop-in replacement layer +- [[Cross-Chain Bridges]] - Multi-chain deployment + +## Getting Started + +1. **For Protocol Developers**: Start with [[Core Architecture Overview]] +2. **For Oracle Builders**: Begin with [[Oracle Scripts]] +3. **For Smart Contract Integrators**: See [[ADFS Integration Guide]] +4. **For Node Operators**: Review [[Node Operations]] + +## Contributing + +This specification is maintained as a living document. See [[Contributing Guidelines]] for how to propose changes and improvements. + +--- + +_This specification is published at [specification.blocksense.network](https://specification.blocksense.network) and maintained in the [Blocksense monorepo](https://github.com/blocksense-network/blocksense)._ diff --git a/spec/package.json b/spec/package.json new file mode 100644 index 0000000000..0f415ef332 --- /dev/null +++ b/spec/package.json @@ -0,0 +1,12 @@ +{ + "name": "blocksense-specification", + "version": "1.0.0", + "description": "Blocksense Protocol Specification", + "type": "module", + "scripts": { + "build": "quartz build", + "serve": "quartz build --serve" + }, + "dependencies": {}, + "devDependencies": {} +} diff --git a/spec/quartz.config.ts b/spec/quartz.config.ts new file mode 100644 index 0000000000..b81f874db2 --- /dev/null +++ b/spec/quartz.config.ts @@ -0,0 +1,84 @@ +import type { QuartzConfig } from 'quartz/cfg'; +import * as Plugin from 'quartz/plugins'; + +const config: QuartzConfig = { + configuration: { + pageTitle: 'Blocksense Protocol Specification', + enableSPA: true, + enablePopovers: true, + analytics: { provider: 'plausible' }, + locale: 'en-US', + baseUrl: 'specification.blocksense.network', + ignorePatterns: ['private', 'templates', '.obsidian'], + defaultDateType: 'created', + theme: { + fontOrigin: 'googleFonts', + cdnCaching: true, + typography: { + header: 'Inter', + body: 'Source Sans Pro', + code: 'IBM Plex Mono', + }, + colors: { + lightMode: { + light: '#fafafa', + lightgray: '#e5e7eb', + gray: '#9ca3af', + darkgray: '#374151', + dark: '#111827', + secondary: '#3b82f6', + tertiary: '#06b6d4', + highlight: 'rgba(59, 130, 246, 0.15)', + }, + darkMode: { + light: '#0f172a', + lightgray: '#1e293b', + gray: '#64748b', + darkgray: '#e2e8f0', + dark: '#f8fafc', + secondary: '#60a5fa', + tertiary: '#22d3ee', + highlight: 'rgba(96, 165, 250, 0.15)', + }, + }, + }, + }, + plugins: { + transformers: [ + Plugin.FrontMatter(), + Plugin.CreatedModifiedDate({ priority: ['frontmatter', 'filesystem'] }), + Plugin.Latex({ renderEngine: 'katex' }), + Plugin.SyntaxHighlighting({ + theme: { + light: 'github-light', + dark: 'github-dark', + }, + keepBackground: false, + }), + Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }), + Plugin.GitHubFlavoredMarkdown(), + Plugin.TableOfContents(), + Plugin.CrawlLinks({ markdownLinkResolution: 'shortest' }), + Plugin.Description(), + ], + filters: [Plugin.RemoveDrafts()], + emitters: [ + Plugin.AliasRedirects(), + Plugin.ComponentResources(), + Plugin.ContentPage(), + Plugin.FolderPage(), + Plugin.TagPage(), + Plugin.ContentIndex({ + enableSiteMap: true, + enableRSS: true, + rssTitle: 'Blocksense Protocol Specification Updates', + rssFullHtml: true, + }), + Plugin.Assets(), + Plugin.Static(), + Plugin.NotFoundPage(), + ], + }, +}; + +export default config; diff --git a/spec/quartz.layout.ts b/spec/quartz.layout.ts new file mode 100644 index 0000000000..cf7cf0c997 --- /dev/null +++ b/spec/quartz.layout.ts @@ -0,0 +1,51 @@ +import type { PageLayout, SharedLayout } from 'quartz/cfg'; +import * as Component from 'quartz/components'; + +export const sharedPageComponents: SharedLayout = { + head: Component.Head(), + header: [], + footer: Component.Footer({ + links: { + GitHub: 'https://github.com/blocksense-network/blocksense', + 'Blocksense Network': 'https://blocksense.network', + Documentation: 'https://docs.blocksense.network', + }, + }), +}; + +export const defaultContentPageLayout: PageLayout = { + beforeBody: [ + Component.Breadcrumbs(), + Component.ArticleTitle(), + Component.ContentMeta(), + Component.TagList(), + ], + left: [ + Component.PageTitle(), + Component.MobileOnly(Component.Spacer()), + Component.Search(), + Component.Darkmode(), + Component.DesktopOnly(Component.Explorer()), + ], + right: [ + Component.Graph(), + Component.DesktopOnly(Component.TableOfContents()), + Component.Backlinks(), + ], +}; + +export const defaultListPageLayout: PageLayout = { + beforeBody: [ + Component.Breadcrumbs(), + Component.ArticleTitle(), + Component.ContentMeta(), + ], + left: [ + Component.PageTitle(), + Component.MobileOnly(Component.Spacer()), + Component.Search(), + Component.Darkmode(), + Component.DesktopOnly(Component.Explorer()), + ], + right: [], +}; diff --git a/spec/quartz/build.ts b/spec/quartz/build.ts new file mode 100644 index 0000000000..8500bfc938 --- /dev/null +++ b/spec/quartz/build.ts @@ -0,0 +1,91 @@ +import type { QuartzConfig } from 'quartz/cfg'; +import * as Plugin from 'quartz/plugins'; + +/** + * Quartz 4.0 Configuration + * + * See https://quartz.jzhao.xyz/configuration for more information. + */ +const config: QuartzConfig = { + configuration: { + pageTitle: 'Blocksense Protocol Specification', + enableSPA: true, + enablePopovers: true, + analytics: { provider: 'plausible' }, + locale: 'en-US', + baseUrl: 'specification.blocksense.network', + ignorePatterns: ['private', 'templates', '.obsidian'], + defaultDateType: 'created', + theme: { + fontOrigin: 'googleFonts', + cdnCaching: true, + typography: { + header: 'Inter', + body: 'Source Sans Pro', + code: 'IBM Plex Mono', + }, + colors: { + lightMode: { + light: '#fafafa', + lightgray: '#e5e7eb', + gray: '#9ca3af', + darkgray: '#374151', + dark: '#111827', + secondary: '#3b82f6', + tertiary: '#06b6d4', + highlight: 'rgba(59, 130, 246, 0.15)', + }, + darkMode: { + light: '#0f172a', + lightgray: '#1e293b', + gray: '#64748b', + darkgray: '#e2e8f0', + dark: '#f8fafc', + secondary: '#60a5fa', + tertiary: '#22d3ee', + highlight: 'rgba(96, 165, 250, 0.15)', + }, + }, + }, + }, + plugins: { + transformers: [ + Plugin.FrontMatter(), + Plugin.CreatedModifiedDate({ + priority: ['frontmatter', 'filesystem'], + }), + Plugin.Latex({ renderEngine: 'katex' }), + Plugin.SyntaxHighlighting({ + theme: { + light: 'github-light', + dark: 'github-dark', + }, + keepBackground: false, + }), + Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }), + Plugin.GitHubFlavoredMarkdown(), + Plugin.TableOfContents(), + Plugin.CrawlLinks({ markdownLinkResolution: 'shortest' }), + Plugin.Description(), + ], + filters: [Plugin.RemoveDrafts()], + emitters: [ + Plugin.AliasRedirects(), + Plugin.ComponentResources(), + Plugin.ContentPage(), + Plugin.FolderPage(), + Plugin.TagPage(), + Plugin.ContentIndex({ + enableSiteMap: true, + enableRSS: true, + rssTitle: 'Blocksense Protocol Specification Updates', + rssFullHtml: true, + }), + Plugin.Assets(), + Plugin.Static(), + Plugin.NotFoundPage(), + ], + }, +}; + +export default config; diff --git a/yarn.lock b/yarn.lock index dc670f173e..8f6b893e3c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1890,6 +1890,12 @@ __metadata: languageName: unknown linkType: soft +"@blocksense/specification-website@workspace:spec/website": + version: 0.0.0-use.local + resolution: "@blocksense/specification-website@workspace:spec/website" + languageName: unknown + linkType: soft + "@blocksense/ui@workspace:*, @blocksense/ui@workspace:libs/ts/ui": version: 0.0.0-use.local resolution: "@blocksense/ui@workspace:libs/ts/ui" From 5ba178d143a86663161f2b69ac5ccd8f1db0aa0e Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Tue, 12 Aug 2025 15:48:37 +0300 Subject: [PATCH 3/8] docs(spec): Add raw non-obsidial-ready markdown files on various topics --- ..._ Integrating Intersubjective Consensus.md | 77 +++++ ...DK Documentation_ Object Ownership APIs.md | 127 +++++++++ ...ntation_ Predictable Address Allocation.md | 61 ++++ ...nse SDK Documentation_ The Object Model.md | 79 +++++ ...SDK Documentation_ The `blocksense` CLI.md | 219 ++++++++++++++ ...sting, Concurrency, and Pricing Markets.md | 112 ++++++++ ...Oracle Service Lifecycle & Storage APIs.md | 79 +++++ ...ion with Trusted Execution Environments.md | 31 ++ ...cksense Software Component Architecture.md | 109 +++++++ ...or the Universal Verification Layer (1).md | 246 ++++++++++++++++ ...Passkey-Based Wallet Discovery Standard.md | 269 ++++++++++++++++++ ...sense Execution Layer_ Design Rationale.md | 123 ++++++++ ...esign Rationale for a Resilient Mempool.md | 71 +++++ 13 files changed, 1603 insertions(+) create mode 100644 spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md create mode 100644 spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md create mode 100644 spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md create mode 100644 spec/content/Blocksense SDK Documentation_ The Object Model.md create mode 100644 spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md create mode 100644 spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md create mode 100644 spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md create mode 100644 spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md create mode 100644 spec/content/Blocksense Software Component Architecture.md create mode 100644 spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md create mode 100644 spec/content/Passkey-Based Wallet Discovery Standard.md create mode 100644 spec/content/The Blocksense Execution Layer_ Design Rationale.md create mode 100644 spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md diff --git a/spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md b/spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md new file mode 100644 index 0000000000..6cb981f714 --- /dev/null +++ b/spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md @@ -0,0 +1,77 @@ +# **Blocksense Architecture: Integrating Intersubjective Consensus** + +## **1\. Introduction: Bridging Two Worlds of Truth** + +The Blocksense network is uniquely designed to process both objective truths (computations with deterministic outcomes) and intersubjective truths (consensus on external information).1 The power of the network lies not just in handling these two domains, but in seamlessly and verifiably integrating them. The results from the + +**Intersubjective Truth Machine**, powered by zkSchellingCoin, must be woven into the state of the **Boundless Throughput Engine** with the same mathematical certainty as any other state transition.1 + +This is achieved by ensuring that the final result of any zkSchellingCoin consensus is accompanied by a ZK proof that attests to the correct and impartial tallying of votes. This "consensus proof" is a first-class object that can be processed by the Execution Layer, creating a trustless bridge between the two layers. This integration happens through two primary mechanisms: regularly scheduled data feeds and on-demand requests from on-chain programs. + +## **2\. Mechanism 1: Scheduled Data Feeds** + +Scheduled data feeds are the backbone of Blocksense's oracle services, providing regular, automated updates for information like asset prices. The process is designed for efficiency, censorship resistance, and verifiable correctness. + +### **2.1. Vote Submission and Collection** + +For any given data feed, a secret sub-committee of reporters is selected to vote on the outcome.1 + +1. **Vote Casting:** Shortly before a scheduled publication time, each reporter in the committee submits their encrypted vote as a standard transaction. +2. **Censorship Resistance:** These vote transactions are processed by the Ordering Layer's parallel DAG mempool, which guarantees their inclusion and ordering in a censorship-resistant manner.1 +3. **On-Chain Aggregation:** A simple, low-cost Objective Program, specific to the data feed, is executed. Its sole function is to receive the ordered votes and append them to a dedicated on-chain list, creating a public, immutable record of all submitted (but still encrypted) votes for that round. + +### **2.2. The Coordinator's Role: Tallying and Proving** + +Once the voting window closes, the responsibility shifts to a set of distributed **Coordinators**. Their role is to tally the votes and prove the correctness of the result, drawing heavily on the principles of the MACI protocol to ensure privacy and collusion resistance. + +1. **Execution of Tallying Circuit:** A Coordinator executes a specialized ZK circuit. This circuit takes the on-chain list of encrypted votes as a public input. +2. **Private Tallying:** Using a shared secret known only to the voters and the coordinator, the circuit decrypts the votes _inside the ZK environment_. It then applies the data feed's specified aggregation logic (e.g., median, trimmed mean) to the decrypted votes to compute a final result. +3. **Proof Generation:** The circuit outputs two things: the final aggregated result and a succinct ZK proof. This proof attests that the tallying process was performed correctly on the exact set of on-chain votes, without revealing the individual votes themselves. + +If a Coordinator fails to submit this proof within the designated time, their stake is slashed, ensuring high liveness for the system. + +### **2.3. Publication, Routing, and Cross-Chain Delivery** + +The final result is propagated through the system and delivered to external networks. + +1. **Publication to Routing Table:** The Coordinator submits a transaction containing the final result and the tallying proof. A core system contract on the Execution Layer verifies this proof. If valid, the result is written to a special, system-wide **Routing Table**. This table acts as a central, verifiable source of truth for all oracle data. +2. **Cross-Chain Aggregation:** A separate, permissionless relayer network monitors the Routing Table. When a new value is published, the relayer identifies which target networks (e.g., Ethereum, Solana) are subscribed to that data feed. +3. **ADFS Payload Generation:** The relayer bundles all pending updates for a specific target network into a single payload, formatting it according to the data structure required by that chain's **Aggregated Data Feed Store (ADFS)** contract.1 +4. **Final Proof for Target Chain:** The relayer generates a final ZK proof that attests to the correct bundling and formatting of this ADFS payload. This proof, along with the payload, is submitted to the target chain. The on-chain ADFS contract only needs to perform a single, inexpensive ZK proof verification to accept thousands of data updates simultaneously, providing unparalleled cost efficiency.1 + +## **3\. Mechanism 2: On-Demand Requests and the Task Manifest Pattern** + +While scheduled feeds are efficient for continuous data, many applications require a response to a specific, one-time query. This is handled by a powerful and generalized request/response mechanism using the **Task Manifest** pattern. + +### **3.1. The Task Manifest Object** + +When an Objective Program needs to trigger a new verifiable computation, it does not call the system directly. Instead, it instantiates a special, temporary **Task Manifest Object**. This object acts as a dedicated coordination point for the request and defines its parameters: + +- The specific data or computation being requested. +- The deadline for receiving a valid response. +- The address of a **callback program** to be executed upon successful completion. +- A **verifier program**, which is a circuit or TEE verifier responsible for validating the response. + +### **3.2. Request and Callback Workflow** + +1. **Instantiation:** An Objective Program creates a Task Manifest Object, funding it with the necessary fees to pay for the service. +2. **Service Execution and Proof Generation:** The appropriate off-chain service (e.g., a zkSchellingCoin Coordinator, a ZK Prover, a 3D rendering farm) performs the requested computation and generates a proof of its work. +3. **Response Submission:** The service provider submits the result and its corresponding proof directly to the Task Manifest Object. +4. **Response Verification:** The Task Manifest Object invokes its designated verifier program. This verifier is chosen based on the nature of the task: + - For a **zkSchellingCoin** request, the verifier is a ZK circuit that checks the Coordinator's tallying proof. + - For a **3D rendering** job, the verifier would likely be a program that checks a **TEE attestation**, confirming that a specific, audited rendering software was run in a secure enclave. +5. **Callback Execution:** If the response is successfully verified before the deadline, the Task Manifest Object triggers the execution of the specified callback program. It passes the final, verified result directly to this program as an input argument. This replaces the need for a global routing table, delivering the result precisely where it is needed. + +## **4\. A General-Purpose Primitive for Verifiable Computation** + +The on-demand request/response mechanism is a fundamental primitive of the Blocksense service-oriented architecture, extending far beyond simple data oracles.1 The "Task Manifest" pattern can be used to create on-chain markets for any kind of verifiable computation: + +- **zkSchellingCoin Consensus:** A dApp can request a one-time consensus on a complex event, like the outcome of a prediction market. +- **ZK Proof Generation Market:** A dApp can create a Task Manifest with a request to generate a complex ZK proof for a large computation. The verifier program in the manifest would be the verifier circuit for the requested proof. +- **TEE-Verified Computation:** A metaverse application could request a high-fidelity 3D render of a scene, with the verifier program configured to accept only results accompanied by a valid TEE attestation. + +In every case, the Task Manifest Object acts as a trustless escrow and verifier, ensuring that payment is only released for correctly completed work, as validated by the appropriate proof. This makes the Blocksense network an extensible, universally verifiable platform for a new generation of decentralized services. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf diff --git a/spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md b/spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md new file mode 100644 index 0000000000..b8ce6253ea --- /dev/null +++ b/spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md @@ -0,0 +1,127 @@ +# **Blocksense SDK Documentation: Object Ownership APIs** + +This document provides a technical reference for the Blocksense Noir APIs used to create and manage on-chain objects. These functions are part of the Blocksense Noir standard library and provide the low-level primitives for interacting with the network's object-centric storage model. + +A solid understanding of the object model is recommended before using these APIs. + +## **Defining an Object** + +In Blocksense Noir, an object is a struct that has the key ability. The first field of the struct must be id: UID, which serves as the object's globally unique identifier on the network. 1 + +Rust + +// Example of a simple object definition +struct MyObject { +id: UID, +value: u64, +} + +## **Core Object Functions** + +These functions are available within the blocksense::object module and are used for creating and managing the state of objects. + +### **object::new** + +Creates a new, mutable object owned by a specific address. + +**Signature:** + +Rust + +fn new\(owner: Address) \-\> T + +**Description:** + +This function is called within a constructor or another function to instantiate a new object. The owner parameter specifies the address that will have exclusive control over the object. The newly created object is mutable by default. + +**Example:** + +Rust + +// Creates a new MyObject owned by the transaction sender +let new_object \= MyObject { +id: object::new(context.sender()), +value: 100, +}; + +### **object::share** + +Transitions an object from an owned state to a shared state, making it accessible to multiple users. + +**Signature:** + +Rust + +fn share\(object: T) + +**Description:** + +A shared object does not have a single owner and can be read or modified by anyone (subject to the program's logic). This action is **irreversible**. Once an object is shared, it cannot become owned again. Use this for objects that represent collaborative state, like a liquidity pool. + +**Example:** + +Rust + +// Takes an owned object and makes it shared +let my_owned_object \= MyObject {... }; +object::share(my_owned_object); + +### **object::freeze** + +Makes an object immutable, preventing any future modifications to its state. + +**Signature:** + +Rust + +fn freeze\(object: T) + +**Description:** + +A frozen object is guaranteed to be read-only for the rest of its existence. This is useful for publishing data that should never change, such as program code modules or on-chain certificates. This action is **irreversible**. 2 + +**Example:** + +Rust + +// Takes an object and makes it immutable +let my_object \= MyObject {... }; +object::freeze(my_object); + +## **Transferring Objects** + +These functions are available within the blocksense::transfer module and are used to change the ownership of objects. + +### **transfer::public_transfer** + +Transfers an owned object from its current owner to a new recipient address. + +**Signature:** + +Rust + +fn public_transfer\(object: T, recipient: Address) + +**Description:** + +This is the standard function for transferring ownership of an object. For an object to be transferable using this function, its defining struct must have both the key and store abilities. 1 This ensures that only objects explicitly marked as transferable can have their ownership changed. + +**Example:** + +Rust + +// Define a transferable object +struct TransferableNFT { +id: UID, +metadata_url: String, +} has key, store + +// In a function, transfer the NFT to a new owner +public fn transfer_nft(nft: TransferableNFT, new_owner: Address) { +transfer::public_transfer(nft, new_owner); +} + +#### **Works cited** + +1. Sui Object | Reference \- The Move Book, accessed July 31, 2025, [https://move-book.com/reference/abilities/object/](https://move-book.com/reference/abilities/object/) +2. sui-foundation/sui-object-model-workshop \- GitHub, accessed July 31, 2025, [https://github.com/sui-foundation/sui-object-model-workshop](https://github.com/sui-foundation/sui-object-model-workshop) diff --git a/spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md b/spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md new file mode 100644 index 0000000000..2a81b36d4d --- /dev/null +++ b/spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md @@ -0,0 +1,61 @@ +# **Blocksense SDK Documentation: Predictable Address Allocation** + +A core design goal of Blocksense is to provide a seamless and intuitive experience for both users and developers. A key part of this is moving beyond the cryptic, randomly generated addresses common in many blockchains. Predictable addresses are essential for user-friendly onboarding, enabling dApps to pre-calculate user accounts and for developers to build composable systems where program instances can reliably discover one another. + +This document outlines the deterministic mechanisms Blocksense uses to create predictable addresses for both user accounts and stateful program instances. + +## **1\. Onboarding Users with Predictable Addresses** + +In Blocksense, a user's account is a programmable user object. The address of this object is not random; it is deterministically derived from the inputs used to create it. + +### **1.1. The create_user Operation** + +The fundamental operation for creating a new account is create_user. Its signature is: + +create_user(validity_window, identity_service, public_bytes, authorization_data, salt) + +The public address of the resulting user object is a cryptographic hash derived from a combination of these inputs: + +- identity_service: The address of the initial Identity Service that will manage the account. +- public_bytes: The public data (e.g., a public key) associated with the user for this initial service. +- authorization_data: The proof that the user has authorized this creation via the identity_service. +- salt: A user-provided nonce to ensure uniqueness. + +Because the output address is a deterministic function of these inputs, anyone can pre-calculate a user's address before the create_user transaction is ever submitted to the network. + +### **1.2. The Bootstrapping Pattern for User-Friendly Onboarding** + +While the create_user operation is deterministic, a user's ultimate IdentityService might be complex or based on personal credentials (like a Passkey) that are not known in advance. To solve this, Blocksense enables a powerful **bootstrapping pattern** that combines predictability with flexibility. + +This is a two-step process: + +1. **Initial Creation with a Bootstrapper:** A dApp or user initiates the process by calling create_user with a well-known, public **bootstrapping IdentityService**. This is a simple, often permissionless, service whose address is constant. By using this known service and a predictable salt (e.g., derived from the user's email or social handle), the dApp can generate a predictable address for the new user. This create_user transaction can be sponsored by the dApp, providing a completely frictionless onboarding experience where the user is not required to hold any tokens. +2. **Immediate Security Upgrade:** The newly created user object is now live on the network at its predictable address. In the very next step, the user calls change_identity_service. This operation allows them to switch control of their account from the generic bootstrapping service to their own desired IdentityService (e.g., one that is controlled by their device's Passkey). + +This pattern provides the best of both worlds: the user gets a predictable, human-friendly address that can be shared easily, while immediately upgrading to a high-security, personalized account manager without ever being locked into the initial bootstrapping service. + +## **2\. Deploying Programs with Predictable Addresses** + +A similar deterministic approach applies to deploying Objective Programs (ZK circuits). The process involves two distinct phases: deploying the immutable code and then creating a stateful instance of it. + +### **2.1. Deploying a Module** + +First, the immutable program logic is deployed to the network using the deploy_module operation: + +deploy_module(program_bytes) + +This operation creates a frozen, system-owned object containing the compiled program bytecode. The address of this module is simply the cryptographic hash of the program_bytes. This ensures that identical code always results in the same on-chain module address, making program logic verifiable and content-addressable. + +### **2.2. Creating a Program Instance** + +Once a module is deployed, developers can create stateful, mutable instances of it using the create_instance operation: + +create_instance(module_address, salt) + +The address of the new program instance is deterministically derived from a combination of three inputs: + +1. The address of the **caller** of the create_instance function. +2. The module_address of the program code being instantiated. +3. A developer-provided salt for uniqueness. + +This mechanism allows developers to predictably calculate the addresses of smart contracts before they are deployed. This is crucial for building complex, multi-contract systems where contracts need to know each other's addresses at the time of deployment to function correctly. For example, a token contract can be deployed with the pre-calculated address of its corresponding liquidity pool, ensuring they are correctly linked from genesis. diff --git a/spec/content/Blocksense SDK Documentation_ The Object Model.md b/spec/content/Blocksense SDK Documentation_ The Object Model.md new file mode 100644 index 0000000000..4b7cd22878 --- /dev/null +++ b/spec/content/Blocksense SDK Documentation_ The Object Model.md @@ -0,0 +1,79 @@ +# **Blocksense SDK Documentation: The Object Model & Parallel Execution** + +A core innovation of the Blocksense network, and the key to its "Boundless Throughput Engine," is its state architecture.1 Unlike traditional blockchains that rely on an account-based model, Blocksense employs an + +**object-centric model** inspired by the design of the Sui blockchain.2 + +This design fundamentally changes how the network processes transactions, moving away from a sequential bottleneck to a massively parallel execution environment. Understanding this model is crucial for developers, as the way you structure your application's state directly impacts its performance and scalability on Blocksense. + +## **The Problem with Sequential Execution** + +Most blockchains, such as Ethereum, use an account-based model where the entire state of the network is represented as a single, large data structure.3 Smart contracts are accounts that hold code and data, and transactions modify this global state. + +This model has a significant drawback: to prevent conflicts (like double-spending), transactions must be processed sequentially, one after another, and ordered into blocks.4 This creates a global queue where every transaction, regardless of what it's doing, has to wait its turn. This sequential processing is a primary cause of the throughput limitations and high fees seen on many networks.5 + +## **The Blocksense Solution: A World of Objects** + +Blocksense's state is not a single ledger but a collection of individual, programmable **objects**.2 An object is the basic unit of storage and can represent anything: a token, an NFT, a smart contract, or a complex data structure.4 + +Each object has a globally unique ID and metadata that defines its properties and, most importantly, its **ownership**. This explicit declaration of ownership is the key that unlocks parallel execution.7 + +### **Types of Object Ownership** + +There are three primary ownership categories for objects in Blocksense: + +1. **Owned Objects:** An object that is owned by a single external address (a user account). Only the owner can initiate a transaction that modifies this object. The vast majority of assets, such as a user's tokens or NFTs, are owned objects. +2. **Shared Objects:** An object that has no specific owner and can be read or modified by any user. Shared objects are the mechanism for creating collaborative applications where multiple users need to interact with the same state, such as a decentralized exchange's liquidity pool or an on-chain auction contract. +3. **Immutable Objects (Frozen):** An object that cannot be modified by anyone after it has been published. Smart contract packages (the code itself) are a prime example of immutable objects.3 + +## **How the Object Model Enables Parallel Execution** + +The power of the object model lies in making data dependencies explicit. Every transaction must declare upfront which objects it will access and how (read-only or read-write). This allows the Blocksense network to analyze the dependencies of all incoming transactions _before_ executing them.2 + +The execution logic is simple but powerful: + +- **If two transactions do not access any of the same objects, they are causally independent and can be executed in parallel without any possibility of conflict**.2 +- **If two transactions only read from the same immutable or shared object, they can also be executed in parallel**. +- **Only when two or more transactions attempt to _modify_ the same shared object is there a data conflict**. In this case, and only in this case, the network must order these specific transactions to ensure a deterministic outcome.4 + +This approach is a paradigm shift from the **total ordering** of traditional blockchains to a more efficient **causal ordering**.10 Instead of ordering everything, Blocksense only orders the small subset of transactions that actually have conflicting dependencies. + +### **The "Simulation-First" Pipeline** + +This principle is put into practice by Blocksense's "Simulation-First Parallel Pipeline".1 + +1. **Dependency Analysis:** The network receives a set of transactions and immediately analyzes their declared object dependencies. +2. **Parallel Simulation:** "Simulator" nodes attempt to execute all causally independent transactions in parallel. Since most transactions in a typical workload (e.g., peer-to-peer payments, NFT transfers) involve only owned objects, they can be processed concurrently with near-zero conflict.7 +3. **Conflict Resolution:** If a conflict is detected on a shared object, one of the conflicting transactions is simply postponed to the next execution batch. This process is extremely fast and efficient.1 + +## **Benefits for Scalability and Developers** + +This architecture provides transformative benefits for both network performance and the developer experience. + +### **For Scalability:** + +- **Massive Throughput:** By breaking the sequential bottleneck, Blocksense's throughput can scale horizontally with the addition of more CPU cores to validator nodes. This allows the network to achieve extremely high transactions per second (TPS), capable of supporting enterprise-grade applications.5 +- **Low Latency & Near-Instant Finality:** Simple transactions involving only owned objects (e.g., transferring a token to a friend) do not require complex consensus. They can be validated and finalized almost instantly, providing a user experience comparable to Web2 applications.6 +- **Reduced Network Congestion:** Because independent transactions don't have to wait for each other, the network is far more resilient to congestion, leading to more stable and predictable transaction fees.5 + +### **For Developers:** + +- **Fine-Grained State Management:** The object model gives developers precise control over their application's state. You can design complex systems as compositions of independent objects, which is often a more intuitive and secure way to model digital assets.2 +- **Performance by Design:** The model encourages developers to think about state contention. By architecting applications to minimize the use of shared objects, you can directly build more scalable and performant dApps. For example, a game might represent each player's inventory as an owned object and only use a shared object for a global leaderboard, ensuring that most in-game actions can be processed in parallel. +- **Enhanced Security:** The Move language, combined with the object model, provides strong ownership and access control guarantees at the language level, preventing entire classes of common smart contract vulnerabilities like reentrancy attacks.4 + +By embracing the object-centric paradigm, Blocksense provides a foundation for a new generation of decentralized applications that are not constrained by the performance limitations of the past. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +2. Building on Sui Blockchain | Here's What You Need to Know, accessed July 31, 2025, [https://blockchain.oodles.io/blog/sui-blockchain/](https://blockchain.oodles.io/blog/sui-blockchain/) +3. Object Model \- Sui Documentation, accessed July 31, 2025, [https://docs.sui.io/concepts/object-model](https://docs.sui.io/concepts/object-model) +4. SUI Deep Dive: Understanding Its Object-Centric Design and ..., accessed July 31, 2025, [https://medium.com/@lucasfada93/sui-deep-dive-understanding-its-object-centric-design-and-parallel-processing-49cb6beda183](https://medium.com/@lucasfada93/sui-deep-dive-understanding-its-object-centric-design-and-parallel-processing-49cb6beda183) +5. All About Parallelization \- The Sui Blog, accessed July 31, 2025, [https://blog.sui.io/parallelization-explained/](https://blog.sui.io/parallelization-explained/) +6. What is Sui Network? (SUI) How it works, who created it and how it is used | Kraken, accessed July 31, 2025, [https://www.kraken.com/learn/what-is-sui-network-sui](https://www.kraken.com/learn/what-is-sui-network-sui) +7. Sui Blockchain: A Deep Dive \- Stakin, accessed July 31, 2025, [https://stakin.com/blog/sui-blockchain-a-deep-dive](https://stakin.com/blog/sui-blockchain-a-deep-dive) +8. SUI, Aptos, and Vara: A Parallelization Comparison | by Vara Network \- Medium, accessed July 31, 2025, [https://medium.com/@VaraNetwork/sui-aptos-and-vara-a-parallelisation-comparison-b36f9ef84e46](https://medium.com/@VaraNetwork/sui-aptos-and-vara-a-parallelisation-comparison-b36f9ef84e46) +9. What Is the Sui Network and How Does It Work? | Omar Faruk777 on ..., accessed July 31, 2025, [https://www.binance.com/en/square/post/21140617778929](https://www.binance.com/en/square/post/21140617778929) +10. A deep dive into Sui's unique architecture, key features, and advantages over traditional blockchains \- CoinTranscend, accessed July 31, 2025, [https://www.cointranscend.com/a-deep-dive-into-suis-unique-architecture-key-features-and-advantages-over-traditional-blockchains/](https://www.cointranscend.com/a-deep-dive-into-suis-unique-architecture-key-features-and-advantages-over-traditional-blockchains/) +11. The SUI Network Explained | Mudrex Learn, accessed July 31, 2025, [https://mudrex.com/learn/the-sui-network-explained/](https://mudrex.com/learn/the-sui-network-explained/) diff --git a/spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md b/spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md new file mode 100644 index 0000000000..ec58f16049 --- /dev/null +++ b/spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md @@ -0,0 +1,219 @@ +# **Blocksense SDK Documentation: The blocksense CLI** + +Welcome to the official documentation for the blocksense command-line interface (CLI). This tool is the cornerstone of the Blocksense SDK, providing a unified and intuitive command center for the entire development lifecycleβ€”from project creation to on-chain deployment and upgrades. + +The blocksense CLI is designed to streamline the development of both Intersubjective Services (Oracle Services) and Objective Programs (ZK Circuits), abstracting away low-level complexities and enabling you to focus on building powerful, verified applications. + +## **Guiding Principles** + +The design of the blocksense CLI is guided by several core principles: + +- **Developer-Centricity:** Every command and option is designed to be intuitive, with clear and actionable feedback. +- **Unified Tooling:** A single, consistent interface (blocksense) manages all aspects of your project, preventing toolchain fragmentation. +- **Platform-Native Abstraction:** The CLI provides high-level commands that map directly to the powerful, unique features of the Blocksense network. +- **Uncompromising Security:** Secure defaults and best practices are integrated directly into the CLI's workflow. + +## **Global Options** + +These options can be used with any blocksense command. + +- \--help, \-h: Displays help information for the specified command. +- \--version, \-V: Displays the current version of the blocksense CLI. + +--- + +## **Command Reference** + +The following sections provide a detailed reference for each of the main blocksense commands. + +### **blocksense init** + +Initializes a new Blocksense project from a predefined or custom template. This command scaffolds a complete directory structure, including boilerplate code and configuration files, so you can start developing immediately. + +**Usage:** + +Bash + +blocksense init \ \ + +**Arguments:** + +- \: The name of the template to use. This can be one of the official templates or a URL to a custom Git repository. +- \: The name of the new directory to create for your project. + +**Official Templates:** + +- oracle-service-rust: A minimal "hello world" Intersubjective Service in Rust, including a basic query function and unit test. +- price-feed-oracle: A comprehensive price feed example demonstrating API fetching, advanced consensus models, and caching. +- objective-program-noir: A minimal ZK circuit project using Blocksense Noir, including a simple circuit and test case. 1 +- zk-identity-service: A template for building a custom, ZK-powered identity service, showcasing the authorize_user API. +- full-stack-dapp: A complete end-to-end example including an oracle service, an objective program, a frontend, and localnet configuration. + +**Output:** + +The init command generates a new directory containing the selected template's files and a central Blocksense.toml configuration file. This manifest is used to configure builds, tests, deployments, and local network settings. + +### **blocksense build** + +Compiles all components within a project directory into deployable artifacts. The command automatically detects whether to build an Intersubjective Service or an Objective Program based on the project's structure and configuration. + +**Usage:** + +Bash + +blocksense build + +**Arguments:** + +- \`\` (Optional): The path to the project or component to build. Defaults to the current directory. + +**Behavior:** + +- **For Intersubjective Services (Rust):** Invokes cargo with the correct wasm32-unknown-unknown target and release profile to produce an optimized .wasm file. +- **For Objective Programs (Noir):** Acts as a wrapper for the blocksense-noir compiler, using settings from Blocksense.toml and Prover.toml to generate the ACIR and ABI files. 1 +- **Dependency Check:** If the blocksense-noir compiler is required but not found in the system's PATH, the command will fail gracefully with a clear diagnostic message and installation instructions. + +### **blocksense run** + +Performs a single, one-off execution of a compiled oracle service or ZK circuit. This is useful for quick checks and debugging without deploying to a network. + +**Usage:** + +Bash + +blocksense run + +**Arguments:** + +- \`\` (Optional): The path to the project or component to run. Defaults to the current directory. If the project is not yet built, blocksense run will trigger a build first. + +**Output:** + +The command executes the program's main function (e.g., the query function for an oracle service) and prints the results and any logs directly to the terminal. + +### **blocksense test** + +Runs the complete test suite for a project, including unit tests for individual components and end-to-end integration tests. + +**Usage:** + +Bash + +blocksense test + +**Behavior:** + +- **Unit Tests:** Discovers and runs tests written for both Rust oracle services (\#\[test\]) and Noir circuits (\#\[test\]). +- **Integration Tests:** Can be configured to spin up an ephemeral instance of the localnet environment, deploy the project's programs, execute test scripts against them, and tear down the network upon completion. + +### **blocksense debug** + +Starts a debugging session using the integrated CodeTracer time-traveling debugger. 4 + +**Usage:** + +Bash + +blocksense debug + +**Arguments:** + +- \`\` (Optional): The path to the program to debug. Defaults to the current directory. + +**Behavior:** + +The command automates the debugging workflow: + +1. Compiles the target program with debug instrumentation. +2. Executes the program to generate a detailed execution trace. +3. Launches the CodeTracer UI with the trace file loaded. + +If the codetracer executable is not found in the system's PATH, the command will provide a helpful diagnostic message with a link to installation instructions. 7 + +### **blocksense deploy** + +Deploys compiled program artifacts to a specified Blocksense network. + +**Usage:** + +Bash + +blocksense deploy \--network \ + +**Options:** + +- \--network \: (Required) Specifies the target network (e.g., localnet, testnet, mainnet). Network details are configured in Blocksense.toml. + +**Behavior:** + +- **For Objective Programs:** Wraps the deploy_module system operation to publish the immutable program code. It can then interactively prompt to create a stateful instance via create_instance. +- **For Intersubjective Services:** Deploys the service's WASM bytecode to the Intersubjective Truth Machine, making it available for execution by oracle nodes. + +### **blocksense upgrade** + +Performs a standard upgrade on a deployed, mutable program instance. + +**Usage:** + +Bash + +blocksense upgrade \--network \ \ \ + +**Arguments:** + +- \: The on-chain ID of the mutable program instance to be upgraded. +- \: The address of the new program module to upgrade to. + +**Behavior:** + +Constructs and submits the upgrade transaction to the specified network after showing the user a confirmation summary. + +### **blocksense localnet** + +Manages the local simulation environment, which includes a Blocksense dev node and emulators for target networks like Ethereum. 8 + +**Usage:** + +Bash + +blocksense localnet \ + +**Subcommands:** + +- start: Starts the complete local network stack as defined in the orchestration configuration (Process Compose or Docker Compose). 9 + - \--fork \: (Optional) Starts the localnet in a "shadow fork" mode, cloning the state of a live public network from the specified JSON-RPC URL. 12 + - \--fork-block-number \: (Optional) Used with \--fork to pin the forked state to a specific block number, ensuring deterministic test runs. +- stop: Stops all services managed by the localnet. +- status: Displays the current status of all localnet services. + +### **blocksense account** + +Manages local accounts used for development and testing. + +**Usage:** + +Bash + +blocksense account \ + +**Subcommands:** + +- new: Creates a new keypair and saves it locally. +- list: Lists all locally managed accounts. +- balance \: Checks the balance of a specified account on a given network. + +#### **Works cited** + +1. Blocksense \- GitHub, accessed July 31, 2025, [https://github.com/blocksense-network](https://github.com/blocksense-network) +2. Noir is a domain specific language for zero knowledge proofs \- GitHub, accessed July 31, 2025, [https://github.com/noir-lang/noir](https://github.com/noir-lang/noir) +3. Noir Documentation, accessed July 31, 2025, [https://noir-lang.org/](https://noir-lang.org/) +4. CodeTracer \- Open Collective, accessed July 31, 2025, [https://opencollective.com/codetracer](https://opencollective.com/codetracer) +5. Introducing CodeTracer \- a time-travelling debugger built with Nim, for Nim., accessed July 31, 2025, [https://forum.nim-lang.org/t/12703](https://forum.nim-lang.org/t/12703) +6. CodeTracer \- Noir Release Demo \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=xZsJ55JVqmU](https://www.youtube.com/watch?v=xZsJ55JVqmU) +7. diadata-org/oracle-pallet \- GitHub, accessed July 31, 2025, [https://github.com/diadata-org/oracle-pallet](https://github.com/diadata-org/oracle-pallet) +8. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +9. Process management using process-compose-flake, accessed July 31, 2025, [https://community.flake.parts/process-compose-flake](https://community.flake.parts/process-compose-flake) +10. Process compose \- devenv, accessed July 31, 2025, [https://devenv.sh/supported-process-managers/process-compose/](https://devenv.sh/supported-process-managers/process-compose/) +11. How Compose works \- Docker Docs, accessed July 31, 2025, [https://docs.docker.com/compose/intro/compose-application-model/](https://docs.docker.com/compose/intro/compose-application-model/) +12. How To Fork Ethereum Mainnet with Hardhat | QuickNode Guides, accessed July 31, 2025, [https://www.quicknode.com/guides/ethereum-development/smart-contracts/how-to-fork-ethereum-mainnet-with-hardhat](https://www.quicknode.com/guides/ethereum-development/smart-contracts/how-to-fork-ethereum-mainnet-with-hardhat) +13. Forking other networks | Ethereum development environment for professionals by Nomic Foundation \- Hardhat, accessed July 31, 2025, [https://hardhat.org/hardhat-network/docs/guides/forking-other-networks](https://hardhat.org/hardhat-network/docs/guides/forking-other-networks) diff --git a/spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md b/spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md new file mode 100644 index 0000000000..74f07d3cbd --- /dev/null +++ b/spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md @@ -0,0 +1,112 @@ +# **Blocksense SDK: Oracle Service Costing, Concurrency, and Pricing Markets** + +The Blocksense network is designed as a global, unified marketplace for verified computation.1 For this marketplace to function efficiently and fairly, the "cost" of any computation must be measured objectively and transparently. This principle is central to the design of Intersubjective Services (Oracle Services). + +This document details how the Blocksense runtime measures the cost of oracle execution, how developers can define custom cost metrics for complex tasks, and how these mechanisms create a competitive pricing market for oracle services. + +## **1\. Objective Cost Measurement** + +To prevent subjective or hardware-dependent pricing, Blocksense employs a multi-faceted approach to resource measurement. The final "cost" of an oracle query is a combination of its intrinsic computational work and any external resources it consumes. + +### **1.1. Intrinsic Cost: WebAssembly Metering** + +Every oracle service runs within a sandboxed WebAssembly (WASM) runtime on the Blocksense node. This runtime is instrumented to meticulously track the resources consumed during each query invocation. The primary metrics are: + +- **Retired Instructions:** The total number of WASM instructions executed. This is a hardware-agnostic measure of pure computational effort. +- **Memory Used:** The amount of memory consumed by the WebAssembly module during execution. +- **Internet Bandwidth:** The volume of data transferred over the network (e.g., for API calls). + +These intrinsic costs are measured automatically by the runtime for every execution. When a Blocksense node reports the result of an oracle query, it reports these measured costs alongside the result. The Schelling point consensus mechanism then applies to both the data result and the reported cost, incentivizing all nodes to report these objective measurements honestly.1 + +### **1.2. Extensible Cost: External Programs and Custom Units** + +Many advanced oracle services rely on external programs to perform specialized tasks. Blocksense allows an oracle service to declare a dependency on such an external program, which is identified by its content hash. + +The critical requirement is that this external program **must produce an objective, hardware-independent measure of its own "cost."** This is not a measure of time, but a deterministic unit relevant to the task. Examples include: + +- **Gas:** For a program that simulates an EVM transaction. +- **Input and Output Tokens:** For a service that queries a large language model.1 +- **Software Counters:** Any custom, deterministic counter defined by the program's logic. + +The Blocksense node executes this external program, collects the cost measurement it produces, and reports this value as part of the total cost for the oracle query. This allows the Blocksense economic model to transparently price and reward arbitrarily complex, specialized computations. + +## **2\. The Pricing Market for Oracle Services** + +The objective cost measurements form the basis of a competitive, market-driven ecosystem for providing oracle services.1 + +- **Service Bidding:** Node operators who wish to run oracle services participate in a bidding system. They bid on their willingness to provide computation at a certain price per cost unit (e.g., price per million retired instructions). +- **Incentivizing Efficiency:** The protocol prioritizes tasks for operators who offer cheaper service. This creates a powerful economic incentive for operators to optimize their infrastructure and report costs honestly. An operator who can perform a computation more efficiently (i.e., for a lower cost) will receive more data reporting tasks and, consequently, more rewards. + +This market dynamic ensures that the price of verified computation on Blocksense is driven down by open competition, benefiting the dApps and users who consume these services. + +## **3\. Advanced Execution: Concurrency and Shared Memory** + +To handle high-frequency data streams and parallelize work, oracle services can leverage advanced execution models, including threading and inter-process communication (IPC) via shared memory. These concurrent tasks are initiated during the one-time setup() phase of the oracle's lifecycle. + +### **3.1. WebAssembly Threads** + +Within the setup() function, an oracle service can spawn multiple WebAssembly threads. This is ideal for tasks that can be parallelized, such as fetching data from multiple APIs simultaneously. The Blocksense runtime automatically tracks the resource consumption (retired instructions, memory used, internet bandwidth) across all threads and aggregates them into a single, total cost for the query invocation. + +### **3.2. External Processes and Shared Memory IPC** + +For tasks that require continuous, long-running operationβ€”such as maintaining a live connection to a high-frequency data sourceβ€”the ideal pattern is to decouple the data ingestion from the on-demand query execution. + +Motivating Example: Real-Time Price Feeds +Consider an oracle service designed to provide the most up-to-the-second price for a volatile asset. This requires maintaining persistent WebSocket connections to multiple cryptocurrency exchanges, a task ill-suited for the synchronous, request-response model of the query function. +The Blocksense architecture solves this with a powerful pattern: + +1. **Launch in setup():** In the setup() hook, the oracle service launches a long-running external process. This process is responsible for establishing and maintaining WebSocket connections to multiple exchanges. +2. **Shared Memory:** The external process and the main oracle service communicate via a standardized shared memory API. This API allows the external process to write data into a well-defined, in-memory table. +3. **Decoupled Workflow:** + - The **external process** runs asynchronously, constantly updating the shared memory table with the latest price ticks from all connected exchanges. Crucially, it also measures its own resource consumption (e.g., bandwidth used) and writes this cost metric into the shared table alongside the price data. + - The oracle's main **query function** becomes extremely lightweight. When invoked, its only job is to read the latest aggregated value and its associated cost from the shared memory table and return them. + +This architecture effectively separates the high-frequency, asynchronous data ingestion from the synchronous, on-demand query processing. It allows the oracle to provide extremely low-latency data while ensuring that the cost of the query function itself remains minimal and predictable. + +## **4\. API for Reporting Custom Costs** + +To formally support the reporting of custom cost units from external programs, the Blocksense SDK provides a clear and enforceable API. The metadata for the oracle service declares the custom cost units it will report. The query function must then return a struct where specific fields are annotated to correspond to these declared units. + +This forces the oracle to report these costs on every invocation, making them an integral part of the service's output. + +**Conceptual API Example:** + +An oracle service that uses an external process to track WebSocket data might define its return type as follows: + +Rust + +// In the oracle's metadata, a custom cost unit is declared: +// custom_costs \= \["websocket_bandwidth_bytes"\] + +// The return struct for the query function. +pub struct PriceFeedResult { +// The primary data result of the query. +pub price: u64, +pub timestamp: u64, + + // This field is annotated as a cost unit. The runtime will parse this + // and include it in the final cost report for the query. + \#\[cost\_unit(name \= "websocket\_bandwidth\_bytes")\] + pub bandwidth\_used: u64, + +} + +// The implementation of the query function. +pub fn query(params: Vec\) \-\> PriceFeedResult { +// Read the latest price and the measured bandwidth cost +// from the shared memory table populated by the external process. +let (latest_price, bandwidth) \= read_from_shared_memory(); + + PriceFeedResult { + price: latest\_price, + timestamp: get\_current\_time(), + bandwidth\_used: bandwidth, + } + +} + +This annotation-based system provides a strongly-typed, explicit, and verifiable way for oracle services to report their extensible costs, ensuring the integrity of the network's pricing markets. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf diff --git a/spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md b/spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md new file mode 100644 index 0000000000..587bfed517 --- /dev/null +++ b/spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md @@ -0,0 +1,79 @@ +# **Blocksense SDK: Oracle Service Lifecycle & Storage APIs** + +Intersubjective Services (Oracle Services) on Blocksense are designed to be powerful, long-running, and stateful applications. They often need to perform complex, resource-intensive tasks that go beyond simple data fetching. To support these advanced use cases, the Blocksense SDK provides a well-defined execution lifecycle and a sophisticated storage model that allows developers to manage performance and on-chain consensus with precision. + +## **1\. The Oracle Service Lifecycle** + +Many advanced oracle services require an expensive, one-time setup. For example, a parametric insurance oracle designed to automatically settle claims for cargo ships must first process vast amounts of geographical and historical weather data to build a baseline risk model. Performing this setup for every single query would be prohibitively slow and costly. + +To solve this, Blocksense recognizes that zkSchellingCoin committee members (the nodes that run oracle services) are assigned their duties for prolonged periods, often several hours at a time.1 This stability makes it economically viable to perform an initial setup. The SDK exposes this capability through a simple three-stage lifecycle, allowing developers to amortize the cost of expensive initializations over thousands of subsequent queries. + +### **1.1. Lifecycle Hooks** + +An oracle service is structured around three core functions, or "hooks," that the developer implements. The oracle service runtime keeps the WebAssembly module instance alive between query calls, allowing state to be maintained in memory. + +- setup(): This function is called **once** when a new instance of the oracle service is initialized on a node. It is the ideal place for performing one-time, expensive setup tasks, such as creating temporary files in the cache, or spawning long-running WebAssembly threads and external processes. + - **Use Case (Parametric Insurance Oracle):** The setup() function would download large datasets, such as global shipping lane maps (GIS data) and historical hurricane track data. It would then write this data to files in the local cache and load it into an efficient, queryable data structure in the WebAssembly module's memory. +- query(params: Vec\) \-\> Vec\: This is the primary function of the service and is invoked for **every individual data request**. It receives request-specific parameters from the objective layer (e.g., a specific policy ID to evaluate) and is responsible for executing the core logic and returning a result. + - **Use Case (Parametric Insurance Oracle):** The query() function would take a policy ID as input. It would then fetch real-time data for the associated vessel, such as its current GPS location. It would compare this live data against the in-memory risk models (loaded from the cache during setup) to determine if a trigger event has occurred and return the outcome. +- teardown(): This function is called **once** when a service instance is being shut down or decommissioned on a node. It allows for the graceful cleanup of any resources allocated in the setup() phase that are not managed automatically by the system. + +## **2\. The Multi-Tiered Storage Model** + +Oracle services have diverse storage needs, ranging from temporary files for a single run, to consensus-critical on-chain state, to persistent, evolving off-chain databases. The Blocksense SDK addresses this with a multi-tiered storage model. + +### **2.1. Tier 1: Ephemeral File System Cache** + +For most use cases, oracle services need a temporary place to store data required for their operation. The SDK provides this through a sandboxed, ephemeral file system that is modeled as a standard file-system API. This design allows developers to use existing Rust libraries that read from and write to the file system without modification. + +- **Characteristics:** + - **Standard API:** Interacting with the cache feels like using a normal file system, enhancing developer productivity. + - **Lifecycle-Managed:** Oracle services can **only create new files within the setup() function**. These files are then available for reading by the query function and any WebAssembly threads spawned during setup. + - **Automatic Cleanup:** The system automatically deletes all files created in the cache when the oracle service instance is terminated. Developers do not need to manually clean up these files in the teardown() hook. + - **Portability:** This caching mechanism is recommended for creating highly portable oracle services that can be easily migrated from one machine to another, as their required state is self-contained and created at startup. + +### **2.2. Tier 2: Consensus Storage API (storage::\*)** + +Consensus Storage is used for persistent data that is an integral part of the oracle's result. + +A critical distinction must be made: while the primary result of a query function can be aggregated using various consensus algorithms (e.g., median, trimmed mean), any write operation to Consensus Storage is **always handled under the "exact match" consensus algorithm**. All reporting nodes must agree on the exact sequence and content of these writes for consensus to be reached. + +Because of this strict requirement, writing to Consensus Storage is recommended only for intersubjective truths that are almost objectively defined. These are values that, despite potentially depending on external factors like internet access, are expected to be identical across all honest reporting nodes. + +- **Use Cases:** + - An oracle tracking a GitHub repository could write the latest commit hash to consensus storage. + - A service that processes a sequence of events could store the ID of the last processed event to prevent duplicates. + - An oracle monitoring a specific satellite feed could store the hash of the latest processed image tile to ensure no data is missed or re-processed. +- **Conceptual API:** + Rust + // Writes a key-value pair to consensus storage. This action becomes part of the transaction result. + fn storage::write(key: Vec\, value: Vec\); + + // Reads a value from the consensus state. + fn storage::read(key: Vec\) \-\> Option\\>; + +### **2.3. Tier 3: Persistent Storage via Self-Elected Capabilities** + +Some oracle services require access to large, persistent, and constantly evolving datasets that would be impractical to set up from scratch for every instance. A prime example is an oracle that needs to query the state of a full Ethereum node. + +This is best modeled as a **self-elected capability**. Instead of a generic storage API, this represents a specialized service that a node operator explicitly chooses to provide. + +- **Mechanism:** A node operator can elect to run and maintain the necessary infrastructure (e.g., a full Ethereum client). The oracle service can then declare a dependency on this capability in its metadata. +- **Custom Cost Model:** Services that rely on these capabilities define their own custom cost models. The cost is not based on standard WASM metering but on metrics relevant to the service (e.g., cost per database query, cost per block data read). This allows the Blocksense marketplace to accurately price these more complex and resource-intensive services.1 + +## **3\. A Note on Stateful Logic: The Correct Pattern** + +The strict "exact match" requirement for the on-chain Consensus Storage API means it is unsuitable for values that may have slight variations between nodes, such as a calculated price from different API sources. Attempting to write such a value to storage would likely lead to consensus failure. + +The correct architectural pattern for managing such state involves a clear separation of concerns between the intersubjective and objective layers: + +1. **Intersubjective Layer (Oracle Service):** The insurance oracle service determines if a specific policy should be paid out (e.g., it encountered a hurricane). It returns a structured result like {"policy_id": "XYZ", "payout_due": true}. The consensus method for this result could be a simple majority vote. +2. **Consensus:** The zkSchellingCoin mechanism establishes a final, agreed-upon result from the reports of all committee members.1 +3. **Objective Layer (ZK Program):** The main insurance dApp contract receives this single, finalized result. It is this programβ€”not the oracle serviceβ€”that is responsible for managing the application's state. It can, for example, update a stateful object it owns that tracks the total number of claims paid out in a specific region. +4. **Data Flow:** If the oracle needed to know about past payouts to adjust its risk model, the Objective Program would pass that historical data _into_ the next query call as a parameter. + +This pattern correctly places the responsibility of state management on the deterministic Objective Layer, while using the Intersubjective Layer for its core purpose: establishing consensus on external, non-deterministic information. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf diff --git a/spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md b/spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md new file mode 100644 index 0000000000..63521f91b1 --- /dev/null +++ b/spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md @@ -0,0 +1,31 @@ +# **Blocksense SDK: Verifiable Computation with Trusted Execution Environments** + +## **1\. The Challenge: Accessing Privileged and Confidential Data** + +A significant portion of the world's high-value data is not publicly accessible. It resides within protected corporate databases, behind authenticated APIs, or is subject to strict privacy regulations. For oracle services to interact with this dataβ€”such as a bank providing private transaction details for a compliance check, or a healthcare provider verifying a credential for an insurance claimβ€”a fundamental challenge arises: how can a decentralized network trust that this privileged data has not been manipulated by the provider? + +Simply sending the data is insufficient, as the provider could alter it. Exposing the access credentials (like API keys or passwords) to a decentralized network of oracle nodes is a non-starter from a security perspective. Blocksense addresses this challenge by integrating a hybrid trust model that combines the hardware-enforced isolation of **Trusted Execution Environments (TEEs)** with the mathematical certainty of **Zero-Knowledge Proofs (ZKPs)**. + +## **2\. The Solution: A Verifiable Chain of Trust** + +The core of the solution is to create an unbroken, verifiable chain of trust that extends from a secure hardware enclave to the Blocksense network. This allows an oracle service to prove that a specific, audited computation was performed on privileged data without revealing the data itself or the credentials used to access it. + +This is achieved through a multi-stage process, orchestrated by **BlocksenseOS**, a specialized, minimal operating system designed to run within TEEs. + +### **2.1. The Primary Use Case: Trust-Minimized Data from Privileged Providers** + +The most powerful application of this model is enabling data providers who have privileged access to information to serve that data to on-chain applications with strong integrity guarantees. + +Consider a data provider who has access to a secure, impartial third-party system (e.g., a government database, a secure financial data feed). They want to provide data from this system to a Blocksense oracle script without revealing their access credentials. + +The workflow is as follows: + +1. **Deployment of an Audited Module:** The data provider deploys an audited, open-source software module into a TEE instance running BlocksenseOS. This module contains the logic to perform a specific task, such as querying the third-party system using embedded credentials. The hash of this audited code is made public. +2. **Execution in Isolation:** The TEE executes the module in a protected environment, completely isolated from the host system. The module uses its embedded credentials to access the privileged data and computes a result. +3. **Hardware Attestation:** The TEE's hardware generates a cryptographic **attestation**. This is a digital signature from the TEE's unique, manufacturer-provisioned private key. The attestation proves two critical facts: + - **Code Integrity:** A specific piece of code, identified by its hash, was executed. + - **Confidentiality:** The execution occurred within the secure, tamper-proof TEE. +4. **Wrapping Attestation in a ZK Proof:** The TEE attestation and the result of the computation are then used as inputs (witnesses) to generate a succinct ZK proof. This proof makes a simple, verifiable statement: _"I possess a valid TEE attestation which confirms that the code with hash \[known_code_hash\] was executed and produced the result \[computation_result\]."_ +5. **On-Chain Verification:** This final ZK proof is what the oracle service submits to the Blocksense network. The on-chain verifierβ€”an Objective Program on Blocksenseβ€”can quickly and cheaply verify this proof. The verifier only needs to know the public hash of the audited module; it never sees the TEE attestation itself or the provider's confidential credentials. + +This process creates an unbreakable chain of trust. The TEE guarantees that the provider cannot manipulate the software after it has been audited and deployed, and the ZK proof guarantees that the attestation is valid. The result is a trust-minimized bridge between confidential off-chain data and the transparent, verifiable world of the blockchain. diff --git a/spec/content/Blocksense Software Component Architecture.md b/spec/content/Blocksense Software Component Architecture.md new file mode 100644 index 0000000000..3386319aee --- /dev/null +++ b/spec/content/Blocksense Software Component Architecture.md @@ -0,0 +1,109 @@ +# **Blocksense Software Component Architecture** + +## **1\. Philosophy: A Modular Ecosystem for Agility and Security** + +The Blocksense platform is engineered as a collection of discrete, specialized software components rather than a single monolithic application. This modular architecture is a deliberate design choice aimed at achieving several critical goals: + +- **Accelerated Development Cycles:** By breaking the system into smaller, independent components, our development teams can achieve significantly faster build, link, and test cycles. This agility allows for more rapid iteration, easier debugging, and quicker delivery of new features and security patches. +- **Enhanced Security through Isolation:** Separating components based on their function allows us to apply the principle of least privilege rigorously. Critical components, such as the credentials manager, can be run in highly isolated environments with minimal attack surfaces. +- **Resource Efficiency and Flexibility:** Node operators only need to run the specific software components required for the duties they are assigned. A node with only oracle duties does not need to run the prover software, leading to more efficient resource utilization. + +All components are designed to run within **BlocksenseOS**, a specialized, minimal operating system that provides a secure and verifiable foundation for the entire stack. + +## **2\. Core Infrastructure Components** + +These components form the foundational layer of any Blocksense node, managing configuration, security, and interaction with the network. + +### **2.1. Blocksense Daemon (blocksensed)** + +The blocksensed process is the central nervous system of a Blocksense node. It acts as a long-running service responsible for orchestrating all other components. + +- **Responsibilities:** + - Loads the node operator's configuration. + - Manages the node's identity and participates in the on-chain bidding process for duties. + - Monitors the blockchain for duty assignments (e.g., being selected for a zkSchellingCoin committee or assigned simulator/prover tasks). + - Provides a secure RPC interface for submitting transactions to the network. + - Acts as a process manager: when a new duty is assigned, blocksensed is responsible for fetching the latest version of the required duty-specific software (e.g., blocksense-oracle-runtime) and launching it in a new, isolated process. + +### **2.2. Credentials Manager (blocksense-creds)** + +The blocksense-creds process is a highly specialized and hardened component with a single responsibility: to securely store and use the node's sensitive private keys. + +- **Responsibilities:** + - Holds the node's primary private key for signing transactions and participating in consensus. + - Exposes a minimal, local-only IPC (Inter-Process Communication) interface to blocksensed. +- **Security Design:** + - blocksense-creds is designed to be completely isolated from the public internet. It only communicates with the blocksensed daemon on the local machine. + - Any potential exploit would require a two-stage attack: first compromising the main blocksensed daemon, and then leveraging a second, separate exploit against the hardened blocksense-creds process. This significantly raises the bar for an attacker to gain access to private keys. + +### **2.3. Blocksense CLI (blocksense)** + +The blocksense binary is the primary interface for developers. It is a client application that interacts with blocksensed and orchestrates the various developer toolchain components. + +- **Responsibilities:** + - Provides a unified command center for project initialization, building, testing, and deployment. + - Communicates with the local blocksensed daemon to submit transactions or query network state. + - Invokes other specialized components, such as the blocksense-noir compiler, as needed during the development workflow. + +## **3\. Duty-Specific Components** + +These are specialized programs that are launched by blocksensed only when the node is assigned a corresponding duty. + +### **3.1. Oracle Runtime (blocksense-oracle-runtime)** + +This component is responsible for executing Intersubjective Services (Oracle Services). + +- **Technology:** Built on the Wasmtime WebAssembly runtime, providing a secure, sandboxed environment for executing untrusted oracle code. +- **Function:** Loads and executes the WASM bytecode of an oracle service, providing it with access to the necessary host APIs (e.g., for HTTP requests, caching, and consensus storage) while meticulously metering its resource consumption. + +### **3.2. Simulator (blocksense-sim)** + +This component is launched when the node is assigned duties as an Execution Layer Simulator. + +- **Function:** Receives ordered batches of transactions from the Ordering Layer. It is responsible for applying the state transition logic for these transactions in a deterministic manner, handling the object-locking protocol, and identifying transactions that need to be postponed due to contention. + +### **3.3. Prover (blocksense-prover)** + +This component is launched when the node is assigned duties as a ZK Prover. + +- **Function:** Takes the execution trace from a Simulator and generates a succinct ZK proof of the computation. This is a computationally intensive task that often leverages specialized hardware (e.g., GPUs, FPGAs) to accelerate the proof generation process. + +## **4\. Developer Toolchain Components** + +These components are part of the Blocksense SDK and are typically invoked by the blocksense CLI during development. + +### **4.1. Noir Compiler (blocksense-noir)** + +The official compiler for the Blocksense Noir language, used to develop Objective Programs (ZK circuits). + +- **Function:** Compiles high-level .nr source code into a verifiable ZK circuit format (ACIR) that can be executed and proven by the Blocksense network. The blocksense build command acts as a user-friendly wrapper around this compiler. + +## **5\. Component Interaction Diagram** + +The following diagram illustrates the high-level interactions between the core components of a Blocksense node. +\+---------------------------------+ +| Developer (via Shell) | +\+---------------------------------+ +| +v +\+---------------------------------+ +| Blocksense CLI (\`blocksense\`) | +\+---------------------------------+ +| (RPC) +v +\+---------------------------------+ \+------------------------------------------+ +| Blocksense Daemon (\`blocksensed\`)|-----\>| Blocksense Network (Peers/Consensus) | +| |\<-----| | +| \- Manages Config & Duties | \+------------------------------------------+ +| \- Launches Duty Components | +\+---------------------------------+ +| (IPC) | (Launches Process) +v \+-------------------\> \[ Duty-Specific Components \] +\+---------------------+ | +| Credentials Manager | | e.g., blocksense-oracle-runtime +| (\`blocksense-creds\`)| | blocksense-sim +| \- Holds Keys | | blocksense-prover +| \- Signs Payloads | | +\+---------------------+ \+------------------------------------------+ + +This modular architecture ensures that Blocksense is not only powerful and scalable but also secure, flexible, and easy to develop for and maintain. diff --git a/spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md b/spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md new file mode 100644 index 0000000000..9c46aefcfa --- /dev/null +++ b/spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md @@ -0,0 +1,246 @@ +# **Blocksense: A Litepaper for the Universal Verification Layer** + +**July 2025** + +## **Abstract** + +The evolution of decentralized technology has been constrained by two fundamental limitations: a **Connectivity Barrier**, which has hindered the full integration of blockchains with the internet and the real world, and a **Throughput Barrier**, leaving the technology without the necessary capacity to realistically power the world's economy. This has confined decentralized applications to a narrow domain of objectively verifiable logic, limiting their potential to reshape our digital world. + +Blocksense introduces a novel, service-oriented blockchain architecture designed to systematically dismantle these barriers. We present a universal verification layer capable of securely processing both objective and intersubjective truths at a scale previously thought unattainable. Our solution is built upon two core innovations: + +1. **The Intersubjective Truth Machine:** We solve the [oracle problem](https://www.mdpi.com/2078-2489/11/11/509) with zkSchellingCoin, a bribery-resistant consensus mechanism that uses zero-knowledge proofs (ZKPs) to ensure voter secrecy. For high-stakes disputes, we employ **Futarchy** as an ultimate arbiter, creating on-demand prediction markets that secure the network with the collective liquid capital of the entire global market, making malicious attacks economically irrational. +2. **The Boundless Throughput Engine:** We implement a Decoupled State Machine Replication (DSMR) architecture that radically parallelizes the blockchain. Transaction ordering is scaled horizontally via multiple sharded DAG-BFT consensus instances, while execution is parallelized through an incrementally verifiable computation (IVC) framework. This design allows network throughput to increase linearly with the number of participating nodes. + +These core innovations enable a new economic paradigm of computational abundance. The Blocksense network operates as a unified marketplace for verified computation, creating a powerful economic flywheel that attracts vast resources. This engine allows us to deliver a frictionless user experience, featuring passkey-native accounts and zero-cost transactions, while unlocking a new design space for applications like on-chain autonomous agents. By solving the foundational problems of connectivity and scale, Blocksense is poised to become the essential middleware for the next generation of the decentralized web. + +## **1\. Introduction: Breaking the Barriers of Blockchain** + +For over a decade, blockchain technology has promised to build a more open, transparent, and user-centric digital future. Yet, despite immense innovation, its transformative potential remains gated by fundamental architectural constraints. Blockchains operate as "digital islands"β€”secure and self-consistent, but profoundly isolated from the world they aim to revolutionize. This isolation manifests as two primary barriers that have dictated the trajectory of the entire space. + +The first is the **Connectivity Barrier**. Blockchains are fundamentally disconnected from external systems; they lack a native, secure mechanism to ingest and agree upon the complex, non-deterministic, and subjective information that underpins the global economy. The industry’s answer, the oracle, has largely remained centralized, failing the core vision of decentralization and creating an imbalance of power that leads to inefficiencies and gatekeeper dynamics. + +The second is the **Throughput Barrier**. The canonical blockchain design, where every full node must process every single transaction, ensures security at the cost of scalability. This "all-nodes-must-verify" paradigm creates a computational bottleneck that limits transaction speed, drives up costs, and ultimately hinders mainstream adoption. Existing scaling solutions, while innovative, have often introduced significant complexity and ecosystem fragmentation, further hindering the user experience without solving the core architectural limitation. + +Blocksense is a direct response to these challenges. It is not merely another Layer-1 blockchain or an incremental improvement on existing oracle designs. We introduce a new paradigm: a **service-oriented blockchain** architected from the ground up to serve as a universal verification layer for both Web3 and Web2. Our mission is to provide the foundational infrastructure for a new class of "Verified Autonomous Services" that can securely reason about any form of information and execute at boundless scale. + +By solving the dual problems of connectivity and throughput, Blocksense paves the way for applications previously confined to the realm of science fiction: decentralized AI agents managing real-world assets, complex financial instruments powered by live internet data, and global compute marketplaces operating with unprecedented efficiency. This paper details the core technological innovations, economic models, and go-to-market strategy that will enable Blocksense to fulfill this vision. + +## **2\. Core Innovation I: The Intersubjective Truth Machine** + +To break the Connectivity Barrier, a protocol must be able to securely establish consensus on **intersubjective truths**β€”information, like the price of an asset or the outcome of an event, where a majority of participants are likely to share the same view, but which cannot be verified by deterministic computation alone. The foundational approach for this is the SchellingCoin game, as first proposed by Vitalik Buterin\[^1\]. It posits that a network of rational, uncoordinated actors will converge on a truthful answer because it is their most profitable individual strategy. While elegant, the emergence of powerful smart contract platforms has revealed a critical vulnerability in naive implementations of this idea. + +\[^1\]: Vitalik Buterin, "SchellingCoin: A Minimal-Trust Universal Data Feed," Ethereum Blog, 2014\. [https://blog.ethereum.org/2014/03/28/schellingcoin-a-minimal-trust-universal-data-feed](https://blog.ethereum.org/2014/03/28/schellingcoin-a-minimal-trust-universal-data-feed) + +### **2.1 The SchellingCoin Achilles' Heel: Trustless Bribery** + +In any system where a single oracle update can influence the fate of billions of dollars, the incentive to corrupt the outcome is immense. The combination of public ledgers and Turing-complete smart contracts creates a fatal attack vector: **the trustless bribe**. An attacker can deploy an escrow-like smart contract that programmatically and anonymously executes a sophisticated bribery campaign with no risk to themselves or the participants. + +This attack works against any voting protocol where participants can prove their right to vote and how they voted. It unfolds as follows: + +1. **Bounty Placement:** An attacker locks a large bounty in a smart contract, promising a reward to any validator who votes for a malicious outcome. +2. **Trustless Coordination:** Validators can independently inspect the contract's code and verify that the reward is guaranteed upon compliance. Using ZKPs, they can even signal their willingness to participate without revealing their identity. +3. **Malicious Vote & Payout:** Once a critical mass of participants is reached, they all cast the malicious vote. The smart contract allows them to prove their participationβ€”again, sophisticated use of ZKPs enables them to claim their reward to a fresh, anonymous addressβ€”without creating a direct, attributable link to the attack. +4. **No-Risk Execution:** If the attack fails to attract enough participants, the smart contract simply returns the bounty to the attacker. + +The devastating power of this attack is its trustless nature; the cold logic of the code is the only escrow required. A more elaborate contract can even eliminate the requirement for an upfront bounty, replacing it with a payout token that represents a share of the generated future profits. + +### **2.2 Defense-in-Depth: A Multi-Layered Security Model** + +Blocksense employs a multi-layered, defense-in-depth strategy to secure intersubjective consensus, making attacks progressively more difficult and economically irrational at every stage. + +#### **Layer 1: Secret Sub-Committees & zkSchellingCoin** + +Our first line of defense is zkSchellingCoin, an enhanced implementation of the SchellingCoin principle. For any given data request, the protocol elects a small, random, and secret sub-committee of stakers to vote. By drawing on research from coercion-resistant e-voting protocols like MACI (Minimal Anti-Collusion Infrastructure), we use zero-knowledge proofs to make it cryptographically impossible for a voter to produce the proof an attacker's contract would require. The system makes it impossible for a voter to prove _both_ their right to vote on a particular topic _and_ the content of their vote. Without this complete proof, the trustless bribe collapses. + +#### **Layer 2: Distributed Coordination & Reputation** + +While MACI prevents voters from proving how they voted, its standard design has a single point of failure: the Coordinator, who processes the encrypted votes. A malicious Coordinator cannot forge the final tally, but they _can_ break vote secrecy by colluding with attackers. + +Blocksense eliminates this vulnerability by **distributing the Coordinator role** using MPC-powered co-SNARKs. The vote tallying is performed by a set of operators who disclose their identity and get selected via a dynamic **reputation market**. The ultimate users of the dataβ€”the protocols and dApps with high TVSβ€”are awarded endorsement credits, which they use to indicate preferred coordinators. Coordinators who fail to flag malicious updates face slashing which creates a powerful second layer of defense: an attacker must now not only subvert the staking system but also the reputation system, which is controlled by the very entities they wish to harm. This model significantly lowers the raw capital requirements for security, drawing strength from the established trust networks of the ecosystem, much like today's dominant centralized oracles that operate purely on reputation. + +#### **Layer 3: Open Challenges & Dispute Escalation** + +Once a sub-committee and its coordinators produce a result, it is not immediately finalized. Every data update enters a configurable **dispute period**. This period is designed to be minimal, as **watchdog nodes can run automated software** that continuously monitors all proposed updates and can raise a dispute within milliseconds of detecting a malicious or incorrect result. Importantly, an ongoing dispute for a specific data point does not affect the liveness of the service; a new committee is immediately elected to provide a subsequent update, ensuring the protocol remains operational. During the dispute period, **anyone can challenge** the original outcome by posting a dispute bond. This action immediately escalates the stakes: the dispute is no longer between the small committee and a single challenger, but requires **all stakers in the protocol to take a side**. The backers of the losing side face slashing, ensuring that challenges are taken seriously and raising the economic cost of pushing a malicious update through the system. + +#### **Layer 4: Futarchy, the Ultimate Arbiter** + +If a dispute escalates to a full network vote, a sufficiently capitalized attacker could still theoretically win through a 51% stake attack. To counter this existential threat, Blocksense integrates its final and most powerful layer of defense: **Futarchy**. + +Instead of resolving the dispute with a simple vote, the protocol turns to the entire global market for judgment. + +1. **Prediction Markets Launch:** The protocol automatically creates two prediction markets with highly specific questions: + - **Market M:** Will the price of the Blocksense token fall by more than 50% in the next two weeks if the malicious Claim M is published? + - **Market T:** Will the price of the Blocksense token fall by more than 50% in the next two weeks if the truthful Claim T is published? +2. **The Market Decides:** A successful, value-extracting attack has a clear consequence: all honest stakers will be slashed, leaving the protocol in the hands of the attacker and destroying market confidence. The token price would inevitably trend towards zero. Therefore, rational market participants worldwide will rush to bet "Yes" on Market M, as this outcome is highly probable. Conversely, there is no reason to expect a price crash if the truthful Claim T is published. +3. **Unwinnable Economic Warfare:** To win, the attacker must manipulate the prediction markets by betting against this obvious reality. In essence, they must financially overpower every rational actor in the world who is drawn to a profitable, low-risk bet. The cost of such an attack is not measured against the total value staked in Blocksense, but against **all the liquid capital available to participate in the prediction market**. By turning a security crisis into a global trading opportunity, Futarchy serves as the ultimate crypto-economic backstop, making any rational 51% attack prohibitively expensive. + +## **3\. Core Innovation II: The Boundless Throughput Engine** + +The monolithic architecture of traditional blockchains is the root cause of the Throughput Barrier. Blocksense demolishes this barrier with a radically parallel design that separates network functions and scales them independently, leading to theoretically boundless throughput. + +### **3.1 The Decoupled Architecture: Separating Ordering from Execution** + +Blocksense is built on a **Decoupled State Machine Replication (DSMR)** model. In this paradigm, the network's responsibilities are split into two distinct, asynchronous layers: + +1. **The Ordering Layer (Mempool):** This layer's sole responsibility is to receive transactions from users and establish a definitive, global order for them. +2. **The Execution Layer:** This layer consumes the finalized sequence of transactions and processes the state transitions. + +This separation allows each layer to be optimized and scaled independently using specialized techniques. + +### **3.2 Scalable Ordering: The Parallel DAG Mempool** + +To achieve limitless ordering capacity, Blocksense implements a novel **parallel mempool** composed of multiple, independent Directed Acyclic Graph (DAG) based BFT consensus instances. We leverage cutting-edge protocols like Sui's Mysticeti and Aptos's Raptr, which have demonstrated sub-second finality and throughput exceeding 100,000 TPS in test conditions with validator sets of \~100 nodes. + +The mechanism is simple yet powerful: + +- **Transaction Sharding:** Transactions are deterministically assigned to one of the parallel DAG instances by hash, distributing the ordering load evenly. +- **Independent Finalization:** Each DAG instance finalizes its own local sequence of transactions with high speed. +- **Round-Robin Consumption:** The Execution Layer consumes the finalized transaction lists from each DAG in a fair, round-robin sequence, weaving them together into a single, globally ordered stream. + +This architecture allows us to increase the network's transaction ordering capacity simply by adding more parallel DAG instances, enabling horizontal scaling of the mempool to meet any demand. + +### **3.3 Scalable Execution: The Simulation-First Parallel Pipeline** + +Achieving parallel execution is notoriously difficult due to potential data dependencies between transactions. Blocksense solves this with a multi-stage, **simulation-first pipeline** that separates the cheap work of determining execution outcomes from the expensive work of proving them. + +**1\. Simulation:** Once a batch of transactions is finalized by the Ordering Layer, it is first picked up by a class of nodes we call **Simulators**. Inspired by the Calvin protocol and Speculative Multi-threaded (SMT) execution, Simulators attempt to execute all transactions in a batch in parallel. + +- **Conflict Resolution:** If transactions have data conflicts (e.g., two transactions trying to modify the same state), the conflicting transaction is postponed to the next batch. A special "skip" proof is generated to demonstrate the conflict, and the reward for executing the postponed transaction is increased to ensure it is eventually processed. With sub-second batches, this process introduces negligible latency. +- **Economic Security:** Simulators are not critical for protocol safety, as a faulty simulation cannot directly harm users. However, to build confidence, Simulators must sign their results. If a Simulator signs an invalid result, they can be slashed. This provides a strong economic incentive for correctness, allowing the next stage of the pipeline to proceed. + +**2\. Proving:** The signed results from the Simulatorsβ€”the pre- and post-conditions for every computational stepβ€”are broadcast to the network of **Provers**. With the execution path now determined, the computationally intensive task of generating ZK proofs can be massively parallelized. + +- **Incrementally Verifiable Computation (IVC):** Using a ZK proving system that employs **folding** (e.g., UltraHONK), different Provers can work on different steps of different transactions simultaneously. +- **Proof Aggregation:** These individual "leaf" proofsβ€”both for precise state transition computations and the zkSchellingCoin votes produced by intersubjective committeesβ€”are then efficiently combined up a tree using a **folding scheme**. The final result is a single, succinct proof that attests to the validity of the entire block's state transition, without requiring any single node to have executed or proven all of it. + +This unified ZK proof is a powerful primitive. It allows Blocksense to be natively ZK-bridged to any other chain, functioning as a ZK rollup or validium. It also enables light clients to sync with the chain instantly and securely by downloading and verifying just a single proof. + +This entire architectureβ€”from parallel ordering to parallel simulation and provingβ€”requires immense computational capacity. The design is predicated on the ability to attract a vast network of hardware operators. The following section details the economic model designed to do precisely that. + +## **4\. The Blocksense Economy: A Self-Reinforcing Flywheel** + +Breakthrough technology alone is insufficient. A successful protocol requires a robust, self-reinforcing economic model that aligns incentives between all participants. The Blocksense economy is designed around a principle of **computational abundance**. Unlike traditional blockchains that treat transaction throughput as a scarce resource auctioned off via priority fees, Blocksense's boundless architecture treats it as a commodity. This fundamental shift allows us to eliminate **transaction priority fees**. Instead of users bidding against each other for inclusion, node operators compete to provide computation at the lowest possible price, driving costs down to their material limitβ€”a figure we expect to trend towards zero over time as hardware efficiency continues to improve. + +### **4.1 Tokenomics and Utility** + +The native Blocksense token is the lifeblood of the network, serving three primary functions: + +1. **Staking and Security:** Node operators must stake Blocksense tokens to participate in the network's consensus and execution processes. This stake acts as a security deposit, which can be slashed for malicious behavior, thereby securing the network. +2. **Payment for Services:** The Blocksense token is the exclusive unit of account for all network services. This includes fees for code execution, internet bandwidth for data services, and persistent storage rent. The only scarce resource where priority bidding is utilized is for block space on target chains, ensuring efficient cross-chain data delivery. +3. **Governance:** Token holders will have the right to participate in the governance of the protocol, voting on key parameter changes and system upgrades. + +### **4.2 A Unified, Capability-Based Marketplace for Web2 & Web3** + +The Blocksense network is more than a blockchain; it is a global marketplace for **verified computation** designed to compete with and subsume specialized compute networks across every vertical. We achieve this through a flexible, **capability-based approach**. + +Within Blocksense, services can require specialized hardware (e.g., high-end GPUs for rendering or AI inference), access to proprietary data feeds (e.g., real-time sports results), or other unique capabilities. Our protocol provides a portal where operators can see the real-time profitability of acquiring these capabilities. The service bidding process allows operators to price their services based on the specific capabilities they offer, creating dynamic, market-driven pricing for every type of computation. This naturally segments the market, allowing Blocksense to effectively compete with specialized networks for ZK proving, 3D rendering, AI, and more, all within a single unified platform. + +This model is supercharged by our ability to serve both Web3 and Web2 clients. The zkSchellingCoin mechanism can provide cryptographic guarantees for any sufficiently deterministic task. For example, a cloud service offering inference from an open-weights LLM can stake funds in Blocksense and cryptographically sign their outputs. If a user suspects the provider is cutting costs by serving a smaller model, they can trigger a zkSchellingCoin consensus to verify the output's authenticity. If caught, the provider's stake is slashed, creating a new paradigm of trust-minimized Web2 services. This creates a **powerful structural advantage** for Blocksense node operators, who earn revenue from two distinct categories of work: + +- **High-Margin Verification:** Core Web3 tasks like providing oracle data for high-value DeFi protocols. +- **Low-Margin Commodity Compute:** General-purpose Web2/Web3 tasks where prices are driven by open market competition. + +The key insight is that the high-margin work attracts operators and subsidizes their participation in the network. They can then use their idle capacity to service the low-margin commodity markets at a cost basis that pure-play specialized networks cannot match. This advantage allows Blocksense to attract a vast and diverse network of hardware providers, ensuring deep liquidity and the lowest prices for all computational services. Furthermore, as this network of capable operators becomes globally distributed, Blocksense is uniquely positioned to become the ideal platform for low-latency services such as conversational AI, online gaming, and augmented reality. + +### **4.3 Oracle Extractable Value (OEV) as a User Rebate** + +Maximal Extractable Value (MEV) is an extractive force in most blockchain ecosystems. Blocksense redesigns this dynamic. Our architecture allows us to bundle many oracle updates together with meta-transactions that can act on them, all within a single, indivisible on-chain transaction. This atomicity allows us to natively capture the value associated with acting on this new informationβ€”what we term **Oracle Extractable Value (OEV)**. + +Instead of allowing this value to be captured by third-party searchers, Blocksense runs a competitive auction for the right to include transactions within these atomic bundles. The revenue generated is then programmatically redistributed to the protocols and dApps whose activity generated the OEV opportunity in the first place. These protocols, in turn, can pass these savings on to their end-users. This transforms MEV from an invisible tax on users into a powerful retention and growth mechanism for the entire ecosystem. + +### **4.4 The Service Bidding System** + +To ensure that network resources are allocated efficiently and at the lowest possible cost, Blocksense employs a secret service bidding system. Node operators secretly bid for the right to perform various duties (e.g., mempool validation, ZK proving, zkSchellingCoin voting). A service running within the protocol computes a cut-off price for each duty, selecting all bidders below that price. To prevent centralization and strategic underbidding from compromising security, the selection mechanism incorporates randomization, grouping bids into percentile-based bands and giving all bidders within a band a chance to be selected. This fosters healthy competition, driving down costs for users while ensuring the network remains decentralized and secure. + +### **4.5 Our Durable Moat: A Self-Reinforcing Network Effect** + +The Blocksense economic model is designed to create a powerful, self-reinforcing network effect that forms our long-term competitive moat. The flywheel is driven by the unique properties of our shared resource pooling architecture. + +Adding an additional consumer to a Blocksense service (e.g., a new protocol subscribing to an existing data feed) does not increase the operational cost of running that service. The cost is shared among all consumers. Therefore, **every new consumer lowers the cost for all existing consumers**. This creates a powerful economic barrier to entry. A competitor would have to match our network's scale and volume to offer a comparable price, a monumental challenge once a critical mass is achieved. + +This cost advantage is reinforced by the relationship between Total Value Secured (TVS) and trust. New consumers are naturally drawn to the platform with the highest TVS, as it serves as a strong social signal of reliability. As new consumers join, the network's TVS grows, which in turn attracts more stakers and node operators seeking to earn rewards. This influx of capital and hardware further increases the network's crypto-economic security, making Blocksense an even more attractive and trusted platform for the next wave of consumers. + +## **5\. Go-to-Market: Universal Cross-Chain Services** + +Blocksense's advanced technology and robust economics translate directly into a suite of disruptive services. Our go-to-market strategy is focused on leveraging these services to solve acute pain points for developers and protocols across the entire Web3 ecosystem, starting with the multi-billion dollar oracle market. + +### **5.1 The ADFS: A Hyper-Efficient Data Bus** + +The cornerstone of our service offering is the **ADFS (Aggregated Data Feed Store)**. The ADFS is a smart contract system deployed on target blockchains that acts as a hyper-efficient data and transaction bus. Its power comes from aggregation: Blocksense can bundle thousands of distinct data feed updates, cross-chain messages, and meta-transactions into a single payload, the validity of which is verified on the target chain by a single, inexpensive zero-knowledge proof. + +This architecture provides an order-of-magnitude cost reduction compared to any existing oracle or cross-chain messaging protocol, which typically post individual transactions for each update. The ADFS is our beachhead, enabling us to deliver superior service at a structurally lower cost. + +### **5.2 Disrupting the Oracle Market** + +The oracle market is currently split between two paradigms: push and pull models. Blocksense is designed to disrupt both. + +- **vs. Push Oracles:** Traditional "push" oracles are limited by on-chain costs, forcing a trade-off between data freshness and expense. The extreme efficiency of the ADFS breaks this trade-off. By pushing vast amounts of data at a marginal cost, we enable use cases that are currently prohibitive, such as high-frequency on-chain derivatives, real-time state updates for blockchain games, and more sophisticated algorithmic strategies. +- **vs. Pull Oracles:** The "pull" model requires protocols to run costly off-chain infrastructure to monitor and bring data on-chain. Blocksense offers a superior alternative through the **programmability of our oracle scripts**. A task like a loan liquidation can be encoded as a persistent, autonomous service that runs on the decentralized Blocksense network. This service can detect liquidation conditions and conditionally push the required data on-chain. Crucially, this process integrates with our OEV market; sophisticated actors can bid to provide the required liquidation capital on-demand, all within the same atomic ADFS transaction. This creates a hyper-efficient liquidation marketplace, eliminating the need for protocols to overpay external bots. For maximum flexibility, Blocksense also supports a traditional pull model, where a frequently rotated High-Frequency Updates Committee provides signed data off-chain. + +### **5.3 Beyond Data: A Universal Cross-Chain Primitive** + +The ADFS is more than just a data delivery mechanism; it is a universal primitive for efficient cross-chain communication. Its ability to aggregate arbitrary messages and verify them with a single ZK proof has far-reaching applications: + +- **ZK Proof Aggregation:** Rollups and ZK-coprocessors can use Blocksense as a highly efficient aggregation and settlement layer, outsourcing the expensive on-chain verification of their proofs. +- **Account Abstraction Bundler:** Blocksense can act as a universal bundler, gathering user operations from across the ecosystem and settling them on any target chain in a single, cost-effective transaction. +- **On-Demand Liquidity:** The same OEV market participants who provide capital for liquidations can also provide on-demand liquidity for cross-chain swaps and chain abstraction. This allows users to seamlessly interact with dApps on any chain while holding funds on a single chain, with Blocksense acting as the trust and messaging layer. + +By establishing itself as the most efficient cross-chain data and verification layer, Blocksense is positioned to become essential, non-displaceable middleware for the entire multi-chain ecosystem. + +## **6\. Redefining the User & Developer Experience** + +The ultimate measure of a protocol's success is the quality of the experiences it enables. The architectural innovations of Blocksense are not ends in themselves, but means to deliver a radically improved experience for both end-users and developers, paving the way for mainstream adoption. + +### **6.1 For Users: The Invisible Blockchain** + +For Web3 to reach a global audience, the underlying technology must become invisible. Blocksense is designed to abstract away the complexities that have plagued the user experience for years. + +- **Frictionless Onboarding:** We eliminate the need for browser extensions and seed phrases. Blocksense features a native account abstraction system built around **Passkeys** (WebAuthn). Users can create a wallet and sign transactions using the biometric sensors already on their phones and laptops (e.g., Face ID, fingerprint scan), providing a familiar, secure, and seamless onboarding experience. +- **Zero-Cost Transactions:** The high and unpredictable cost of gas is a major barrier to entry. In the Blocksense economy, transaction fees are a business expense, not a user tax. Our architecture enables flexible pricing models where applications, protocols, or even receiving parties can sponsor transaction costs, creating a "gasless" experience for the end-user. +- **Instant & Secure Syncing:** Users should not have to wait hours to sync a full node or trust a centralized endpoint. Blocksense light clients can sync to the latest state of the chain instantly and securely by downloading and verifying a single, succinct ZK proof of the chain's history. + +### **6.2 For Developers: A Universe of Possibilities** + +Blocksense removes the traditional constraints of smart contract development, providing a Turing-complete, general-purpose platform for building a new generation of powerful applications. + +- **The Birth of Autonomous Agents:** The combination of three core featuresβ€”**scheduled/recurring transactions** (setTimeout/setInterval), native **AI/ML model inference**, and the ability to read from **any on-chain or off-chain data source**β€”creates the perfect environment for building true, on-chain **Autonomous Agents**. Developers can deploy persistent services that operate independently, react to external events, and execute complex logic, unlocking use cases from automated DeFi strategies to decentralized social media moderators. +- **Universal Composability:** Blocksense is a multi-VM environment, designed to support a range of execution engines like WASM, Move, and the EVM. This is achieved by allowing new ZK circuits that prove the execution of a given VM to be deployed as regular services on the network. We will standardize the ABI for cross-VM calls, allowing smart contracts written in different languages to communicate seamlessly, as if they were making a simple function call. This fosters a rich, interoperable ecosystem where developers can use the best tools for the job without being siloed. +- **Native Privacy:** The ZK-native architecture of Blocksense makes it a premier platform for privacy-preserving applications. Developers can leverage the protocol's core cryptographic primitives to build applications with confidentiality guarantees. A powerful example is a privacy-preserving, cross-chain smart wallet that uses ZK proofs to shield sensitive **governance details**β€”such as multi-signature thresholds and signers for a corporate treasuryβ€”while interacting with any connected blockchain, all managed through a simple, passkey-based interface. +- **The End of the Oracle Problem:** For developers, accessing external data or performing a complex computation is no longer a multi-party integration challenge. It is a native API call. By building intersubjective consensus directly into the execution layer, Blocksense transforms the entire internet into a readable, verifiable data source for smart contracts. + +## **7\. Governance** + +Blocksense is committed to the principles of progressive decentralization. Over time, control over the protocol will be transferred to its community of stakeholders, managed through the Blocksense DAO. The DAO's primary responsibility will be to steward the long-term health and evolution of the network. + +**Protocol Upgrades:** The core function of the DAO is to manage protocol upgrades. As a ZK-native protocol, major upgrades involve deploying new ZK circuits and verifier contracts. This process is governed by on-chain voting of Blocksense token holders. To ensure network stability and user security, all passed proposals are executed via a **timelock contract**. This imposes a mandatory delay between a successful vote and the implementation of the upgrade, giving all users and applications ample time to review the changes, prepare for them, or, in the event of a contentious proposal, exit the system. This mechanism is a critical safeguard against hostile or rushed governance takeovers. + +**Treasury and Ecosystem Management:** At the time of the Token Generation Event (TGE), a significant portion of the token supply will be allocated to a community-governed treasury. These funds will be unlocked gradually over several years to ensure long-term, sustainable development without creating downward price pressure. The Blocksense DAO will have transparent oversight of these funds, directing them towards activities that grow the ecosystem, including: + +- **Research & Development Grants:** Funding teams and individuals to advance the core protocol. +- **Ecosystem Investments:** Providing capital to promising projects and applications building on Blocksense. +- **Strategic Partnerships:** Fostering integrations and business development initiatives. + +## **8\. Roadmap** + +Our path to building the universal verification layer is pragmatic and phased, prioritizing security and utility at every step. We are executing a deliberate strategy of progressive decentralization. + +- **Phase 1: Foundation & Live Services (Current)** + - **Live Network:** The Blocksense network is currently live and operational under a Proof-of-Authority (PoA) model, secured by a set of trusted, permissioned operators. + - **Developer SDK:** Our comprehensive SDK for programming intersubjective oracle services is available, allowing developers to build and deploy custom data feeds today. + - **Progressive Service Rollout:** Throughout 2025 and into 2026, we are planning to launch a suite of competitive services on our PoA network. This includes verified AI inference, low-latency oracles, pull/conditional push oracles, OEV capture, cross-chain interoperability, sports data feeds for prediction markets, ZK proof aggregation, and account abstraction solutions. +- **Phase 2: Bootstrapping Decentralization (Upcoming)** + - **EigenLayer Integration:** The next major milestone is to become an Actively Validated Service (AVS) on EigenLayer. This will allow ETH re-stakers to delegate their stake to secure the Blocksense network, dramatically increasing our crypto-economic security and providing a clear path toward decentralization. +- **Phase 3: The ZK-Native Protocol (2026)** + - **Testnet Launch (Early 2026):** The testnet for the full ZK-native consensus protocol will be launched, featuring the bribery-resistant zkSchellingCoin circuits and the on-chain Futarchy mechanism for public testing. + - **TGE & Mainnet Launch (Late 2026):** Following a successful testnet phase, we will conduct the Token Generation Event (TGE). This will be followed by the mainnet launch of the fully permissionless, Blocksense token-staked Proof-of-Stake system. Concurrent with the TGE, we will establish the Blocksense DAO for on-chain governance. +- **Phase 4: Ecosystem Maturity (Beyond)** + - **Fostering the Service-Oriented Paradigm:** With the core protocol complete, our focus will shift to fostering a vibrant and innovative ecosystem. We believe the unique capabilities of Blocksense will serve as a fertile ground for developers to create novel applications and primitives that we cannot yet anticipate. + - **DAO-led Growth:** Full control of the protocol and its treasury will be transferred to the Blocksense DAO, which will steward future research, development, and growth initiatives. + +## **9\. Conclusion** + +The prevailing paradigms in blockchain architecture have been defined by their limitations. The **Connectivity Barrier** has left them isolated, while the **Throughput Barrier** has left them slow and expensive. These constraints have relegated a technology of immense potential to a niche corner of the digital world. + +Blocksense presents a new path forward. By engineering our protocol from first principles to solve these two fundamental problems, we have created more than just a faster or more connected blockchain. We have built a universal verification layer. Our Intersubjective Truth Machine provides unbreakable, economically rational trust in any data, and our Boundless Throughput Engine provides the scale to apply that trust to any problem. + +This combination unlocks a design space for decentralized applications that was previously unimaginable. From hyper-efficient cross-chain financial services to truly autonomous AI agents, Blocksense provides the secure, scalable, and economically aligned foundation for the next wave of decentralized innovation. We invite you to join us in building this future. diff --git a/spec/content/Passkey-Based Wallet Discovery Standard.md b/spec/content/Passkey-Based Wallet Discovery Standard.md new file mode 100644 index 0000000000..422fb22527 --- /dev/null +++ b/spec/content/Passkey-Based Wallet Discovery Standard.md @@ -0,0 +1,269 @@ +# **Passkey-Based Wallet Discovery Standard: Extension-Less Blockchain Wallets via Web Standards and Iframes** + +## **1\. Introduction** + +### **1.1. Problem Statement** + +The adoption of decentralized applications (DApps) has been persistently hindered by the reliance on browser extensions for wallet interactions. This traditional model, while foundational, introduces significant friction and security concerns that are misaligned with the vision of a seamless, user-centric Web3.1 Key challenges include: + +- **Onboarding Friction:** The mandatory installation of browser-specific extensions creates a multi-step barrier to entry for new users, leading to high drop-off rates. +- **Security Vulnerabilities:** Browser extensions represent a significant attack surface, susceptible to phishing, supply-chain attacks, and permission overreach. +- **Platform Fragmentation:** The extension-based model lacks universal compatibility, failing to provide a consistent experience across different browsers and mobile environments. + +### **1.2. Proposed Solution** + +This document specifies a technical standard for the discovery and integration of passkey-based wallets that operates entirely within the browser, eliminating the need for extensions. By leveraging a combination of W3C standardsβ€”namely the **Payment Handler API** for discovery and **iframes** for secure interactionβ€”this standard enables a secure, native, and frictionless wallet experience. + +Wallet providers register themselves as payment handlers, creating a persistent but lightweight artifact in the browser. DApps can then use the standard Payment Request API to discover available wallets and initiate a secure signing process within a sandboxed iframe. + +**Key Benefits:** + +- **Truly Web-Native:** The entire workflow relies on established W3C standards, including the Payment Handler API, iframes, postMessage, and WebAuthn.2 +- **Frictionless Discovery:** DApps can perform silent, background checks for available wallets. If multiple wallets are registered, the browser presents a native, trusted UI for user selection. +- **Decentralized and Equitable:** The standard is open. Any wallet provider can register itself, and DApps can discover them dynamically without maintaining hardcoded lists or proprietary integrations. +- **Blocksense Compatibility:** The standard explicitly defines signature types that are verifiably compatible with the Blocksense protocol's ZK-native architecture, ensuring that passkey-generated signatures can be efficiently and objectively verified on-chain within Noir-based ZK circuits.1 + +--- + +## **2\. Architecture Overview** + +### **2.1. Components** + +- **Wallet Provider:** A web application (e.g., my-wallet.com) where a user creates and manages their passkey-based wallet. This site is responsible for registering itself as a payment handler. +- **Relying Party (DApp):** A decentralized application (e.g., dapp.com) that needs to interact with a user's wallet to request signatures for transactions. +- **User Agent (Browser):** The browser acts as the trusted intermediary, managing payment handler registrations, facilitating discovery, and brokering secure access to WebAuthn credentials. +- **Blocksense Protocol:** The target blockchain that verifies the cryptographic proof (signature) generated by the wallet. Its ZK-native design allows for the efficient on-chain verification of supported signature schemes.1 + +### **2.2. High-Level Workflow** + +1. **One-Time Wallet Setup:** A user visits a Wallet Provider's website. During the account creation process, the user creates a passkey via the WebAuthn API (navigator.credentials.create()). Upon success, the Wallet Provider's service worker registers itself as a payment handler. +2. **Wallet Discovery:** The user visits a DApp and clicks "Connect Wallet." The DApp uses the Payment Request API to query the browser for any registered handlers that support the standard's specified payment method. If multiple compliant wallets are found, the browser natively prompts the user to select one. +3. **Secure Connection and Signing:** The DApp embeds a sandboxed iframe pointing to the origin of the selected Wallet Provider. The DApp uses postMessage to send the transaction data to the iframe. Inside the iframe, the Wallet Provider's script calls the WebAuthn API (navigator.credentials.get()) to request a signature from the user, triggering the browser's native biometric or security key prompt. +4. **On-Chain Verification:** The iframe returns the signature to the DApp via postMessage. The DApp then submits the transaction and signature to the Blocksense network, where it is verified within a ZK circuit. + +--- + +## **3\. Technical Specification** + +### **3.1. Wallet Provider: Registration** + +A Wallet Provider **MUST** be a Progressive Web App (PWA) with a service worker. After a user successfully creates a passkey, the provider's service worker must register a payment instrument. + +**3.1.1. Instrument Registration** + +The registration is performed via navigator.paymentManager.instruments.set(). + +JavaScript + +// In the Wallet Provider's service worker (sw.js) + +// A unique identifier for this standard +const METHOD_IDENTIFIER \= 'https://passkey-wallet-standard.org/v1'; + +// After successful passkey creation and service worker registration +async function registerWalletInstrument(walletId) { +if (\!('paymentManager' in self.registration)) { +return; +} + +const instrument \= { +name: 'My Passkey Wallet', // User-visible wallet name +icons: \[{ +src: '/icons/wallet-icon-192.png', +sizes: '192x192', +type: 'image/png', +}\], +method: METHOD_IDENTIFIER, +capabilities: { +supportedSignatures: \['ecdsa-secp256r1', 'ecdsa-secp256k1'\], +supportedChains: \['blocksense', 'ethereum'\] +} +}; + +await self.registration.paymentManager.instruments.set( +\`passkey-wallet-${walletId}\`, // A unique key for the instrument +instrument +); +} + +**3.1.2. Service Worker Event Handling** + +The service worker must listen for and respond to two key events from the Payment Handler API. + +JavaScript + +// In the Wallet Provider's service worker (sw.js) + +// Respond affirmatively to availability checks from DApps. +self.addEventListener('canmakepayment', (event) \=\> { +event.respondWith(true); +}); + +// Respond to a discovery request with the wallet's details. +self.addEventListener('paymentrequest', (event) \=\> { +event.respondWith(new Promise((resolve) \=\> { +resolve({ +methodName: METHOD_IDENTIFIER, +details: { +walletOrigin: new URL(self.registration.scope).origin, +// Re-state capabilities for the DApp +supportedSignatures: \['ecdsa-secp256r1', 'ecdsa-secp256k1'\] +} +}); +})); +}); + +### **3.2. Relying Party (DApp): Discovery and Connection** + +When the user initiates a wallet connection, the DApp uses the PaymentRequest API to discover and connect to a compliant wallet. + +JavaScript + +// In the DApp's frontend script + +const METHOD_IDENTIFIER \= 'https://passkey-wallet-standard.org/v1'; + +async function connectWallet() { +if (\!window.PaymentRequest) { +// Fallback for unsupported browsers +alert("This browser doesn't support extension-less wallets."); +return; +} + +const request \= new PaymentRequest( +, +// A dummy total is required by the API +{ total: { label: 'Wallet Authentication', amount: { currency: 'USD', value: '0.00' } } } +); + +const canConnect \= await request.canMakePayment(); +if (\!canConnect) { +// Fallback if no compliant wallet is registered +alert("No passkey wallet found. Please set one up first."); +return; +} + +try { +const response \= await request.show(); +const { walletOrigin } \= response.details; + + // The transaction is "successful" from the API's perspective + await response.complete('success'); + + // Now, load the wallet's iframe to proceed with signing + loadWalletIframe(walletOrigin); + +} catch (error) { +console.error("Wallet connection failed:", error); +} +} + +function loadWalletIframe(walletOrigin) { +const iframe \= document.createElement('iframe'); +iframe.src \= \`${walletOrigin}/wallet-interface.html\`; // Standardized path + +// Crucially, grant the iframe permission to use the WebAuthn API +iframe.allow \= 'publickey-credentials-get'; + +document.body.appendChild(iframe); + +// Setup postMessage communication channel +//... (see next section) +} + +### **3.3. Secure Communication and Signing** + +Communication between the DApp and the Wallet Provider's iframe **MUST** use postMessage with strict origin checks. + +**3.3.1. DApp to Iframe: Requesting a Signature** + +JavaScript + +// In the DApp's frontend script + +// Assuming \`iframe\` and \`walletOrigin\` are available from the previous step +iframe.addEventListener('load', () \=\> { +const transactionToSign \= { /\*... transaction data... \*/ }; +iframe.contentWindow.postMessage( +{ action: 'requestSignature', data: transactionToSign }, +walletOrigin +); +}); + +**3.3.2. Iframe to DApp: Returning the Signature** + +The Wallet Provider's iframe page must be served with a Permissions-Policy HTTP header to enable WebAuthn.5 + +Example HTTP Header: +Permissions-Policy: publickey-credentials-get=\* + +JavaScript + +// In the Wallet Provider's iframe script + +window.addEventListener('message', async (event) \=\> { +// IMPORTANT: Verify the message is from the expected DApp origin +if (event.origin\!== 'https://dapp.com') { +return; +} + +if (event.data.action \=== 'requestSignature') { +try { +const credential \= await navigator.credentials.get({ +publicKey: { +challenge: new Uint8Array(event.data.data.challenge), +//... other WebAuthn options +} +}); + + // Send the signature back to the DApp + window.parent.postMessage( + { action: 'signatureResponse', signature: credential.response }, + 'https://dapp.com' // Target the DApp's origin + ); + } catch (error) { + // Handle errors (e.g., user cancellation) + window.parent.postMessage({ action: 'signatureError', error: error.message }, '\*'); + } + +} +}); + +--- + +## **4\. Signature Types for On-Chain Verification** + +A key requirement of this standard is ensuring that signatures generated via WebAuthn can be verified by Blocksense's ZK-native protocol. Wallet providers **MUST** declare the signature algorithms they support in their registration capabilities. The following table outlines the recommended signature types based on their WebAuthn compatibility and verifiability within Noir ZK circuits. + +| Signature Type | Algorithm Details | Noir Support Status | WebAuthn Compatibility | Blocksense Use Case | +| :------------------ | :------------------------------------------------- | :---------------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| **ECDSA secp256r1** | ECDSA over NIST P-256 curve (ES256). | **Native** 4 | **Yes (Default)** | Primary algorithm for passkey-based transaction signing due to its robust security and native support. | +| **ECDSA secp256k1** | ECDSA over the secp256k1 curve. | **Native** 4 | Partial (via extensions) | Essential for cross-chain compatibility, especially for interacting with Ethereum-based assets via the Blocksense bridge. | +| **RSA-PKCS1-v1_5** | RSA with PKCS\#1 v1.5 padding and SHA-256. | **Community Library** 6 | Yes (legacy support) | Enables verification of signatures from older hardware tokens or systems, such as DKIM email verification for Web2 interoperability. | +| **Schnorr** | Schnorr signatures over secp256k1 or other curves. | **Community Library** 7 | No (not standard) | Useful for advanced cryptographic schemes like efficient multi-signatures within autonomous agents. | +| **EdDSA** | Edwards-curve DSA over Ed25519. | **Community Library** 8 | No (not standard) | Ideal for privacy-preserving applications and ZK proof aggregation within the ADFS. | + +--- + +## **5\. Security and Privacy Considerations** + +- **Iframe Sandboxing:** The use of iframes naturally sandboxes the Wallet Provider's code from the DApp, preventing direct access to the DOM or JavaScript environment and mitigating cross-site scripting (XSS) risks. +- **Origin Verification:** Both the DApp and the Wallet Provider **MUST** perform strict origin checks on all messages received via postMessage to prevent malicious cross-window communication. +- **User Activation:** WebAuthn calls like navigator.credentials.get() require a transient user activation (e.g., a click) within the iframe, preventing drive-by signing attempts.5 +- **Discovery Privacy:** The canMakePayment() check is designed to be privacy-preserving. It returns a simple boolean without revealing which specific wallets are installed until the user explicitly consents by interacting with the show() prompt. + +## **6\. Future Extensions** + +- **Hybrid Passkeys:** As browser support for synced passkeys (via iCloud, Google Password Manager, etc.) matures, this standard will seamlessly support them, enabling users to access their wallets across all their devices without manual export/import. +- **Expanded Capabilities:** The capabilities object in the payment instrument registration can be extended to advertise support for other features, such as specific on-chain account abstraction modules or privacy-preserving protocols. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +2. Payment Handler API \- W3C, accessed July 31, 2025, [https://www.w3.org/TR/payment-handler/](https://www.w3.org/TR/payment-handler/) +3. Web Authentication: An API for accessing Public Key Credentials \- Level 2 \- W3C, accessed July 31, 2025, [https://www.w3.org/TR/webauthn-2/](https://www.w3.org/TR/webauthn-2/) +4. ECDSA Signature Verification | Noir Documentation, accessed July 31, 2025, [https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/ecdsa_sig_verification](https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/ecdsa_sig_verification) +5. Passkeys & iframes: How to Create & Login with a Passkey? \- Corbado, accessed July 31, 2025, [https://www.corbado.com/blog/iframe-passkeys-webauthn](https://www.corbado.com/blog/iframe-passkeys-webauthn) +6. richardliang/noir-rsa: Noir implementation of RSA-verify \- GitHub, accessed July 31, 2025, [https://github.com/richardliang/noir-rsa](https://github.com/richardliang/noir-rsa) +7. noir-lang/schnorr \- GitHub, accessed July 31, 2025, [https://github.com/noir-lang/schnorr](https://github.com/noir-lang/schnorr) +8. noir-lang/eddsa \- GitHub, accessed July 31, 2025, [https://github.com/noir-lang/eddsa](https://github.com/noir-lang/eddsa) diff --git a/spec/content/The Blocksense Execution Layer_ Design Rationale.md b/spec/content/The Blocksense Execution Layer_ Design Rationale.md new file mode 100644 index 0000000000..2f7d479b28 --- /dev/null +++ b/spec/content/The Blocksense Execution Layer_ Design Rationale.md @@ -0,0 +1,123 @@ +# **The Blocksense Execution Layer: Design Rationale** + +## **1\. Introduction: The Boundless Throughput Engine** + +The Blocksense Execution Layer is the second core component of our Decoupled State Machine Replication (DSMR) architecture. While the Ordering Layer is responsible for establishing a definitive, global sequence of transactions, the Execution Layer's mission is to process these transactions, apply the resulting state changes, and produce a succinct, verifiable proof of the entire computation. This is the heart of the "Boundless Throughput Engine," designed to overcome the computational bottlenecks that have historically limited blockchain scalability.1 + +The design of this layer was guided by a set of stringent requirements, drawing inspiration not only from blockchain technology but also from decades of research in high-performance distributed databases. + +## **2\. The Core Challenge: Deterministic Execution at Unlimited Scale** + +To achieve boundless throughput, the Blocksense network is designed to scale its ordering capacity horizontally by adding more parallel DAG-BFT consensus instances.1 The Execution Layer, therefore, faces a unique and demanding challenge: it must be able to correctly process a potentially massive influx of transactions from multiple, independent streams while adhering to the strict rules of blockchain state transition. + +This challenge can be broken down into the following core requirements: + +- **Deterministic State:** The global state of the Blocksense network must be a deterministic function of the transaction streams provided by the Ordering Layer. Given the same initial state and the same set of ordered transactions, every node must always compute the exact same final state. +- **Atomic and Isolated Execution:** The full set of reads and writes for any given transaction must be executed atomically. The system must prevent race conditions and ensure that concurrent transactions do not interfere with one another, maintaining serializable isolation. +- **Scalable Ingestion:** The Execution Layer must be able to handle an indefinitely increasing number of transaction streams from the Ordering Layer without becoming a bottleneck. +- **Support for Complex Logic:** Transactions contain arbitrary smart contract logic. The execution model must handle cases where the objects a transaction writes to are dependent on the values it first reads. +- **Deterministic Conflict Resolution:** When contention occurs (e.g., two transactions attempting to modify the same data), the mechanism for postponing or resolving the conflict must be fully deterministic. Transaction failure should never be the result of non-deterministic factors like network timing or execution speed. + +## **3\. The Architectural Blueprint: A Synthesis of Proven Concepts** + +To solve this complex set of problems, the Blocksense Execution Layer employs a "Simulation-First Parallel Pipeline".1 This architecture is a novel synthesis of three powerful concepts: + +1. **Deterministic Scheduling, inspired by the Calvin Protocol:** We adopt the core principle of the Calvin distributed database protocol: agree on a transaction order _before_ execution begins. This allows us to eliminate the non-determinism and overhead of traditional distributed commit protocols. +2. **Explicit Dependencies via the Object Model:** We leverage an object-centric data model, similar to Sui's, where transactions must explicitly declare the data (objects) they intend to access. This allows the system to statically analyze dependencies and unlock massive parallelism. +3. **Client-Side Pre-Proving:** We shift a portion of the computational work to the client by allowing users to generate ZK proofs for parts of their transactions, particularly the authorization logic. This reduces the verification load on the network and enables an ultra-fast path for simple operations. + +These three components work in concert to create a highly parallel, deterministic, and verifiable execution environment. + +### **3.1. Component 1: Deterministic Scheduling Inspired by Calvin** + +The Calvin protocol's core insight is that by decoupling transaction ordering from execution, you can eliminate the primary source of latency and non-determinism in distributed systems: the two-phase commit. We adapt this principle for the blockchain context. + +Once the Ordering Layer delivers a finalized, globally ordered batch of transactions, the Execution Layer begins its work. This is handled by a class of nodes called **Simulators**.1 + +1. **Batch Ingestion:** Simulators receive the ordered batch of transactions for the current epoch (e.g., a 10ms time slice). +2. **Deterministic Locking and Execution:** The Simulators process the transactions strictly according to the pre-agreed global order. A deterministic locking protocol ensures that if two transactions in the batch contend for the same shared object, the transaction that appears earlier in the sequence acquires the lock first. +3. **Conflict Resolution:** If a transaction attempts to acquire a lock held by a preceding transaction within the same batch, it is deterministically postponed. A "skip" proof is generated, and the transaction is rescheduled for the next execution batch with an increased reward to prevent starvation.1 + +Because the order is already known, this entire process is perfectly deterministic. Every honest Simulator node, given the same input batch, will produce the exact same set of state changes and postponed transactions, without needing to communicate with other nodes during execution. + +### **3.2. Component 2: Unlocking Parallelism with the Object Model** + +While the Calvin-inspired approach provides determinism, the key to achieving massive throughput is parallel execution. This is where the object model becomes critical. By requiring every transaction to explicitly list the objects it reads from and writes to, we can build a dependency graph for an entire batch of transactions before execution begins. + +This enables two distinct execution paths: + +- **The Fast Path (Parallel Execution):** The vast majority of blockchain transactions (e.g., asset transfers, NFT mints) involve only **owned objects**, which can only be modified by their owner. Since these transactions have no overlapping state dependencies, they are causally independent and can be executed and proven in parallel by the Simulators. This is the primary driver of Blocksense's scalability. +- **The Consensus Path (Sequential Execution):** Transactions that involve **shared objects** (e.g., interacting with a central AMM contract) are prone to contention. These are the transactions that rely on the deterministic locking mechanism described above. They are executed sequentially within the batch to ensure a consistent outcome. + +This hybrid model allows Blocksense to process the bulk of transactions with maximum parallelism while handling contentious operations with deterministic safety. + +### **3.3. Component 3: Accelerating the Pipeline with Client-Side Pre-Proving** + +To further optimize the pipeline and reduce the load on network nodes, Blocksense introduces a mechanism for client-side pre-proving. The network's use of Incrementally Verifiable Computation (IVC) breaks execution down into small, provable steps, some of which can be performed by the user themselves. + +- **Pre-Proving Authorization:** The first step of any transaction is verifying the user's authority to execute it. This is typically a self-contained computation (e.g., checking a signature or a ZK proof against an IdentityService). Users can generate a ZK proof for this authorization step on their own device. This pre-generated proof is submitted with the transaction, allowing the mempool to verify it much more cheaply than simulating the authorization logic itself. +- **The Ultimate Fast Path: Fully Pre-Proven Transactions:** For simple "fast path" transactions, such as transferring an owned object, the entire state transition can be proven client-side. The user can construct a ZK proof that demonstrates: "I am the authorized owner of this object, and I have correctly applied the state transition to transfer it to a new owner." +- **The Execution Layer as a "Proof Stitcher":** When the Execution Layer receives a batch containing these fully pre-proven transactions, its job is dramatically simplified. Instead of executing and proving the logic from scratch, it merely needs to verify the client-provided proofs and "stitch" the resulting state changes into the global state tree. This offloads the majority of the computational work for simple transactions from the network to the end-user, further enhancing scalability. + +## **4\. The Power of Incrementally Verifiable Computation (IVC)** + +The entire proving stage of the Execution Layer is built upon a powerful cryptographic primitive known as **Incrementally Verifiable Computation (IVC)**.1 IVC is a technique that allows a long sequence of computations to be proven in a highly efficient and scalable manner.2 + +### **4.1. What is IVC?** + +Imagine you have a program that runs for a million steps. Proving the entire execution in one go would require a massive amount of memory and computational power. IVC solves this by breaking the problem down.4 + +At its core, IVC allows a prover to demonstrate that a configuration x_0 correctly transitions to a final configuration x_T after T repeated applications of some function.2 It does this by generating a chain of proofs. A proof + +Ο€_n for step n attests to two facts simultaneously: + +1. The computation for step n was performed correctly (i.e., x_n is the correct result of applying the function to x_n-1). +2. The proof from the previous step, Ο€_n-1, was valid. + +This recursive structure means that verifying the final proof, Ο€_T, is sufficient to verify the integrity of the entire computation chain, from start to finish.6 The key benefit is that the size of the proof and the time it takes to update it at each step remain small and constant, regardless of the total number of steps.5 + +### **4.2. Folding Schemes: The Engine of Efficient IVC** + +A naive implementation of IVC, where each step's proof circuit includes a full verifier for the previous step's proof, would be prohibitively expensive. Modern IVC systems, such as Nova, overcome this with a technique called **folding**.6 + +A folding scheme is a lightweight protocol that takes two instances of a problem (and their corresponding witnesses) and combines them into a single new instance of the same size.9 This new "folded" instance is satisfiable only if both original instances were. This process is significantly cheaper than generating and verifying a full ZK proof. + +In the context of IVC, instead of verifying a full proof at each step, the system simply _folds_ the claim from the current step into a running "accumulator" instance. The expensive work of generating a final, succinct proof is deferred until the very end of the computation.11 + +### **4.3. Benefits for the Blocksense Execution Layer** + +Integrating IVC is fundamental to the "Boundless Throughput Engine": + +- **Massive Parallelism:** IVC allows the enormous task of proving a block's execution to be broken down into millions of small, independent steps. These "leaf" proofs can be generated in parallel by a distributed network of Prover nodes.1 +- **Efficient Aggregation:** The individual proofs are then efficiently combined up a tree using a folding scheme, resulting in a single, succinct proof for the entire block's state transition.1 +- **Constant Verification Cost:** The final proof remains small and cheap to verify, regardless of the number of transactions in the block. This is essential for our ZK-native bridges and for enabling light clients to sync instantly and securely.1 +- **Reduced Memory Overhead:** Provers do not need to hold the entire computation trace in memory at once; they only need to process one step at a time, making the system more accessible to a wider range of hardware.12 + +## **5\. The ZK Proving Engine: UltraHONK** + +The entire Execution Layer is underpinned by a state-of-the-art ZK proving system that uses IVC. The ideal ZK proving system for this architecture must have three key properties: + +1. **Fast Leaf Proofs:** Generating proofs for individual execution steps must be extremely fast. +2. **Fast Recursion/Folding:** Combining many small proofs into a single, final proof must be highly efficient. +3. **EVM Verifiability:** The final proof must be directly verifiable on EVM chains without requiring an additional, costly "wrapping" step in another proof system like Groth16. + +Currently, the **UltraHONK** proving system, as implemented in the Barretenberg backend, best satisfies these requirements. It offers rapid proof generation and produces proofs that can be verified by a Solidity smart contract, making it ideal for our ZK-native bridging goals. Blocksense actively monitors the rapidly evolving ZK landscape and provides comprehensive benchmarks at **zk-wars.blocksense.network** to ensure we are always leveraging the most efficient and secure technology available. + +## **6\. Conclusion** + +The Blocksense Execution Layer is a meticulously designed system that achieves boundless throughput by embracing determinism and parallelism. By combining a Calvin-inspired deterministic scheduling model with the explicit dependency information from our object model, we can safely parallelize the vast majority of transactions. The addition of client-side pre-proving further offloads work from the network, creating an ultra-efficient "fast path" for common operations. Underpinned by the powerful and flexible UltraHONK IVC proving system, this architecture constitutes a true Boundless Throughput Engine, capable of executing and verifying transactions at a scale that can support the global economy. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +2. simons.berkeley.edu, accessed July 31, 2025, [https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17\#:\~:text=Incrementally%20verifiable%20computation%20(IVC)%20%5B,%2Ddeterministic)%20transition%20function%20M.]() +3. Incrementally Verifiable Computation for NP from Standard Assumptions \- Simons Institute, accessed July 31, 2025, [https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17](https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17) +4. Recursive Zero-Knowledge Proofs \- sCrypt \- Medium, accessed July 31, 2025, [https://scryptplatform.medium.com/recursive-zero-knowledge-proofs-27f2d934f953](https://scryptplatform.medium.com/recursive-zero-knowledge-proofs-27f2d934f953) +5. Incrementally Verifiable Computation for NP from Standard Assumptions \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=RvaEt9awsTw](https://www.youtube.com/watch?v=RvaEt9awsTw) +6. Zero-knowledge proof composition and recursion. Part 3: Nova \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=nw4-p1KVphU](https://www.youtube.com/watch?v=nw4-p1KVphU) +7. Zero-knowledge proof composition and recursion. Part 5: PCD, IVC, and Mina \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=mS2EWydMR3Y](https://www.youtube.com/watch?v=mS2EWydMR3Y) +8. Nova Studies I: Exploring Aggregation, Recursion, and Folding | by zk.Link | zkLinkBlog, accessed July 31, 2025, [https://blog.zk.link/nova-studies-i-exploring-aggregation-recursion-and-folding-23b9a67000cd](https://blog.zk.link/nova-studies-i-exploring-aggregation-recursion-and-folding-23b9a67000cd) +9. A Review of Folding Schemes. Introduction | by Eigen Network | Medium, accessed July 31, 2025, [https://eigenlab.medium.com/a-review-of-folding-schemes-a285a790fe2f](https://eigenlab.medium.com/a-review-of-folding-schemes-a285a790fe2f) +10. Nova: Recursive Zero-Knowledge Arguments from Folding Schemes \- IACR, accessed July 31, 2025, [https://iacr.org/archive/crypto2022/135070334/135070334.pdf](https://iacr.org/archive/crypto2022/135070334/135070334.pdf) +11. Incrementally verifiable computation: NOVA \- LambdaClass Blog, accessed July 31, 2025, [https://blog.lambdaclass.com/incrementally-verifiable-computation-nova/](https://blog.lambdaclass.com/incrementally-verifiable-computation-nova/) +12. Champagne SuperNova, incrementally verifiable computation \- LambdaClass Blog, accessed July 31, 2025, [https://blog.lambdaclass.com/champagne-supernova-incrementally-verifiable-computation-2/](https://blog.lambdaclass.com/champagne-supernova-incrementally-verifiable-computation-2/) diff --git a/spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md b/spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md new file mode 100644 index 0000000000..0840b9e9ce --- /dev/null +++ b/spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md @@ -0,0 +1,71 @@ +# **The Blocksense Ordering Layer: Design Rationale for a Resilient Mempool** + +## **1\. Introduction: The Heart of the Boundless Throughput Engine** + +The Blocksense architecture is founded on the principle of Decoupled State Machine Replication (DSMR), which separates the complex task of running a blockchain into two distinct layers: an **Ordering Layer** responsible for establishing a global, definitive sequence of transactions, and an **Execution Layer** that processes the state transitions defined by that sequence.1 + +This document provides a detailed background on the design philosophy and technical architecture of the Blocksense Ordering Layer. The design of this layer is paramount, as it directly impacts the network's performance, security, and fairness. It must satisfy a demanding set of requirements to enable the high-performance oracle services and ZK-native functionalities that define the Blocksense network.1 + +## **2\. The Problem Statement: Core Requirements for the Ordering Layer** + +The design of the Blocksense Ordering Layer is guided by a set of uncompromising requirements that collectively ensure a robust, efficient, and fair platform for all participants. + +- **Uncompromising Censorship Resistance:** The system must be able to resist attempts by any single party or small coalition to prevent valid transactions from being included and ordered. This is a critical prerequisite for supporting coercion-resistant applications like MACI (Minimal Anti-Collusion Infrastructure).1 +- **Sub-Second Finality:** To minimize the latency of our oracle services and enable real-time applications, the global order of transactions must be determined and finalized in under a second.1 +- **Verifiable Finality with Zero-Knowledge Proofs:** The proof that a specific transaction order has been finalized must be expressible as a succinct ZK proof. This is essential for enabling trustless, ZK-native bridges to other chains and allowing light clients to sync to the network's state with a single proof verification.1 A ZK proof of the execution layer alone is insufficient, as it would allow for the cheap construction of alternative histories. +- **Deterministic Total Ordering:** The layer must produce a single, unambiguous, and totally ordered sequence of all transactions. This determinism is fundamental to the correctness of the state machine. +- **Precise Transaction Timestamps:** Each transaction must be assigned a reliable and agreed-upon timestamp. This is crucial for the execution layer's batching logic, which may operate on principles such as "10ms have elapsed" or "a batch of N transactions has been committed." +- **Maximal Extractable Value (MEV) Mitigation:** The design should actively prevent or mitigate extractive MEV strategies like front-running and sandwich attacks. This is achieved through mechanisms such as applying a random permutation to transactions after finalization and implementing commit-reveal schemes.1 +- **Robust Spam and Denial-of-Service (DoS) Resistance:** In a high-throughput system, preventing malicious actors from flooding the network with invalid or low-value transactions is a critical security challenge. The system must have robust mechanisms to disincentivize and penalize such behavior. + +## **3\. The Spam Challenge in Decoupled Architectures** + +In a traditional monolithic blockchain, transaction validation, ordering, and execution are tightly bundled. A block producer typically executes transactions before including them in a block, ensuring they are valid and fee-paying. + +In a DSMR architecture, this is not the case. The Ordering Layer agrees on a sequence of transactions _before_ they are fully executed. This creates a critical vulnerability highlighted in research on high-throughput systems like Avalanche's Vryx: the potential for a significant gap between **replicated TPS (rTPS)** and **finalized, fee-paying TPS (fTPS)**. + +An adversary can exploit this by submitting a high volume of transactions that are syntactically valid (and thus accepted by the Ordering Layer) but will fail during semantic validation at the Execution Layer (e.g., due to an invalid signature, insufficient funds, or a failed smart contract assertion). In this scenario, the network's validators waste valuable bandwidth, storage, and consensus resources ordering useless data, effectively launching a DoS attack that reduces the network's capacity for legitimate transactions. A successful mempool design must ensure that fTPS remains as close to rTPS as possible, even under adversarial conditions. + +## **4\. The Blocksense Approach: A Multi-Layered Defense** + +The Blocksense Ordering Layer integrates and extends state-of-the-art concepts, adapting them to our unique object ownership and account abstraction models. Our solution is a multi-layered defense system designed to make spam economically irrational and computationally ineffective. + +### **Layer 1: Pre-Consensus Validation** + +The first and most critical line of defense is a rigorous set of checks that every transaction must pass _before_ it is accepted into the mempool for ordering. Unlike traditional mempools that might gossip unverified data, Blocksense validators perform lightweight but essential semantic validation upfront. This model is inspired by Sui's architecture, where validators ensure a transaction is viable before committing consensus resources to it.2 + +To achieve this, mempool nodes (validators) must have access to the state of the objects a transaction intends to use. When a user submits a transaction, the receiving validator performs the following checks: + +1. **Authorization Verification:** The validator fetches the current state of the sender's user object and its associated IdentityService. It then simulates the authorize_user call, using the provided authorization_data and intentions to confirm that the transaction is properly authorized. This check immediately rejects transactions with invalid signatures or ZK proofs. +2. **Ownership and Gas Sufficiency:** The validator verifies that the sender owns all input objects and that the account holds sufficient funds to cover the max_gas_absolute specified in their Gas Policy. + +Only transactions that pass all these checks are signed by the validator and broadcast to the DAG for ordering. This "sane transaction" gate is the primary mechanism for preventing invalid data from consuming network resources, ensuring that only potentially valid, fee-paying transactions enter the consensus process. + +### **Layer 2: Reputation-Gated Ingress** + +The second layer of defense is a reputation system built directly into our native account abstraction model. This acts as a powerful Sybil resistance mechanism. + +- **Mechanism:** Every user object on Blocksense is assigned an on-chain reputation score. This score is a function of various factors, including account age, historical transaction volume, the value of assets held, and the ratio of successful to reverted transactions. +- **Spam Mitigation:** A user's reputation score directly determines their baseline transaction throughput limit. New accounts with zero history have a very low limit, sufficient for initial interactions but insufficient for launching a meaningful spam attack. To gain a higher throughput allowance, an account must build a positive on-chain history over time. This creates a significant economic barrier for attackers, who would need to "age" and fund a vast number of accounts to mount a large-scale DoS attack. + +### **Layer 3: Dynamic Back-Pressure and Resource Management** + +The final layer addresses a potential imbalance in the DSMR model: the risk that the Ordering Layer could accept valid transactions faster than the Execution Layer can collectively prove and finalize them. This is managed through a dynamic back-pressure mechanism. + +- **Mechanism:** Mempool nodes constantly monitor the length of the execution queueβ€”the distance between the last transaction finalized by the Ordering Layer and the last transaction for which a ZK proof has been accepted by the network. +- **Spam and Overload Mitigation:** If this queue grows beyond a safe threshold, it indicates that the network is under heavy load or that execution capacity is lagging. In response, the mempool nodes begin applying back-pressure.3 They will start rejecting new incoming transactions, and the user's client software will receive a "network congested" notification. This prevents the execution queue from growing indefinitely and ensures system stability. +- **Economic Feedback Loop:** This back-pressure mechanism is coupled with an economic incentive. A long execution queue automatically triggers higher rewards in the open market for submitting ZK proofs. This incentivizes more Prover nodes to join the network or allocate more resources to clearing the backlog, thereby increasing execution capacity and restoring balance. +- **Over-Provisioned by Design:** The Blocksense economic model encourages a large pool of hardware operators who can service both high-margin Web3 verification tasks and low-margin commodity Web2 compute jobs.1 Since participating in consensus and execution is designed to be more profitable, the network is expected to always be over-provisioned, with operators ready to shift their capacity to clear the execution queue when rewards increase. + +For this feedback loop to be effective, users must have direct, low-latency connections to the network's validators, which may be multi-homed to enhance their own DoS resilience. + +## **5\. Conclusion** + +The Blocksense Ordering Layer is a sophisticated system engineered to meet the extreme demands of a universal verification layer. By unifying the concepts of rigorous pre-consensus validation, on-chain reputation, and dynamic back-pressure, our design creates a robust, multi-layered defense against spam and DoS attacks. This architecture ensures that as the network scales to boundless throughput, it remains fair, censorship-resistant, and economically secure, providing a stable foundation for the next generation of decentralized services. + +#### **Works cited** + +1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +2. Life of a Transaction \- Sui Documentation, accessed July 31, 2025, [https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle](https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle) +3. Back Pressure in Distributed Systems \- GeeksforGeeks, accessed July 31, 2025, [https://www.geeksforgeeks.org/computer-networks/back-pressure-in-distributed-systems/](https://www.geeksforgeeks.org/computer-networks/back-pressure-in-distributed-systems/) +4. Rahasak blockchain Validate-Execute-Group architecture workflow. \- ResearchGate, accessed July 31, 2025, [https://www.researchgate.net/figure/Rahasak-blockchain-Validate-Execute-Group-architecture-workflow_fig1_349400291](https://www.researchgate.net/figure/Rahasak-blockchain-Validate-Execute-Group-architecture-workflow_fig1_349400291) From 07e8f0dd8ddd6466216d5b613dd98468734d27bf Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Tue, 12 Aug 2025 16:37:44 +0300 Subject: [PATCH 4/8] docs(spec): Organise and name the files in a more consistent way --- .../execution-layer/execution-layer-design-rationale.md} | 0 .../consensus/ordering-layer/ordering-layer-design-rationale.md} | 0 .../overview/blocksense-litepaper.md} | 0 .../overview/software-component-architecture.md} | 0 .../state-model/object-model.md} | 0 .../state-model/object-ownership-apis.md} | 0 .../state-model/predictable-address-allocation.md} | 0 .../user-experience/passkey-wallet-discovery.md} | 0 .../consensus/intersubjective-consensus-integration.md} | 0 .../sdk/oracle-service-costing.md} | 0 .../sdk/oracle-service-lifecycle.md} | 0 .../sdk/verifiable-computation-tee.md} | 0 .../cli.md} | 0 13 files changed, 0 insertions(+), 0 deletions(-) rename spec/content/{The Blocksense Execution Layer_ Design Rationale.md => core/consensus/execution-layer/execution-layer-design-rationale.md} (100%) rename spec/content/{The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md => core/consensus/ordering-layer/ordering-layer-design-rationale.md} (100%) rename spec/content/{Blocksense_ A Litepaper for the Universal Verification Layer (1).md => core/overview/blocksense-litepaper.md} (100%) rename spec/content/{Blocksense Software Component Architecture.md => core/overview/software-component-architecture.md} (100%) rename spec/content/{Blocksense SDK Documentation_ The Object Model.md => core/state-model/object-model.md} (100%) rename spec/content/{Blocksense SDK Documentation_ Object Ownership APIs.md => core/state-model/object-ownership-apis.md} (100%) rename spec/content/{Blocksense SDK Documentation_ Predictable Address Allocation.md => core/state-model/predictable-address-allocation.md} (100%) rename spec/content/{Passkey-Based Wallet Discovery Standard.md => core/user-experience/passkey-wallet-discovery.md} (100%) rename spec/content/{Blocksense Architecture_ Integrating Intersubjective Consensus.md => oracle-system/consensus/intersubjective-consensus-integration.md} (100%) rename spec/content/{Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md => oracle-system/sdk/oracle-service-costing.md} (100%) rename spec/content/{Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md => oracle-system/sdk/oracle-service-lifecycle.md} (100%) rename spec/content/{Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md => oracle-system/sdk/verifiable-computation-tee.md} (100%) rename spec/content/{Blocksense SDK Documentation_ The `blocksense` CLI.md => tooling/cli.md} (100%) diff --git a/spec/content/The Blocksense Execution Layer_ Design Rationale.md b/spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md similarity index 100% rename from spec/content/The Blocksense Execution Layer_ Design Rationale.md rename to spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md diff --git a/spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md b/spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md similarity index 100% rename from spec/content/The Blocksense Ordering Layer_ Design Rationale for a Resilient Mempool.md rename to spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md diff --git a/spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md b/spec/content/core/overview/blocksense-litepaper.md similarity index 100% rename from spec/content/Blocksense_ A Litepaper for the Universal Verification Layer (1).md rename to spec/content/core/overview/blocksense-litepaper.md diff --git a/spec/content/Blocksense Software Component Architecture.md b/spec/content/core/overview/software-component-architecture.md similarity index 100% rename from spec/content/Blocksense Software Component Architecture.md rename to spec/content/core/overview/software-component-architecture.md diff --git a/spec/content/Blocksense SDK Documentation_ The Object Model.md b/spec/content/core/state-model/object-model.md similarity index 100% rename from spec/content/Blocksense SDK Documentation_ The Object Model.md rename to spec/content/core/state-model/object-model.md diff --git a/spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md b/spec/content/core/state-model/object-ownership-apis.md similarity index 100% rename from spec/content/Blocksense SDK Documentation_ Object Ownership APIs.md rename to spec/content/core/state-model/object-ownership-apis.md diff --git a/spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md b/spec/content/core/state-model/predictable-address-allocation.md similarity index 100% rename from spec/content/Blocksense SDK Documentation_ Predictable Address Allocation.md rename to spec/content/core/state-model/predictable-address-allocation.md diff --git a/spec/content/Passkey-Based Wallet Discovery Standard.md b/spec/content/core/user-experience/passkey-wallet-discovery.md similarity index 100% rename from spec/content/Passkey-Based Wallet Discovery Standard.md rename to spec/content/core/user-experience/passkey-wallet-discovery.md diff --git a/spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md b/spec/content/oracle-system/consensus/intersubjective-consensus-integration.md similarity index 100% rename from spec/content/Blocksense Architecture_ Integrating Intersubjective Consensus.md rename to spec/content/oracle-system/consensus/intersubjective-consensus-integration.md diff --git a/spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md b/spec/content/oracle-system/sdk/oracle-service-costing.md similarity index 100% rename from spec/content/Blocksense SDK_ Oracle Service Costing, Concurrency, and Pricing Markets.md rename to spec/content/oracle-system/sdk/oracle-service-costing.md diff --git a/spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md b/spec/content/oracle-system/sdk/oracle-service-lifecycle.md similarity index 100% rename from spec/content/Blocksense SDK_ Oracle Service Lifecycle & Storage APIs.md rename to spec/content/oracle-system/sdk/oracle-service-lifecycle.md diff --git a/spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md b/spec/content/oracle-system/sdk/verifiable-computation-tee.md similarity index 100% rename from spec/content/Blocksense SDK_ Verifiable Computation with Trusted Execution Environments.md rename to spec/content/oracle-system/sdk/verifiable-computation-tee.md diff --git a/spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md b/spec/content/tooling/cli.md similarity index 100% rename from spec/content/Blocksense SDK Documentation_ The `blocksense` CLI.md rename to spec/content/tooling/cli.md From 701d67c04598f73da2891a8adbb302ee59357ed4 Mon Sep 17 00:00:00 2001 From: Zahary Karadjov Date: Tue, 12 Aug 2025 17:35:25 +0300 Subject: [PATCH 5/8] docs(spec): Restore proper Markdown footnotes across all specification documents - Convert broken Google Docs export footnote references (e.g., .1, .2) to proper Markdown footnotes - Update all 'Works cited' sections to use [^1]: format instead of numbered lists - Ensure cross-references to blocksense-litepaper.md are properly formatted - Improve readability and compatibility with GitHub and Quartz publishing --- .../execution-layer-design-rationale.md | 80 ++--- .../ordering-layer-design-rationale.md | 35 ++- .../software-component-architecture.md | 51 ++-- spec/content/core/state-model/object-model.md | 74 ++--- .../core/state-model/object-ownership-apis.md | 81 ++--- .../predictable-address-allocation.md | 36 ++- .../passkey-wallet-discovery.md | 280 ++++++++++-------- .../intersubjective-consensus-integration.md | 18 +- .../sdk/oracle-service-costing.md | 48 +-- .../sdk/oracle-service-lifecycle.md | 28 +- spec/content/tooling/cli.md | 152 +++++----- 11 files changed, 475 insertions(+), 408 deletions(-) diff --git a/spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md b/spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md index 2f7d479b28..da34de60f7 100644 --- a/spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md +++ b/spec/content/core/consensus/execution-layer/execution-layer-design-rationale.md @@ -2,13 +2,13 @@ ## **1\. Introduction: The Boundless Throughput Engine** -The Blocksense Execution Layer is the second core component of our Decoupled State Machine Replication (DSMR) architecture. While the Ordering Layer is responsible for establishing a definitive, global sequence of transactions, the Execution Layer's mission is to process these transactions, apply the resulting state changes, and produce a succinct, verifiable proof of the entire computation. This is the heart of the "Boundless Throughput Engine," designed to overcome the computational bottlenecks that have historically limited blockchain scalability.1 +The Blocksense Execution Layer is the second core component of our Decoupled State Machine Replication (DSMR) architecture. While the Ordering Layer is responsible for establishing a definitive, global sequence of transactions, the Execution Layer's mission is to process these transactions, apply the resulting state changes, and produce a succinct, verifiable proof of the entire computation. This is the heart of the "Boundless Throughput Engine," designed to overcome the computational bottlenecks that have historically limited blockchain scalability.[^1] The design of this layer was guided by a set of stringent requirements, drawing inspiration not only from blockchain technology but also from decades of research in high-performance distributed databases. ## **2\. The Core Challenge: Deterministic Execution at Unlimited Scale** -To achieve boundless throughput, the Blocksense network is designed to scale its ordering capacity horizontally by adding more parallel DAG-BFT consensus instances.1 The Execution Layer, therefore, faces a unique and demanding challenge: it must be able to correctly process a potentially massive influx of transactions from multiple, independent streams while adhering to the strict rules of blockchain state transition. +To achieve boundless throughput, the Blocksense network is designed to scale its ordering capacity horizontally by adding more parallel DAG-BFT consensus instances.[^1] The Execution Layer, therefore, faces a unique and demanding challenge: it must be able to correctly process a potentially massive influx of transactions from multiple, independent streams while adhering to the strict rules of blockchain state transition. This challenge can be broken down into the following core requirements: @@ -20,7 +20,7 @@ This challenge can be broken down into the following core requirements: ## **3\. The Architectural Blueprint: A Synthesis of Proven Concepts** -To solve this complex set of problems, the Blocksense Execution Layer employs a "Simulation-First Parallel Pipeline".1 This architecture is a novel synthesis of three powerful concepts: +To solve this complex set of problems, the Blocksense Execution Layer employs a "Simulation-First Parallel Pipeline".[^1] This architecture is a novel synthesis of three powerful concepts: 1. **Deterministic Scheduling, inspired by the Calvin Protocol:** We adopt the core principle of the Calvin distributed database protocol: agree on a transaction order _before_ execution begins. This allows us to eliminate the non-determinism and overhead of traditional distributed commit protocols. 2. **Explicit Dependencies via the Object Model:** We leverage an object-centric data model, similar to Sui's, where transactions must explicitly declare the data (objects) they intend to access. This allows the system to statically analyze dependencies and unlock massive parallelism. @@ -32,11 +32,11 @@ These three components work in concert to create a highly parallel, deterministi The Calvin protocol's core insight is that by decoupling transaction ordering from execution, you can eliminate the primary source of latency and non-determinism in distributed systems: the two-phase commit. We adapt this principle for the blockchain context. -Once the Ordering Layer delivers a finalized, globally ordered batch of transactions, the Execution Layer begins its work. This is handled by a class of nodes called **Simulators**.1 +Once the Ordering Layer delivers a finalized, globally ordered batch of transactions, the Execution Layer begins its work. This is handled by a class of nodes called **Simulators**.[^1] 1. **Batch Ingestion:** Simulators receive the ordered batch of transactions for the current epoch (e.g., a 10ms time slice). 2. **Deterministic Locking and Execution:** The Simulators process the transactions strictly according to the pre-agreed global order. A deterministic locking protocol ensures that if two transactions in the batch contend for the same shared object, the transaction that appears earlier in the sequence acquires the lock first. -3. **Conflict Resolution:** If a transaction attempts to acquire a lock held by a preceding transaction within the same batch, it is deterministically postponed. A "skip" proof is generated, and the transaction is rescheduled for the next execution batch with an increased reward to prevent starvation.1 +3. **Conflict Resolution:** If a transaction attempts to acquire a lock held by a preceding transaction within the same batch, it is deterministically postponed. A "skip" proof is generated, and the transaction is rescheduled for the next execution batch with an increased reward to prevent starvation.[^1] Because the order is already known, this entire process is perfectly deterministic. Every honest Simulator node, given the same input batch, will produce the exact same set of state changes and postponed transactions, without needing to communicate with other nodes during execution. @@ -61,37 +61,38 @@ To further optimize the pipeline and reduce the load on network nodes, Blocksens ## **4\. The Power of Incrementally Verifiable Computation (IVC)** -The entire proving stage of the Execution Layer is built upon a powerful cryptographic primitive known as **Incrementally Verifiable Computation (IVC)**.1 IVC is a technique that allows a long sequence of computations to be proven in a highly efficient and scalable manner.2 +The entire proving stage of the Execution Layer is built upon a powerful cryptographic primitive known as **Incrementally Verifiable Computation (IVC)**.[^2] IVC is a technique that allows a long sequence of computations to be proven in a highly efficient and scalable manner.[^3] ### **4.1. What is IVC?** -Imagine you have a program that runs for a million steps. Proving the entire execution in one go would require a massive amount of memory and computational power. IVC solves this by breaking the problem down.4 +Imagine you have a program that runs for a million steps. Proving the entire execution in one go would require a massive amount of memory and computational power. IVC solves this by breaking the problem down.[^4] -At its core, IVC allows a prover to demonstrate that a configuration x_0 correctly transitions to a final configuration x_T after T repeated applications of some function.2 It does this by generating a chain of proofs. A proof +At its core, IVC allows a prover to demonstrate that a configuration xβ‚€ correctly transitions to a final configuration x_T after T repeated applications of some function. It does this by generating a chain of proofs. A proof Ο€_n for step n attests to two facts simultaneously: -Ο€_n for step n attests to two facts simultaneously: +1. The computation for step n was performed correctly (i.e., x*n is the correct result of applying the function to x*{n-1}). +2. The proof from the previous step, Ο€\_{n-1}, was valid. -1. The computation for step n was performed correctly (i.e., x_n is the correct result of applying the function to x_n-1). -2. The proof from the previous step, Ο€_n-1, was valid. - -This recursive structure means that verifying the final proof, Ο€_T, is sufficient to verify the integrity of the entire computation chain, from start to finish.6 The key benefit is that the size of the proof and the time it takes to update it at each step remain small and constant, regardless of the total number of steps.5 +This recursive structure means that verifying the final proof, Ο€_T, is sufficient to verify the integrity of the entire computation chain, from start to finish.[^6] The key benefit is that the size of the proof and the time it takes to update it at each step remain small and constant, regardless of the total number of steps.[^5] ### **4.2. Folding Schemes: The Engine of Efficient IVC** -A naive implementation of IVC, where each step's proof circuit includes a full verifier for the previous step's proof, would be prohibitively expensive. Modern IVC systems, such as Nova, overcome this with a technique called **folding**.6 +A naive implementation of IVC, where each step's proof circuit includes a full verifier for the previous step's proof, would be prohibitively expensive. Modern IVC systems, such as Nova, overcome this with a technique called **folding**.[^6] -A folding scheme is a lightweight protocol that takes two instances of a problem (and their corresponding witnesses) and combines them into a single new instance of the same size.9 This new "folded" instance is satisfiable only if both original instances were. This process is significantly cheaper than generating and verifying a full ZK proof. +A folding scheme is a lightweight protocol that takes two instances of a problem (and their corresponding witnesses) and combines them into a single new instance of the same size.[^9] This new "folded" instance is satisfiable only if both original instances were. This process is significantly cheaper than generating and verifying a full ZK proof. -In the context of IVC, instead of verifying a full proof at each step, the system simply _folds_ the claim from the current step into a running "accumulator" instance. The expensive work of generating a final, succinct proof is deferred until the very end of the computation.11 +In the context of IVC, instead of verifying a full proof at each step, the system simply _folds_ the claim from the current step into a running "accumulator" instance. The expensive work of generating a final, succinct proof is deferred until the very end of the computation.[^11] ### **4.3. Benefits for the Blocksense Execution Layer** Integrating IVC is fundamental to the "Boundless Throughput Engine": -- **Massive Parallelism:** IVC allows the enormous task of proving a block's execution to be broken down into millions of small, independent steps. These "leaf" proofs can be generated in parallel by a distributed network of Prover nodes.1 -- **Efficient Aggregation:** The individual proofs are then efficiently combined up a tree using a folding scheme, resulting in a single, succinct proof for the entire block's state transition.1 -- **Constant Verification Cost:** The final proof remains small and cheap to verify, regardless of the number of transactions in the block. This is essential for our ZK-native bridges and for enabling light clients to sync instantly and securely.1 -- **Reduced Memory Overhead:** Provers do not need to hold the entire computation trace in memory at once; they only need to process one step at a time, making the system more accessible to a wider range of hardware.12 +- **Massive Parallelism:** IVC allows the enormous task of proving a block's execution to be broken down into millions of small, independent steps. These "leaf" proofs can be generated in parallel by a distributed network of Prover nodes.[^1] + +- **Efficient Aggregation:** The individual proofs are then efficiently combined up a tree using a folding scheme, resulting in a single, succinct proof for the entire block's state transition.[^1] + +- **Constant Verification Cost:** The final proof remains small and cheap to verify, regardless of the number of transactions in the block. This is essential for our ZK-native bridges and for enabling light clients to sync instantly and securely.[^1] + +- **Reduced Memory Overhead:** Provers do not need to hold the entire computation trace in memory at once; they only need to process one step at a time, making the system more accessible to a wider range of hardware.[^12] ## **5\. The ZK Proving Engine: UltraHONK** @@ -107,17 +108,28 @@ Currently, the **UltraHONK** proving system, as implemented in the Barretenberg The Blocksense Execution Layer is a meticulously designed system that achieves boundless throughput by embracing determinism and parallelism. By combining a Calvin-inspired deterministic scheduling model with the explicit dependency information from our object model, we can safely parallelize the vast majority of transactions. The addition of client-side pre-proving further offloads work from the network, creating an ultra-efficient "fast path" for common operations. Underpinned by the powerful and flexible UltraHONK IVC proving system, this architecture constitutes a true Boundless Throughput Engine, capable of executing and verifying transactions at a scale that can support the global economy. -#### **Works cited** - -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf -2. simons.berkeley.edu, accessed July 31, 2025, [https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17\#:\~:text=Incrementally%20verifiable%20computation%20(IVC)%20%5B,%2Ddeterministic)%20transition%20function%20M.]() -3. Incrementally Verifiable Computation for NP from Standard Assumptions \- Simons Institute, accessed July 31, 2025, [https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17](https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17) -4. Recursive Zero-Knowledge Proofs \- sCrypt \- Medium, accessed July 31, 2025, [https://scryptplatform.medium.com/recursive-zero-knowledge-proofs-27f2d934f953](https://scryptplatform.medium.com/recursive-zero-knowledge-proofs-27f2d934f953) -5. Incrementally Verifiable Computation for NP from Standard Assumptions \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=RvaEt9awsTw](https://www.youtube.com/watch?v=RvaEt9awsTw) -6. Zero-knowledge proof composition and recursion. Part 3: Nova \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=nw4-p1KVphU](https://www.youtube.com/watch?v=nw4-p1KVphU) -7. Zero-knowledge proof composition and recursion. Part 5: PCD, IVC, and Mina \- YouTube, accessed July 31, 2025, [https://www.youtube.com/watch?v=mS2EWydMR3Y](https://www.youtube.com/watch?v=mS2EWydMR3Y) -8. Nova Studies I: Exploring Aggregation, Recursion, and Folding | by zk.Link | zkLinkBlog, accessed July 31, 2025, [https://blog.zk.link/nova-studies-i-exploring-aggregation-recursion-and-folding-23b9a67000cd](https://blog.zk.link/nova-studies-i-exploring-aggregation-recursion-and-folding-23b9a67000cd) -9. A Review of Folding Schemes. Introduction | by Eigen Network | Medium, accessed July 31, 2025, [https://eigenlab.medium.com/a-review-of-folding-schemes-a285a790fe2f](https://eigenlab.medium.com/a-review-of-folding-schemes-a285a790fe2f) -10. Nova: Recursive Zero-Knowledge Arguments from Folding Schemes \- IACR, accessed July 31, 2025, [https://iacr.org/archive/crypto2022/135070334/135070334.pdf](https://iacr.org/archive/crypto2022/135070334/135070334.pdf) -11. Incrementally verifiable computation: NOVA \- LambdaClass Blog, accessed July 31, 2025, [https://blog.lambdaclass.com/incrementally-verifiable-computation-nova/](https://blog.lambdaclass.com/incrementally-verifiable-computation-nova/) -12. Champagne SuperNova, incrementally verifiable computation \- LambdaClass Blog, accessed July 31, 2025, [https://blog.lambdaclass.com/champagne-supernova-incrementally-verifiable-computation-2/](https://blog.lambdaclass.com/champagne-supernova-incrementally-verifiable-computation-2/) +## **Works Cited** + +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles + +[^2]: [Incrementally Verifiable Computation for NP from Standard Assumptions]()%20transition%20function%20M.) - Simons Institute, accessed July 31, 2025 + +[^3]: [Incrementally Verifiable Computation for NP from Standard Assumptions](https://simons.berkeley.edu/talks/surya-mathialagan-mit-2025-07-17) - Simons Institute, accessed July 31, 2025 + +[^4]: [Recursive Zero-Knowledge Proofs](https://scryptplatform.medium.com/recursive-zero-knowledge-proofs-27f2d934f953) - sCrypt - Medium, accessed July 31, 2025 + +[^5]: [Incrementally Verifiable Computation for NP from Standard Assumptions](https://www.youtube.com/watch?v=RvaEt9awsTw) - YouTube, accessed July 31, 2025 + +[^6]: [Zero-knowledge proof composition and recursion. Part 3: Nova](https://www.youtube.com/watch?v=nw4-p1KVphU) - YouTube, accessed July 31, 2025 + +[^7]: [Zero-knowledge proof composition and recursion. Part 5: PCD, IVC, and Mina](https://www.youtube.com/watch?v=mS2EWydMR3Y) - YouTube, accessed July 31, 2025 + +[^8]: [Nova Studies I: Exploring Aggregation, Recursion, and Folding](https://blog.zk.link/nova-studies-i-exploring-aggregation-recursion-and-folding-23b9a67000cd) | by zk.Link | zkLinkBlog, accessed July 31, 2025 + +[^9]: [A Review of Folding Schemes. Introduction](https://eigenlab.medium.com/a-review-of-folding-schemes-a285a790fe2f) | by Eigen Network | Medium, accessed July 31, 2025 + +[^10]: [Nova: Recursive Zero-Knowledge Arguments from Folding Schemes](https://iacr.org/archive/crypto2022/135070334/135070334.pdf) - IACR, accessed July 31, 2025 + +[^11]: [Incrementally verifiable computation: NOVA](https://blog.lambdaclass.com/incrementally-verifiable-computation-nova/) - LambdaClass Blog, accessed July 31, 2025 + +[^12]: [Champagne SuperNova, incrementally verifiable computation](https://blog.lambdaclass.com/champagne-supernova-incrementally-verifiable-computation-2/) - LambdaClass Blog, accessed July 31, 2025 diff --git a/spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md b/spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md index 0840b9e9ce..78cf2cddd3 100644 --- a/spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md +++ b/spec/content/core/consensus/ordering-layer/ordering-layer-design-rationale.md @@ -2,20 +2,20 @@ ## **1\. Introduction: The Heart of the Boundless Throughput Engine** -The Blocksense architecture is founded on the principle of Decoupled State Machine Replication (DSMR), which separates the complex task of running a blockchain into two distinct layers: an **Ordering Layer** responsible for establishing a global, definitive sequence of transactions, and an **Execution Layer** that processes the state transitions defined by that sequence.1 +The Blocksense architecture is founded on the principle of Decoupled State Machine Replication (DSMR), which separates the complex task of running a blockchain into two distinct layers: an **Ordering Layer** responsible for establishing a global, definitive sequence of transactions, and an **Execution Layer** that processes the state transitions defined by that sequence.[^1] -This document provides a detailed background on the design philosophy and technical architecture of the Blocksense Ordering Layer. The design of this layer is paramount, as it directly impacts the network's performance, security, and fairness. It must satisfy a demanding set of requirements to enable the high-performance oracle services and ZK-native functionalities that define the Blocksense network.1 +This document provides a detailed background on the design philosophy and technical architecture of the Blocksense Ordering Layer. The design of this layer is paramount, as it directly impacts the network's performance, security, and fairness. It must satisfy a demanding set of requirements to enable the high-performance oracle services and ZK-native functionalities that define the Blocksense network.[^1] ## **2\. The Problem Statement: Core Requirements for the Ordering Layer** The design of the Blocksense Ordering Layer is guided by a set of uncompromising requirements that collectively ensure a robust, efficient, and fair platform for all participants. -- **Uncompromising Censorship Resistance:** The system must be able to resist attempts by any single party or small coalition to prevent valid transactions from being included and ordered. This is a critical prerequisite for supporting coercion-resistant applications like MACI (Minimal Anti-Collusion Infrastructure).1 -- **Sub-Second Finality:** To minimize the latency of our oracle services and enable real-time applications, the global order of transactions must be determined and finalized in under a second.1 -- **Verifiable Finality with Zero-Knowledge Proofs:** The proof that a specific transaction order has been finalized must be expressible as a succinct ZK proof. This is essential for enabling trustless, ZK-native bridges to other chains and allowing light clients to sync to the network's state with a single proof verification.1 A ZK proof of the execution layer alone is insufficient, as it would allow for the cheap construction of alternative histories. +- **Uncompromising Censorship Resistance:** The system must be able to resist attempts by any single party or small coalition to prevent valid transactions from being included and ordered. This is a critical prerequisite for supporting coercion-resistant applications like MACI (Minimal Anti-Collusion Infrastructure).[^1] +- **Sub-Second Finality:** To minimize the latency of our oracle services and enable real-time applications, the global order of transactions must be determined and finalized in under a second.[^1] +- **Verifiable Finality with Zero-Knowledge Proofs:** The proof that a specific transaction order has been finalized must be expressible as a succinct ZK proof. This is essential for enabling trustless, ZK-native bridges to other chains and allowing light clients to sync to the network's state with a single proof verification. A ZK proof of the execution layer alone is insufficient, as it would allow for the cheap construction of alternative histories.[^1] - **Deterministic Total Ordering:** The layer must produce a single, unambiguous, and totally ordered sequence of all transactions. This determinism is fundamental to the correctness of the state machine. - **Precise Transaction Timestamps:** Each transaction must be assigned a reliable and agreed-upon timestamp. This is crucial for the execution layer's batching logic, which may operate on principles such as "10ms have elapsed" or "a batch of N transactions has been committed." -- **Maximal Extractable Value (MEV) Mitigation:** The design should actively prevent or mitigate extractive MEV strategies like front-running and sandwich attacks. This is achieved through mechanisms such as applying a random permutation to transactions after finalization and implementing commit-reveal schemes.1 +- **Maximal Extractable Value (MEV) Mitigation:** The design should actively prevent or mitigate extractive MEV strategies like front-running and sandwich attacks. This is achieved through mechanisms such as applying a random permutation to transactions after finalization and implementing commit-reveal schemes.[^1] - **Robust Spam and Denial-of-Service (DoS) Resistance:** In a high-throughput system, preventing malicious actors from flooding the network with invalid or low-value transactions is a critical security challenge. The system must have robust mechanisms to disincentivize and penalize such behavior. ## **3\. The Spam Challenge in Decoupled Architectures** @@ -32,12 +32,12 @@ The Blocksense Ordering Layer integrates and extends state-of-the-art concepts, ### **Layer 1: Pre-Consensus Validation** -The first and most critical line of defense is a rigorous set of checks that every transaction must pass _before_ it is accepted into the mempool for ordering. Unlike traditional mempools that might gossip unverified data, Blocksense validators perform lightweight but essential semantic validation upfront. This model is inspired by Sui's architecture, where validators ensure a transaction is viable before committing consensus resources to it.2 +The first and most critical line of defense is a rigorous set of checks that every transaction must pass _before_ it is accepted into the mempool for ordering. Unlike traditional mempools that might gossip unverified data, Blocksense validators perform lightweight but essential semantic validation upfront. This model is inspired by Sui's architecture, where validators ensure a transaction is viable before committing consensus resources to it.[^2] To achieve this, mempool nodes (validators) must have access to the state of the objects a transaction intends to use. When a user submits a transaction, the receiving validator performs the following checks: -1. **Authorization Verification:** The validator fetches the current state of the sender's user object and its associated IdentityService. It then simulates the authorize_user call, using the provided authorization_data and intentions to confirm that the transaction is properly authorized. This check immediately rejects transactions with invalid signatures or ZK proofs. -2. **Ownership and Gas Sufficiency:** The validator verifies that the sender owns all input objects and that the account holds sufficient funds to cover the max_gas_absolute specified in their Gas Policy. +1. **Authorization Verification:** The validator fetches the current state of the sender's user object and its associated `IdentityService`. It then simulates the `authorize_user` call, using the provided `authorization_data` and `intentions` to confirm that the transaction is properly authorized. This check immediately rejects transactions with invalid signatures or ZK proofs. +2. **Ownership and Gas Sufficiency:** The validator verifies that the sender owns all input objects and that the account holds sufficient funds to cover the `max_gas_absolute` specified in their Gas Policy. Only transactions that pass all these checks are signed by the validator and broadcast to the DAG for ordering. This "sane transaction" gate is the primary mechanism for preventing invalid data from consuming network resources, ensuring that only potentially valid, fee-paying transactions enter the consensus process. @@ -53,9 +53,9 @@ The second layer of defense is a reputation system built directly into our nativ The final layer addresses a potential imbalance in the DSMR model: the risk that the Ordering Layer could accept valid transactions faster than the Execution Layer can collectively prove and finalize them. This is managed through a dynamic back-pressure mechanism. - **Mechanism:** Mempool nodes constantly monitor the length of the execution queueβ€”the distance between the last transaction finalized by the Ordering Layer and the last transaction for which a ZK proof has been accepted by the network. -- **Spam and Overload Mitigation:** If this queue grows beyond a safe threshold, it indicates that the network is under heavy load or that execution capacity is lagging. In response, the mempool nodes begin applying back-pressure.3 They will start rejecting new incoming transactions, and the user's client software will receive a "network congested" notification. This prevents the execution queue from growing indefinitely and ensures system stability. +- **Spam and Overload Mitigation:** If this queue grows beyond a safe threshold, it indicates that the network is under heavy load or that execution capacity is lagging. In response, the mempool nodes begin applying back-pressure.[^3] They will start rejecting new incoming transactions, and the user's client software will receive a "network congested" notification. This prevents the execution queue from growing indefinitely and ensures system stability. - **Economic Feedback Loop:** This back-pressure mechanism is coupled with an economic incentive. A long execution queue automatically triggers higher rewards in the open market for submitting ZK proofs. This incentivizes more Prover nodes to join the network or allocate more resources to clearing the backlog, thereby increasing execution capacity and restoring balance. -- **Over-Provisioned by Design:** The Blocksense economic model encourages a large pool of hardware operators who can service both high-margin Web3 verification tasks and low-margin commodity Web2 compute jobs.1 Since participating in consensus and execution is designed to be more profitable, the network is expected to always be over-provisioned, with operators ready to shift their capacity to clear the execution queue when rewards increase. +- **Over-Provisioned by Design:** The Blocksense economic model encourages a large pool of hardware operators who can service both high-margin Web3 verification tasks and low-margin commodity Web2 compute jobs.[^1] Since participating in consensus and execution is designed to be more profitable, the network is expected to always be over-provisioned, with operators ready to shift their capacity to clear the execution queue when rewards increase. For this feedback loop to be effective, users must have direct, low-latency connections to the network's validators, which may be multi-homed to enhance their own DoS resilience. @@ -63,9 +63,12 @@ For this feedback loop to be effective, users must have direct, low-latency conn The Blocksense Ordering Layer is a sophisticated system engineered to meet the extreme demands of a universal verification layer. By unifying the concepts of rigorous pre-consensus validation, on-chain reputation, and dynamic back-pressure, our design creates a robust, multi-layered defense against spam and DoS attacks. This architecture ensures that as the network scales to boundless throughput, it remains fair, censorship-resistant, and economically secure, providing a stable foundation for the next generation of decentralized services. -#### **Works cited** +## **Works Cited** -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf -2. Life of a Transaction \- Sui Documentation, accessed July 31, 2025, [https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle](https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle) -3. Back Pressure in Distributed Systems \- GeeksforGeeks, accessed July 31, 2025, [https://www.geeksforgeeks.org/computer-networks/back-pressure-in-distributed-systems/](https://www.geeksforgeeks.org/computer-networks/back-pressure-in-distributed-systems/) -4. Rahasak blockchain Validate-Execute-Group architecture workflow. \- ResearchGate, accessed July 31, 2025, [https://www.researchgate.net/figure/Rahasak-blockchain-Validate-Execute-Group-architecture-workflow_fig1_349400291](https://www.researchgate.net/figure/Rahasak-blockchain-Validate-Execute-Group-architecture-workflow_fig1_349400291) +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles + +[^2]: [Life of a Transaction](https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle) - Sui Documentation, accessed July 31, 2025 + +[^3]: [Back Pressure in Distributed Systems](https://www.geeksforgeeks.org/computer-networks/back-pressure-in-distributed-systems/) - GeeksforGeeks, accessed July 31, 2025 + +[^4]: [Rahasak blockchain Validate-Execute-Group architecture workflow](https://www.researchgate.net/figure/Rahasak-blockchain-Validate-Execute-Group-architecture-workflow_fig1_349400291) - ResearchGate, accessed July 31, 2025 diff --git a/spec/content/core/overview/software-component-architecture.md b/spec/content/core/overview/software-component-architecture.md index 3386319aee..bc4cc24ef1 100644 --- a/spec/content/core/overview/software-component-architecture.md +++ b/spec/content/core/overview/software-component-architecture.md @@ -81,29 +81,32 @@ The official compiler for the Blocksense Noir language, used to develop Objectiv ## **5\. Component Interaction Diagram** The following diagram illustrates the high-level interactions between the core components of a Blocksense node. -\+---------------------------------+ -| Developer (via Shell) | -\+---------------------------------+ -| -v -\+---------------------------------+ -| Blocksense CLI (\`blocksense\`) | -\+---------------------------------+ -| (RPC) -v -\+---------------------------------+ \+------------------------------------------+ -| Blocksense Daemon (\`blocksensed\`)|-----\>| Blocksense Network (Peers/Consensus) | -| |\<-----| | -| \- Manages Config & Duties | \+------------------------------------------+ -| \- Launches Duty Components | -\+---------------------------------+ -| (IPC) | (Launches Process) -v \+-------------------\> \[ Duty-Specific Components \] -\+---------------------+ | -| Credentials Manager | | e.g., blocksense-oracle-runtime -| (\`blocksense-creds\`)| | blocksense-sim -| \- Holds Keys | | blocksense-prover -| \- Signs Payloads | | -\+---------------------+ \+------------------------------------------+ + +``` ++---------------------------------+ +| Developer (via Shell) | ++---------------------------------+ + | + v ++---------------------------------+ +| Blocksense CLI (`blocksense`) | ++---------------------------------+ + | (RPC) + v ++---------------------------------+ +------------------------------------------+ +| Blocksense Daemon (`blocksensed`)|----->| Blocksense Network (Peers/Consensus) | +| |<-----| | +| - Manages Config & Duties | +------------------------------------------+ +| - Launches Duty Components | ++---------------------------------+ + | (IPC) | (Launches Process) + v +-------------------> [ Duty-Specific Components ] ++---------------------+ | +| Credentials Manager | | e.g., blocksense-oracle-runtime +| (`blocksense-creds`)| | blocksense-sim +| - Holds Keys | | blocksense-prover +| - Signs Payloads | | ++---------------------+ +------------------------------------------+ +``` This modular architecture ensures that Blocksense is not only powerful and scalable but also secure, flexible, and easy to develop for and maintain. diff --git a/spec/content/core/state-model/object-model.md b/spec/content/core/state-model/object-model.md index 4b7cd22878..739759c771 100644 --- a/spec/content/core/state-model/object-model.md +++ b/spec/content/core/state-model/object-model.md @@ -1,22 +1,20 @@ # **Blocksense SDK Documentation: The Object Model & Parallel Execution** -A core innovation of the Blocksense network, and the key to its "Boundless Throughput Engine," is its state architecture.1 Unlike traditional blockchains that rely on an account-based model, Blocksense employs an - -**object-centric model** inspired by the design of the Sui blockchain.2 +A core innovation of the Blocksense network, and the key to its "Boundless Throughput Engine," is its state architecture.[^1] Unlike traditional blockchains that rely on an account-based model, Blocksense employs an **object-centric model** inspired by the design of the Sui blockchain.[^2] This design fundamentally changes how the network processes transactions, moving away from a sequential bottleneck to a massively parallel execution environment. Understanding this model is crucial for developers, as the way you structure your application's state directly impacts its performance and scalability on Blocksense. ## **The Problem with Sequential Execution** -Most blockchains, such as Ethereum, use an account-based model where the entire state of the network is represented as a single, large data structure.3 Smart contracts are accounts that hold code and data, and transactions modify this global state. +Most blockchains, such as Ethereum, use an account-based model where the entire state of the network is represented as a single, large data structure.[^3] Smart contracts are accounts that hold code and data, and transactions modify this global state. -This model has a significant drawback: to prevent conflicts (like double-spending), transactions must be processed sequentially, one after another, and ordered into blocks.4 This creates a global queue where every transaction, regardless of what it's doing, has to wait its turn. This sequential processing is a primary cause of the throughput limitations and high fees seen on many networks.5 +This model has a significant drawback: to prevent conflicts (like double-spending), transactions must be processed sequentially, one after another, and ordered into blocks.[^4] This creates a global queue where every transaction, regardless of what it's doing, has to wait its turn. This sequential processing is a primary cause of the throughput limitations and high fees seen on many networks.[^5] ## **The Blocksense Solution: A World of Objects** -Blocksense's state is not a single ledger but a collection of individual, programmable **objects**.2 An object is the basic unit of storage and can represent anything: a token, an NFT, a smart contract, or a complex data structure.4 +Blocksense's state is not a single ledger but a collection of individual, programmable **objects**.[^2] An object is the basic unit of storage and can represent anything: a token, an NFT, a smart contract, or a complex data structure.[^4] -Each object has a globally unique ID and metadata that defines its properties and, most importantly, its **ownership**. This explicit declaration of ownership is the key that unlocks parallel execution.7 +Each object has a globally unique ID and metadata that defines its properties and, most importantly, its **ownership**. This explicit declaration of ownership is the key that unlocks parallel execution.[^7] ### **Types of Object Ownership** @@ -24,27 +22,27 @@ There are three primary ownership categories for objects in Blocksense: 1. **Owned Objects:** An object that is owned by a single external address (a user account). Only the owner can initiate a transaction that modifies this object. The vast majority of assets, such as a user's tokens or NFTs, are owned objects. 2. **Shared Objects:** An object that has no specific owner and can be read or modified by any user. Shared objects are the mechanism for creating collaborative applications where multiple users need to interact with the same state, such as a decentralized exchange's liquidity pool or an on-chain auction contract. -3. **Immutable Objects (Frozen):** An object that cannot be modified by anyone after it has been published. Smart contract packages (the code itself) are a prime example of immutable objects.3 +3. **Immutable Objects (Frozen):** An object that cannot be modified by anyone after it has been published. Smart contract packages (the code itself) are a prime example of immutable objects.[^3] ## **How the Object Model Enables Parallel Execution** -The power of the object model lies in making data dependencies explicit. Every transaction must declare upfront which objects it will access and how (read-only or read-write). This allows the Blocksense network to analyze the dependencies of all incoming transactions _before_ executing them.2 +The power of the object model lies in making data dependencies explicit. Every transaction must declare upfront which objects it will access and how (read-only or read-write). This allows the Blocksense network to analyze the dependencies of all incoming transactions _before_ executing them.[^2] The execution logic is simple but powerful: -- **If two transactions do not access any of the same objects, they are causally independent and can be executed in parallel without any possibility of conflict**.2 +- **If two transactions do not access any of the same objects, they are causally independent and can be executed in parallel without any possibility of conflict**.[^2] - **If two transactions only read from the same immutable or shared object, they can also be executed in parallel**. -- **Only when two or more transactions attempt to _modify_ the same shared object is there a data conflict**. In this case, and only in this case, the network must order these specific transactions to ensure a deterministic outcome.4 +- **Only when two or more transactions attempt to _modify_ the same shared object is there a data conflict**. In this case, and only in this case, the network must order these specific transactions to ensure a deterministic outcome.[^4] -This approach is a paradigm shift from the **total ordering** of traditional blockchains to a more efficient **causal ordering**.10 Instead of ordering everything, Blocksense only orders the small subset of transactions that actually have conflicting dependencies. +This approach is a paradigm shift from the **total ordering** of traditional blockchains to a more efficient **causal ordering**.[^10] Instead of ordering everything, Blocksense only orders the small subset of transactions that actually have conflicting dependencies. ### **The "Simulation-First" Pipeline** -This principle is put into practice by Blocksense's "Simulation-First Parallel Pipeline".1 +This principle is put into practice by Blocksense's "Simulation-First Parallel Pipeline".[^1] 1. **Dependency Analysis:** The network receives a set of transactions and immediately analyzes their declared object dependencies. -2. **Parallel Simulation:** "Simulator" nodes attempt to execute all causally independent transactions in parallel. Since most transactions in a typical workload (e.g., peer-to-peer payments, NFT transfers) involve only owned objects, they can be processed concurrently with near-zero conflict.7 -3. **Conflict Resolution:** If a conflict is detected on a shared object, one of the conflicting transactions is simply postponed to the next execution batch. This process is extremely fast and efficient.1 +2. **Parallel Simulation:** "Simulator" nodes attempt to execute all causally independent transactions in parallel. Since most transactions in a typical workload (e.g., peer-to-peer payments, NFT transfers) involve only owned objects, they can be processed concurrently with near-zero conflict.[^7] +3. **Conflict Resolution:** If a conflict is detected on a shared object, one of the conflicting transactions is simply postponed to the next execution batch. This process is extremely fast and efficient.[^1] ## **Benefits for Scalability and Developers** @@ -52,28 +50,38 @@ This architecture provides transformative benefits for both network performance ### **For Scalability:** -- **Massive Throughput:** By breaking the sequential bottleneck, Blocksense's throughput can scale horizontally with the addition of more CPU cores to validator nodes. This allows the network to achieve extremely high transactions per second (TPS), capable of supporting enterprise-grade applications.5 -- **Low Latency & Near-Instant Finality:** Simple transactions involving only owned objects (e.g., transferring a token to a friend) do not require complex consensus. They can be validated and finalized almost instantly, providing a user experience comparable to Web2 applications.6 -- **Reduced Network Congestion:** Because independent transactions don't have to wait for each other, the network is far more resilient to congestion, leading to more stable and predictable transaction fees.5 +- **Massive Throughput:** By breaking the sequential bottleneck, Blocksense's throughput can scale horizontally with the addition of more CPU cores to validator nodes. This allows the network to achieve extremely high transactions per second (TPS), capable of supporting enterprise-grade applications.[^5] +- **Low Latency & Near-Instant Finality:** Simple transactions involving only owned objects (e.g., transferring a token to a friend) do not require complex consensus. They can be validated and finalized almost instantly, providing a user experience comparable to Web2 applications.[^6] +- **Reduced Network Congestion:** Because independent transactions don't have to wait for each other, the network is far more resilient to congestion, leading to more stable and predictable transaction fees.[^5] ### **For Developers:** -- **Fine-Grained State Management:** The object model gives developers precise control over their application's state. You can design complex systems as compositions of independent objects, which is often a more intuitive and secure way to model digital assets.2 +- **Fine-Grained State Management:** The object model gives developers precise control over their application's state. You can design complex systems as compositions of independent objects, which is often a more intuitive and secure way to model digital assets.[^2] - **Performance by Design:** The model encourages developers to think about state contention. By architecting applications to minimize the use of shared objects, you can directly build more scalable and performant dApps. For example, a game might represent each player's inventory as an owned object and only use a shared object for a global leaderboard, ensuring that most in-game actions can be processed in parallel. -- **Enhanced Security:** The Move language, combined with the object model, provides strong ownership and access control guarantees at the language level, preventing entire classes of common smart contract vulnerabilities like reentrancy attacks.4 +- **Enhanced Security:** The Move language, combined with the object model, provides strong ownership and access control guarantees at the language level, preventing entire classes of common smart contract vulnerabilities like reentrancy attacks.[^4] By embracing the object-centric paradigm, Blocksense provides a foundation for a new generation of decentralized applications that are not constrained by the performance limitations of the past. -#### **Works cited** - -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf -2. Building on Sui Blockchain | Here's What You Need to Know, accessed July 31, 2025, [https://blockchain.oodles.io/blog/sui-blockchain/](https://blockchain.oodles.io/blog/sui-blockchain/) -3. Object Model \- Sui Documentation, accessed July 31, 2025, [https://docs.sui.io/concepts/object-model](https://docs.sui.io/concepts/object-model) -4. SUI Deep Dive: Understanding Its Object-Centric Design and ..., accessed July 31, 2025, [https://medium.com/@lucasfada93/sui-deep-dive-understanding-its-object-centric-design-and-parallel-processing-49cb6beda183](https://medium.com/@lucasfada93/sui-deep-dive-understanding-its-object-centric-design-and-parallel-processing-49cb6beda183) -5. All About Parallelization \- The Sui Blog, accessed July 31, 2025, [https://blog.sui.io/parallelization-explained/](https://blog.sui.io/parallelization-explained/) -6. What is Sui Network? (SUI) How it works, who created it and how it is used | Kraken, accessed July 31, 2025, [https://www.kraken.com/learn/what-is-sui-network-sui](https://www.kraken.com/learn/what-is-sui-network-sui) -7. Sui Blockchain: A Deep Dive \- Stakin, accessed July 31, 2025, [https://stakin.com/blog/sui-blockchain-a-deep-dive](https://stakin.com/blog/sui-blockchain-a-deep-dive) -8. SUI, Aptos, and Vara: A Parallelization Comparison | by Vara Network \- Medium, accessed July 31, 2025, [https://medium.com/@VaraNetwork/sui-aptos-and-vara-a-parallelisation-comparison-b36f9ef84e46](https://medium.com/@VaraNetwork/sui-aptos-and-vara-a-parallelisation-comparison-b36f9ef84e46) -9. What Is the Sui Network and How Does It Work? | Omar Faruk777 on ..., accessed July 31, 2025, [https://www.binance.com/en/square/post/21140617778929](https://www.binance.com/en/square/post/21140617778929) -10. A deep dive into Sui's unique architecture, key features, and advantages over traditional blockchains \- CoinTranscend, accessed July 31, 2025, [https://www.cointranscend.com/a-deep-dive-into-suis-unique-architecture-key-features-and-advantages-over-traditional-blockchains/](https://www.cointranscend.com/a-deep-dive-into-suis-unique-architecture-key-features-and-advantages-over-traditional-blockchains/) -11. The SUI Network Explained | Mudrex Learn, accessed July 31, 2025, [https://mudrex.com/learn/the-sui-network-explained/](https://mudrex.com/learn/the-sui-network-explained/) +## **Works Cited** + +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles + +[^2]: [Building on Sui Blockchain](https://blockchain.oodles.io/blog/sui-blockchain/) - Here's What You Need to Know, accessed July 31, 2025 + +[^3]: [Object Model](https://docs.sui.io/concepts/object-model) - Sui Documentation, accessed July 31, 2025 + +[^4]: [SUI Deep Dive: Understanding Its Object-Centric Design and Parallel Processing](https://medium.com/@lucasfada93/sui-deep-dive-understanding-its-object-centric-design-and-parallel-processing-49cb6beda183) - Medium, accessed July 31, 2025 + +[^5]: [All About Parallelization](https://blog.sui.io/parallelization-explained/) - The Sui Blog, accessed July 31, 2025 + +[^6]: [What is Sui Network? (SUI)](https://www.kraken.com/learn/what-is-sui-network-sui) - How it works, who created it and how it is used | Kraken, accessed July 31, 2025 + +[^7]: [Sui Blockchain: A Deep Dive](https://stakin.com/blog/sui-blockchain-a-deep-dive) - Stakin, accessed July 31, 2025 + +[^8]: [SUI, Aptos, and Vara: A Parallelization Comparison](https://medium.com/@VaraNetwork/sui-aptos-and-vara-a-parallelisation-comparison-b36f9ef84e46) | by Vara Network - Medium, accessed July 31, 2025 + +[^9]: [What Is the Sui Network and How Does It Work?](https://www.binance.com/en/square/post/21140617778929) | Omar Faruk777 on Binance, accessed July 31, 2025 + +[^10]: [A deep dive into Sui's unique architecture, key features, and advantages over traditional blockchains](https://www.cointranscend.com/a-deep-dive-into-suis-unique-architecture-key-features-and-advantages-over-traditional-blockchains/) - CoinTranscend, accessed July 31, 2025 + +[^11]: [The SUI Network Explained](https://mudrex.com/learn/the-sui-network-explained/) | Mudrex Learn, accessed July 31, 2025 diff --git a/spec/content/core/state-model/object-ownership-apis.md b/spec/content/core/state-model/object-ownership-apis.md index b8ce6253ea..b24dffef5d 100644 --- a/spec/content/core/state-model/object-ownership-apis.md +++ b/spec/content/core/state-model/object-ownership-apis.md @@ -6,19 +6,19 @@ A solid understanding of the object model is recommended before using these APIs ## **Defining an Object** -In Blocksense Noir, an object is a struct that has the key ability. The first field of the struct must be id: UID, which serves as the object's globally unique identifier on the network. 1 - -Rust +In Blocksense Noir, an object is a struct that has the key ability. The first field of the struct must be `id: UID`, which serves as the object's globally unique identifier on the network. +```rust // Example of a simple object definition struct MyObject { -id: UID, -value: u64, + id: UID, + value: u64, } +``` ## **Core Object Functions** -These functions are available within the blocksense::object module and are used for creating and managing the state of objects. +These functions are available within the `blocksense::object` module and are used for creating and managing the state of objects. ### **object::new** @@ -26,9 +26,9 @@ Creates a new, mutable object owned by a specific address. **Signature:** -Rust - -fn new\(owner: Address) \-\> T +```rust +fn new(owner: Address) -> T +``` **Description:** @@ -36,13 +36,13 @@ This function is called within a constructor or another function to instantiate **Example:** -Rust - +```rust // Creates a new MyObject owned by the transaction sender -let new_object \= MyObject { -id: object::new(context.sender()), -value: 100, +let new_object = MyObject { + id: object::new(context.sender()), + value: 100, }; +``` ### **object::share** @@ -50,9 +50,9 @@ Transitions an object from an owned state to a shared state, making it accessibl **Signature:** -Rust - -fn share\(object: T) +```rust +fn share(object: T) +``` **Description:** @@ -60,11 +60,11 @@ A shared object does not have a single owner and can be read or modified by anyo **Example:** -Rust - +```rust // Takes an owned object and makes it shared -let my_owned_object \= MyObject {... }; +let my_owned_object = MyObject { ... }; object::share(my_owned_object); +``` ### **object::freeze** @@ -72,25 +72,25 @@ Makes an object immutable, preventing any future modifications to its state. **Signature:** -Rust - -fn freeze\(object: T) +```rust +fn freeze(object: T) +``` **Description:** -A frozen object is guaranteed to be read-only for the rest of its existence. This is useful for publishing data that should never change, such as program code modules or on-chain certificates. This action is **irreversible**. 2 +A frozen object is guaranteed to be read-only for the rest of its existence. This is useful for publishing data that should never change, such as program code modules or on-chain certificates. This action is **irreversible**. **Example:** -Rust - +```rust // Takes an object and makes it immutable -let my_object \= MyObject {... }; +let my_object = MyObject { ... }; object::freeze(my_object); +``` ## **Transferring Objects** -These functions are available within the blocksense::transfer module and are used to change the ownership of objects. +These functions are available within the `blocksense::transfer` module and are used to change the ownership of objects. ### **transfer::public_transfer** @@ -98,30 +98,31 @@ Transfers an owned object from its current owner to a new recipient address. **Signature:** -Rust - -fn public_transfer\(object: T, recipient: Address) +```rust +fn public_transfer(object: T, recipient: Address) +``` **Description:** -This is the standard function for transferring ownership of an object. For an object to be transferable using this function, its defining struct must have both the key and store abilities. 1 This ensures that only objects explicitly marked as transferable can have their ownership changed. +This is the standard function for transferring ownership of an object. For an object to be transferable using this function, its defining struct must have both the `key` and `store` abilities.[^1] This ensures that only objects explicitly marked as transferable can have their ownership changed. **Example:** -Rust - +```rust // Define a transferable object struct TransferableNFT { -id: UID, -metadata_url: String, + id: UID, + metadata_url: String, } has key, store // In a function, transfer the NFT to a new owner public fn transfer_nft(nft: TransferableNFT, new_owner: Address) { -transfer::public_transfer(nft, new_owner); + transfer::public_transfer(nft, new_owner); } +``` + +## **Works Cited** -#### **Works cited** +[^1]: [Sui Object Reference](https://move-book.com/reference/abilities/object/) - The Move Book, accessed July 31, 2025 -1. Sui Object | Reference \- The Move Book, accessed July 31, 2025, [https://move-book.com/reference/abilities/object/](https://move-book.com/reference/abilities/object/) -2. sui-foundation/sui-object-model-workshop \- GitHub, accessed July 31, 2025, [https://github.com/sui-foundation/sui-object-model-workshop](https://github.com/sui-foundation/sui-object-model-workshop) +[^2]: [sui-foundation/sui-object-model-workshop](https://github.com/sui-foundation/sui-object-model-workshop) - GitHub, accessed July 31, 2025 diff --git a/spec/content/core/state-model/predictable-address-allocation.md b/spec/content/core/state-model/predictable-address-allocation.md index 2a81b36d4d..01caf51a08 100644 --- a/spec/content/core/state-model/predictable-address-allocation.md +++ b/spec/content/core/state-model/predictable-address-allocation.md @@ -10,27 +10,29 @@ In Blocksense, a user's account is a programmable user object. The address of th ### **1.1. The create_user Operation** -The fundamental operation for creating a new account is create_user. Its signature is: +The fundamental operation for creating a new account is `create_user`. Its signature is: +```rust create_user(validity_window, identity_service, public_bytes, authorization_data, salt) +``` The public address of the resulting user object is a cryptographic hash derived from a combination of these inputs: -- identity_service: The address of the initial Identity Service that will manage the account. -- public_bytes: The public data (e.g., a public key) associated with the user for this initial service. -- authorization_data: The proof that the user has authorized this creation via the identity_service. -- salt: A user-provided nonce to ensure uniqueness. +- `identity_service`: The address of the initial Identity Service that will manage the account. +- `public_bytes`: The public data (e.g., a public key) associated with the user for this initial service. +- `authorization_data`: The proof that the user has authorized this creation via the `identity_service`. +- `salt`: A user-provided nonce to ensure uniqueness. -Because the output address is a deterministic function of these inputs, anyone can pre-calculate a user's address before the create_user transaction is ever submitted to the network. +Because the output address is a deterministic function of these inputs, anyone can pre-calculate a user's address before the `create_user` transaction is ever submitted to the network. ### **1.2. The Bootstrapping Pattern for User-Friendly Onboarding** -While the create_user operation is deterministic, a user's ultimate IdentityService might be complex or based on personal credentials (like a Passkey) that are not known in advance. To solve this, Blocksense enables a powerful **bootstrapping pattern** that combines predictability with flexibility. +While the `create_user` operation is deterministic, a user's ultimate `IdentityService` might be complex or based on personal credentials (like a Passkey) that are not known in advance. To solve this, Blocksense enables a powerful **bootstrapping pattern** that combines predictability with flexibility. This is a two-step process: -1. **Initial Creation with a Bootstrapper:** A dApp or user initiates the process by calling create_user with a well-known, public **bootstrapping IdentityService**. This is a simple, often permissionless, service whose address is constant. By using this known service and a predictable salt (e.g., derived from the user's email or social handle), the dApp can generate a predictable address for the new user. This create_user transaction can be sponsored by the dApp, providing a completely frictionless onboarding experience where the user is not required to hold any tokens. -2. **Immediate Security Upgrade:** The newly created user object is now live on the network at its predictable address. In the very next step, the user calls change_identity_service. This operation allows them to switch control of their account from the generic bootstrapping service to their own desired IdentityService (e.g., one that is controlled by their device's Passkey). +1. **Initial Creation with a Bootstrapper:** A dApp or user initiates the process by calling `create_user` with a well-known, public **bootstrapping IdentityService**. This is a simple, often permissionless, service whose address is constant. By using this known service and a predictable salt (e.g., derived from the user's email or social handle), the dApp can generate a predictable address for the new user. This `create_user` transaction can be sponsored by the dApp, providing a completely frictionless onboarding experience where the user is not required to hold any tokens. +2. **Immediate Security Upgrade:** The newly created user object is now live on the network at its predictable address. In the very next step, the user calls `change_identity_service`. This operation allows them to switch control of their account from the generic bootstrapping service to their own desired `IdentityService` (e.g., one that is controlled by their device's Passkey). This pattern provides the best of both worlds: the user gets a predictable, human-friendly address that can be shared easily, while immediately upgrading to a high-security, personalized account manager without ever being locked into the initial bootstrapping service. @@ -40,22 +42,26 @@ A similar deterministic approach applies to deploying Objective Programs (ZK cir ### **2.1. Deploying a Module** -First, the immutable program logic is deployed to the network using the deploy_module operation: +First, the immutable program logic is deployed to the network using the `deploy_module` operation: +```rust deploy_module(program_bytes) +``` -This operation creates a frozen, system-owned object containing the compiled program bytecode. The address of this module is simply the cryptographic hash of the program_bytes. This ensures that identical code always results in the same on-chain module address, making program logic verifiable and content-addressable. +This operation creates a frozen, system-owned object containing the compiled program bytecode. The address of this module is simply the cryptographic hash of the `program_bytes`. This ensures that identical code always results in the same on-chain module address, making program logic verifiable and content-addressable. ### **2.2. Creating a Program Instance** -Once a module is deployed, developers can create stateful, mutable instances of it using the create_instance operation: +Once a module is deployed, developers can create stateful, mutable instances of it using the `create_instance` operation: +```rust create_instance(module_address, salt) +``` The address of the new program instance is deterministically derived from a combination of three inputs: -1. The address of the **caller** of the create_instance function. -2. The module_address of the program code being instantiated. -3. A developer-provided salt for uniqueness. +1. The address of the **caller** of the `create_instance` function. +2. The `module_address` of the program code being instantiated. +3. A developer-provided `salt` for uniqueness. This mechanism allows developers to predictably calculate the addresses of smart contracts before they are deployed. This is crucial for building complex, multi-contract systems where contracts need to know each other's addresses at the time of deployment to function correctly. For example, a token contract can be deployed with the pre-calculated address of its corresponding liquidity pool, ensuring they are correctly linked from genesis. diff --git a/spec/content/core/user-experience/passkey-wallet-discovery.md b/spec/content/core/user-experience/passkey-wallet-discovery.md index 422fb22527..59fb970aed 100644 --- a/spec/content/core/user-experience/passkey-wallet-discovery.md +++ b/spec/content/core/user-experience/passkey-wallet-discovery.md @@ -4,7 +4,7 @@ ### **1.1. Problem Statement** -The adoption of decentralized applications (DApps) has been persistently hindered by the reliance on browser extensions for wallet interactions. This traditional model, while foundational, introduces significant friction and security concerns that are misaligned with the vision of a seamless, user-centric Web3.1 Key challenges include: +The adoption of decentralized applications (DApps) has been persistently hindered by the reliance on browser extensions for wallet interactions. This traditional model, while foundational, introduces significant friction and security concerns that are misaligned with the vision of a seamless, user-centric Web3.[^1] Key challenges include: - **Onboarding Friction:** The mandatory installation of browser-specific extensions creates a multi-step barrier to entry for new users, leading to high drop-off rates. - **Security Vulnerabilities:** Browser extensions represent a significant attack surface, susceptible to phishing, supply-chain attacks, and permission overreach. @@ -12,16 +12,16 @@ The adoption of decentralized applications (DApps) has been persistently hindere ### **1.2. Proposed Solution** -This document specifies a technical standard for the discovery and integration of passkey-based wallets that operates entirely within the browser, eliminating the need for extensions. By leveraging a combination of W3C standardsβ€”namely the **Payment Handler API** for discovery and **iframes** for secure interactionβ€”this standard enables a secure, native, and frictionless wallet experience. +This document specifies a technical standard for the discovery and integration of passkey-based wallets that operates entirely within the browser, eliminating the need for extensions. By leveraging a combination of W3C standardsβ€”namely the **Payment Handler API** for discovery and **iframes** for secure interactionβ€”this standard enables a secure, native, and frictionless wallet experience.[^2] Wallet providers register themselves as payment handlers, creating a persistent but lightweight artifact in the browser. DApps can then use the standard Payment Request API to discover available wallets and initiate a secure signing process within a sandboxed iframe. **Key Benefits:** -- **Truly Web-Native:** The entire workflow relies on established W3C standards, including the Payment Handler API, iframes, postMessage, and WebAuthn.2 +- **Truly Web-Native:** The entire workflow relies on established W3C standards, including the Payment Handler API, iframes, postMessage, and WebAuthn. - **Frictionless Discovery:** DApps can perform silent, background checks for available wallets. If multiple wallets are registered, the browser presents a native, trusted UI for user selection. - **Decentralized and Equitable:** The standard is open. Any wallet provider can register itself, and DApps can discover them dynamically without maintaining hardcoded lists or proprietary integrations. -- **Blocksense Compatibility:** The standard explicitly defines signature types that are verifiably compatible with the Blocksense protocol's ZK-native architecture, ensuring that passkey-generated signatures can be efficiently and objectively verified on-chain within Noir-based ZK circuits.1 +- **Blocksense Compatibility:** The standard explicitly defines signature types that are verifiably compatible with the Blocksense protocol's ZK-native architecture, ensuring that passkey-generated signatures can be efficiently and objectively verified on-chain within Noir-based ZK circuits.[^1] --- @@ -32,7 +32,7 @@ Wallet providers register themselves as payment handlers, creating a persistent - **Wallet Provider:** A web application (e.g., my-wallet.com) where a user creates and manages their passkey-based wallet. This site is responsible for registering itself as a payment handler. - **Relying Party (DApp):** A decentralized application (e.g., dapp.com) that needs to interact with a user's wallet to request signatures for transactions. - **User Agent (Browser):** The browser acts as the trusted intermediary, managing payment handler registrations, facilitating discovery, and brokering secure access to WebAuthn credentials. -- **Blocksense Protocol:** The target blockchain that verifies the cryptographic proof (signature) generated by the wallet. Its ZK-native design allows for the efficient on-chain verification of supported signature schemes.1 +- **Blocksense Protocol:** The target blockchain that verifies the cryptographic proof (signature) generated by the wallet. Its ZK-native design allows for the efficient on-chain verification of supported signature schemes.[^1] ### **2.2. High-Level Workflow** @@ -53,123 +53,131 @@ A Wallet Provider **MUST** be a Progressive Web App (PWA) with a service worker. The registration is performed via navigator.paymentManager.instruments.set(). -JavaScript - +```javascript // In the Wallet Provider's service worker (sw.js) // A unique identifier for this standard -const METHOD_IDENTIFIER \= 'https://passkey-wallet-standard.org/v1'; +const METHOD_IDENTIFIER = 'https://passkey-wallet-standard.org/v1'; // After successful passkey creation and service worker registration async function registerWalletInstrument(walletId) { -if (\!('paymentManager' in self.registration)) { -return; -} - -const instrument \= { -name: 'My Passkey Wallet', // User-visible wallet name -icons: \[{ -src: '/icons/wallet-icon-192.png', -sizes: '192x192', -type: 'image/png', -}\], -method: METHOD_IDENTIFIER, -capabilities: { -supportedSignatures: \['ecdsa-secp256r1', 'ecdsa-secp256k1'\], -supportedChains: \['blocksense', 'ethereum'\] -} -}; - -await self.registration.paymentManager.instruments.set( -\`passkey-wallet-${walletId}\`, // A unique key for the instrument -instrument -); + if (!('paymentManager' in self.registration)) { + return; + } + + const instrument = { + name: 'My Passkey Wallet', // User-visible wallet name + icons: [ + { + src: '/icons/wallet-icon-192.png', + sizes: '192x192', + type: 'image/png', + }, + ], + method: METHOD_IDENTIFIER, + capabilities: { + supportedSignatures: ['ecdsa-secp256r1', 'ecdsa-secp256k1'], + supportedChains: ['blocksense', 'ethereum'], + }, + }; + + await self.registration.paymentManager.instruments.set( + `passkey-wallet-${walletId}`, // A unique key for the instrument + instrument, + ); } +``` **3.1.2. Service Worker Event Handling** The service worker must listen for and respond to two key events from the Payment Handler API. -JavaScript - +```javascript // In the Wallet Provider's service worker (sw.js) // Respond affirmatively to availability checks from DApps. -self.addEventListener('canmakepayment', (event) \=\> { -event.respondWith(true); +self.addEventListener('canmakepayment', event => { + event.respondWith(true); }); // Respond to a discovery request with the wallet's details. -self.addEventListener('paymentrequest', (event) \=\> { -event.respondWith(new Promise((resolve) \=\> { -resolve({ -methodName: METHOD_IDENTIFIER, -details: { -walletOrigin: new URL(self.registration.scope).origin, -// Re-state capabilities for the DApp -supportedSignatures: \['ecdsa-secp256r1', 'ecdsa-secp256k1'\] -} -}); -})); +self.addEventListener('paymentrequest', event => { + event.respondWith( + new Promise(resolve => { + resolve({ + methodName: METHOD_IDENTIFIER, + details: { + walletOrigin: new URL(self.registration.scope).origin, + // Re-state capabilities for the DApp + supportedSignatures: ['ecdsa-secp256r1', 'ecdsa-secp256k1'], + }, + }); + }), + ); }); +``` ### **3.2. Relying Party (DApp): Discovery and Connection** When the user initiates a wallet connection, the DApp uses the PaymentRequest API to discover and connect to a compliant wallet. -JavaScript - +```javascript // In the DApp's frontend script -const METHOD_IDENTIFIER \= 'https://passkey-wallet-standard.org/v1'; +const METHOD_IDENTIFIER = 'https://passkey-wallet-standard.org/v1'; async function connectWallet() { -if (\!window.PaymentRequest) { -// Fallback for unsupported browsers -alert("This browser doesn't support extension-less wallets."); -return; -} - -const request \= new PaymentRequest( -, -// A dummy total is required by the API -{ total: { label: 'Wallet Authentication', amount: { currency: 'USD', value: '0.00' } } } -); - -const canConnect \= await request.canMakePayment(); -if (\!canConnect) { -// Fallback if no compliant wallet is registered -alert("No passkey wallet found. Please set one up first."); -return; -} - -try { -const response \= await request.show(); -const { walletOrigin } \= response.details; + if (!window.PaymentRequest) { + // Fallback for unsupported browsers + alert("This browser doesn't support extension-less wallets."); + return; + } + + const request = new PaymentRequest( + [{ supportedMethods: METHOD_IDENTIFIER }], + // A dummy total is required by the API + { + total: { + label: 'Wallet Authentication', + amount: { currency: 'USD', value: '0.00' }, + }, + }, + ); + + const canConnect = await request.canMakePayment(); + if (!canConnect) { + // Fallback if no compliant wallet is registered + alert('No passkey wallet found. Please set one up first.'); + return; + } + + try { + const response = await request.show(); + const { walletOrigin } = response.details; // The transaction is "successful" from the API's perspective await response.complete('success'); // Now, load the wallet's iframe to proceed with signing loadWalletIframe(walletOrigin); - -} catch (error) { -console.error("Wallet connection failed:", error); -} + } catch (error) { + console.error('Wallet connection failed:', error); + } } function loadWalletIframe(walletOrigin) { -const iframe \= document.createElement('iframe'); -iframe.src \= \`${walletOrigin}/wallet-interface.html\`; // Standardized path + const iframe = document.createElement('iframe'); + iframe.src = `${walletOrigin}/wallet-interface.html`; // Standardized path -// Crucially, grant the iframe permission to use the WebAuthn API -iframe.allow \= 'publickey-credentials-get'; + // Crucially, grant the iframe permission to use the WebAuthn API + iframe.allow = 'publickey-credentials-get'; -document.body.appendChild(iframe); + document.body.appendChild(iframe); -// Setup postMessage communication channel -//... (see next section) + // Setup postMessage communication channel + //... (see next section) } +``` ### **3.3. Secure Communication and Signing** @@ -177,57 +185,64 @@ Communication between the DApp and the Wallet Provider's iframe **MUST** use pos **3.3.1. DApp to Iframe: Requesting a Signature** -JavaScript - +```javascript // In the DApp's frontend script -// Assuming \`iframe\` and \`walletOrigin\` are available from the previous step -iframe.addEventListener('load', () \=\> { -const transactionToSign \= { /\*... transaction data... \*/ }; -iframe.contentWindow.postMessage( -{ action: 'requestSignature', data: transactionToSign }, -walletOrigin -); +// Assuming `iframe` and `walletOrigin` are available from the previous step +iframe.addEventListener('load', () => { + const transactionToSign = { + /*... transaction data... */ + }; + iframe.contentWindow.postMessage( + { action: 'requestSignature', data: transactionToSign }, + walletOrigin, + ); }); +``` **3.3.2. Iframe to DApp: Returning the Signature** -The Wallet Provider's iframe page must be served with a Permissions-Policy HTTP header to enable WebAuthn.5 +The Wallet Provider's iframe page must be served with a Permissions-Policy HTTP header to enable WebAuthn. -Example HTTP Header: -Permissions-Policy: publickey-credentials-get=\* +**Example HTTP Header:** -JavaScript +``` +Permissions-Policy: publickey-credentials-get=* +``` +```javascript // In the Wallet Provider's iframe script -window.addEventListener('message', async (event) \=\> { -// IMPORTANT: Verify the message is from the expected DApp origin -if (event.origin\!== 'https://dapp.com') { -return; -} - -if (event.data.action \=== 'requestSignature') { -try { -const credential \= await navigator.credentials.get({ -publicKey: { -challenge: new Uint8Array(event.data.data.challenge), -//... other WebAuthn options -} -}); +window.addEventListener('message', async event => { + // IMPORTANT: Verify the message is from the expected DApp origin + if (event.origin !== 'https://dapp.com') { + return; + } + + if (event.data.action === 'requestSignature') { + try { + const credential = await navigator.credentials.get({ + publicKey: { + challenge: new Uint8Array(event.data.data.challenge), + //... other WebAuthn options + }, + }); // Send the signature back to the DApp window.parent.postMessage( { action: 'signatureResponse', signature: credential.response }, - 'https://dapp.com' // Target the DApp's origin + 'https://dapp.com', // Target the DApp's origin ); } catch (error) { // Handle errors (e.g., user cancellation) - window.parent.postMessage({ action: 'signatureError', error: error.message }, '\*'); + window.parent.postMessage( + { action: 'signatureError', error: error.message }, + '*', + ); } - -} + } }); +``` --- @@ -235,13 +250,13 @@ challenge: new Uint8Array(event.data.data.challenge), A key requirement of this standard is ensuring that signatures generated via WebAuthn can be verified by Blocksense's ZK-native protocol. Wallet providers **MUST** declare the signature algorithms they support in their registration capabilities. The following table outlines the recommended signature types based on their WebAuthn compatibility and verifiability within Noir ZK circuits. -| Signature Type | Algorithm Details | Noir Support Status | WebAuthn Compatibility | Blocksense Use Case | -| :------------------ | :------------------------------------------------- | :---------------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | -| **ECDSA secp256r1** | ECDSA over NIST P-256 curve (ES256). | **Native** 4 | **Yes (Default)** | Primary algorithm for passkey-based transaction signing due to its robust security and native support. | -| **ECDSA secp256k1** | ECDSA over the secp256k1 curve. | **Native** 4 | Partial (via extensions) | Essential for cross-chain compatibility, especially for interacting with Ethereum-based assets via the Blocksense bridge. | -| **RSA-PKCS1-v1_5** | RSA with PKCS\#1 v1.5 padding and SHA-256. | **Community Library** 6 | Yes (legacy support) | Enables verification of signatures from older hardware tokens or systems, such as DKIM email verification for Web2 interoperability. | -| **Schnorr** | Schnorr signatures over secp256k1 or other curves. | **Community Library** 7 | No (not standard) | Useful for advanced cryptographic schemes like efficient multi-signatures within autonomous agents. | -| **EdDSA** | Edwards-curve DSA over Ed25519. | **Community Library** 8 | No (not standard) | Ideal for privacy-preserving applications and ZK proof aggregation within the ADFS. | +| Signature Type | Algorithm Details | Noir Support Status | WebAuthn Compatibility | Blocksense Use Case | +| :------------------ | :------------------------------------------------- | :-------------------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| **ECDSA secp256r1** | ECDSA over NIST P-256 curve (ES256). | **Native** | **Yes (Default)** | Primary algorithm for passkey-based transaction signing due to its robust security and native support. | +| **ECDSA secp256k1** | ECDSA over the secp256k1 curve. | **Native** | Partial (via extensions) | Essential for cross-chain compatibility, especially for interacting with Ethereum-based assets via the Blocksense bridge. | +| **RSA-PKCS1-v1_5** | RSA with PKCS#1 v1.5 padding and SHA-256. | **Community Library** | Yes (legacy support) | Enables verification of signatures from older hardware tokens or systems, such as DKIM email verification for Web2 interoperability. | +| **Schnorr** | Schnorr signatures over secp256k1 or other curves. | **Community Library** | No (not standard) | Useful for advanced cryptographic schemes like efficient multi-signatures within autonomous agents. | +| **EdDSA** | Edwards-curve DSA over Ed25519. | **Community Library** | No (not standard) | Ideal for privacy-preserving applications and ZK proof aggregation within the ADFS. | --- @@ -249,7 +264,7 @@ A key requirement of this standard is ensuring that signatures generated via Web - **Iframe Sandboxing:** The use of iframes naturally sandboxes the Wallet Provider's code from the DApp, preventing direct access to the DOM or JavaScript environment and mitigating cross-site scripting (XSS) risks. - **Origin Verification:** Both the DApp and the Wallet Provider **MUST** perform strict origin checks on all messages received via postMessage to prevent malicious cross-window communication. -- **User Activation:** WebAuthn calls like navigator.credentials.get() require a transient user activation (e.g., a click) within the iframe, preventing drive-by signing attempts.5 +- **User Activation:** WebAuthn calls like `navigator.credentials.get()` require a transient user activation (e.g., a click) within the iframe, preventing drive-by signing attempts.[^5] - **Discovery Privacy:** The canMakePayment() check is designed to be privacy-preserving. It returns a simple boolean without revealing which specific wallets are installed until the user explicitly consents by interacting with the show() prompt. ## **6\. Future Extensions** @@ -257,13 +272,20 @@ A key requirement of this standard is ensuring that signatures generated via Web - **Hybrid Passkeys:** As browser support for synced passkeys (via iCloud, Google Password Manager, etc.) matures, this standard will seamlessly support them, enabling users to access their wallets across all their devices without manual export/import. - **Expanded Capabilities:** The capabilities object in the payment instrument registration can be extended to advertise support for other features, such as specific on-chain account abstraction modules or privacy-preserving protocols. -#### **Works cited** +## **Works Cited** + +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles + +[^2]: [Payment Handler API](https://www.w3.org/TR/payment-handler/) - W3C, accessed July 31, 2025 + +[^3]: [Web Authentication: An API for accessing Public Key Credentials - Level 2](https://www.w3.org/TR/webauthn-2/) - W3C, accessed July 31, 2025 + +[^4]: [ECDSA Signature Verification](https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/ecdsa_sig_verification) | Noir Documentation, accessed July 31, 2025 + +[^5]: [Passkeys & iframes: How to Create & Login with a Passkey?](https://www.corbado.com/blog/iframe-passkeys-webauthn) - Corbado, accessed July 31, 2025 + +[^6]: [richardliang/noir-rsa: Noir implementation of RSA-verify](https://github.com/richardliang/noir-rsa) - GitHub, accessed July 31, 2025 + +[^7]: [noir-lang/schnorr](https://github.com/noir-lang/schnorr) - GitHub, accessed July 31, 2025 -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf -2. Payment Handler API \- W3C, accessed July 31, 2025, [https://www.w3.org/TR/payment-handler/](https://www.w3.org/TR/payment-handler/) -3. Web Authentication: An API for accessing Public Key Credentials \- Level 2 \- W3C, accessed July 31, 2025, [https://www.w3.org/TR/webauthn-2/](https://www.w3.org/TR/webauthn-2/) -4. ECDSA Signature Verification | Noir Documentation, accessed July 31, 2025, [https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/ecdsa_sig_verification](https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives/ecdsa_sig_verification) -5. Passkeys & iframes: How to Create & Login with a Passkey? \- Corbado, accessed July 31, 2025, [https://www.corbado.com/blog/iframe-passkeys-webauthn](https://www.corbado.com/blog/iframe-passkeys-webauthn) -6. richardliang/noir-rsa: Noir implementation of RSA-verify \- GitHub, accessed July 31, 2025, [https://github.com/richardliang/noir-rsa](https://github.com/richardliang/noir-rsa) -7. noir-lang/schnorr \- GitHub, accessed July 31, 2025, [https://github.com/noir-lang/schnorr](https://github.com/noir-lang/schnorr) -8. noir-lang/eddsa \- GitHub, accessed July 31, 2025, [https://github.com/noir-lang/eddsa](https://github.com/noir-lang/eddsa) +[^8]: [noir-lang/eddsa](https://github.com/noir-lang/eddsa) - GitHub, accessed July 31, 2025 diff --git a/spec/content/oracle-system/consensus/intersubjective-consensus-integration.md b/spec/content/oracle-system/consensus/intersubjective-consensus-integration.md index 6cb981f714..a0769efdbd 100644 --- a/spec/content/oracle-system/consensus/intersubjective-consensus-integration.md +++ b/spec/content/oracle-system/consensus/intersubjective-consensus-integration.md @@ -2,9 +2,7 @@ ## **1\. Introduction: Bridging Two Worlds of Truth** -The Blocksense network is uniquely designed to process both objective truths (computations with deterministic outcomes) and intersubjective truths (consensus on external information).1 The power of the network lies not just in handling these two domains, but in seamlessly and verifiably integrating them. The results from the - -**Intersubjective Truth Machine**, powered by zkSchellingCoin, must be woven into the state of the **Boundless Throughput Engine** with the same mathematical certainty as any other state transition.1 +The Blocksense network is uniquely designed to process both objective truths (computations with deterministic outcomes) and intersubjective truths (consensus on external information).[^1] The power of the network lies not just in handling these two domains, but in seamlessly and verifiably integrating them. The results from the **Intersubjective Truth Machine**, powered by zkSchellingCoin, must be woven into the state of the **Boundless Throughput Engine** with the same mathematical certainty as any other state transition.[^1] This is achieved by ensuring that the final result of any zkSchellingCoin consensus is accompanied by a ZK proof that attests to the correct and impartial tallying of votes. This "consensus proof" is a first-class object that can be processed by the Execution Layer, creating a trustless bridge between the two layers. This integration happens through two primary mechanisms: regularly scheduled data feeds and on-demand requests from on-chain programs. @@ -14,10 +12,10 @@ Scheduled data feeds are the backbone of Blocksense's oracle services, providing ### **2.1. Vote Submission and Collection** -For any given data feed, a secret sub-committee of reporters is selected to vote on the outcome.1 +For any given data feed, a secret sub-committee of reporters is selected to vote on the outcome.[^1] 1. **Vote Casting:** Shortly before a scheduled publication time, each reporter in the committee submits their encrypted vote as a standard transaction. -2. **Censorship Resistance:** These vote transactions are processed by the Ordering Layer's parallel DAG mempool, which guarantees their inclusion and ordering in a censorship-resistant manner.1 +2. **Censorship Resistance:** These vote transactions are processed by the Ordering Layer's parallel DAG mempool, which guarantees their inclusion and ordering in a censorship-resistant manner.[^1] 3. **On-Chain Aggregation:** A simple, low-cost Objective Program, specific to the data feed, is executed. Its sole function is to receive the ordered votes and append them to a dedicated on-chain list, creating a public, immutable record of all submitted (but still encrypted) votes for that round. ### **2.2. The Coordinator's Role: Tallying and Proving** @@ -36,8 +34,8 @@ The final result is propagated through the system and delivered to external netw 1. **Publication to Routing Table:** The Coordinator submits a transaction containing the final result and the tallying proof. A core system contract on the Execution Layer verifies this proof. If valid, the result is written to a special, system-wide **Routing Table**. This table acts as a central, verifiable source of truth for all oracle data. 2. **Cross-Chain Aggregation:** A separate, permissionless relayer network monitors the Routing Table. When a new value is published, the relayer identifies which target networks (e.g., Ethereum, Solana) are subscribed to that data feed. -3. **ADFS Payload Generation:** The relayer bundles all pending updates for a specific target network into a single payload, formatting it according to the data structure required by that chain's **Aggregated Data Feed Store (ADFS)** contract.1 -4. **Final Proof for Target Chain:** The relayer generates a final ZK proof that attests to the correct bundling and formatting of this ADFS payload. This proof, along with the payload, is submitted to the target chain. The on-chain ADFS contract only needs to perform a single, inexpensive ZK proof verification to accept thousands of data updates simultaneously, providing unparalleled cost efficiency.1 +3. **ADFS Payload Generation:** The relayer bundles all pending updates for a specific target network into a single payload, formatting it according to the data structure required by that chain's **Aggregated Data Feed Store (ADFS)** contract.[^1] +4. **Final Proof for Target Chain:** The relayer generates a final ZK proof that attests to the correct bundling and formatting of this ADFS payload. This proof, along with the payload, is submitted to the target chain. The on-chain ADFS contract only needs to perform a single, inexpensive ZK proof verification to accept thousands of data updates simultaneously, providing unparalleled cost efficiency.[^1] ## **3\. Mechanism 2: On-Demand Requests and the Task Manifest Pattern** @@ -64,7 +62,7 @@ When an Objective Program needs to trigger a new verifiable computation, it does ## **4\. A General-Purpose Primitive for Verifiable Computation** -The on-demand request/response mechanism is a fundamental primitive of the Blocksense service-oriented architecture, extending far beyond simple data oracles.1 The "Task Manifest" pattern can be used to create on-chain markets for any kind of verifiable computation: +The on-demand request/response mechanism is a fundamental primitive of the Blocksense service-oriented architecture, extending far beyond simple data oracles.[^1] The "Task Manifest" pattern can be used to create on-chain markets for any kind of verifiable computation: - **zkSchellingCoin Consensus:** A dApp can request a one-time consensus on a complex event, like the outcome of a prediction market. - **ZK Proof Generation Market:** A dApp can create a Task Manifest with a request to generate a complex ZK proof for a large computation. The verifier program in the manifest would be the verifier circuit for the requested proof. @@ -72,6 +70,6 @@ The on-demand request/response mechanism is a fundamental primitive of the Block In every case, the Task Manifest Object acts as a trustless escrow and verifier, ensuring that payment is only released for correctly completed work, as validated by the appropriate proof. This makes the Blocksense network an extensible, universally verifiable platform for a new generation of decentralized services. -#### **Works cited** +## **Works Cited** -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles diff --git a/spec/content/oracle-system/sdk/oracle-service-costing.md b/spec/content/oracle-system/sdk/oracle-service-costing.md index 74f07d3cbd..7af4d0dcdf 100644 --- a/spec/content/oracle-system/sdk/oracle-service-costing.md +++ b/spec/content/oracle-system/sdk/oracle-service-costing.md @@ -1,6 +1,6 @@ # **Blocksense SDK: Oracle Service Costing, Concurrency, and Pricing Markets** -The Blocksense network is designed as a global, unified marketplace for verified computation.1 For this marketplace to function efficiently and fairly, the "cost" of any computation must be measured objectively and transparently. This principle is central to the design of Intersubjective Services (Oracle Services). +The Blocksense network is designed as a global, unified marketplace for verified computation.[^1] For this marketplace to function efficiently and fairly, the "cost" of any computation must be measured objectively and transparently. This principle is central to the design of Intersubjective Services (Oracle Services). This document details how the Blocksense runtime measures the cost of oracle execution, how developers can define custom cost metrics for complex tasks, and how these mechanisms create a competitive pricing market for oracle services. @@ -16,7 +16,7 @@ Every oracle service runs within a sandboxed WebAssembly (WASM) runtime on the B - **Memory Used:** The amount of memory consumed by the WebAssembly module during execution. - **Internet Bandwidth:** The volume of data transferred over the network (e.g., for API calls). -These intrinsic costs are measured automatically by the runtime for every execution. When a Blocksense node reports the result of an oracle query, it reports these measured costs alongside the result. The Schelling point consensus mechanism then applies to both the data result and the reported cost, incentivizing all nodes to report these objective measurements honestly.1 +These intrinsic costs are measured automatically by the runtime for every execution. When a Blocksense node reports the result of an oracle query, it reports these measured costs alongside the result. The Schelling point consensus mechanism then applies to both the data result and the reported cost, incentivizing all nodes to report these objective measurements honestly.[^1] ### **1.2. Extensible Cost: External Programs and Custom Units** @@ -25,14 +25,14 @@ Many advanced oracle services rely on external programs to perform specialized t The critical requirement is that this external program **must produce an objective, hardware-independent measure of its own "cost."** This is not a measure of time, but a deterministic unit relevant to the task. Examples include: - **Gas:** For a program that simulates an EVM transaction. -- **Input and Output Tokens:** For a service that queries a large language model.1 +- **Input and Output Tokens:** For a service that queries a large language model. - **Software Counters:** Any custom, deterministic counter defined by the program's logic. The Blocksense node executes this external program, collects the cost measurement it produces, and reports this value as part of the total cost for the oracle query. This allows the Blocksense economic model to transparently price and reward arbitrarily complex, specialized computations. ## **2\. The Pricing Market for Oracle Services** -The objective cost measurements form the basis of a competitive, market-driven ecosystem for providing oracle services.1 +The objective cost measurements form the basis of a competitive, market-driven ecosystem for providing oracle services.[^1] - **Service Bidding:** Node operators who wish to run oracle services participate in a bidding system. They bid on their willingness to provide computation at a certain price per cost unit (e.g., price per million retired instructions). - **Incentivizing Efficiency:** The protocol prioritizes tasks for operators who offer cheaper service. This creates a powerful economic incentive for operators to optimize their infrastructure and report costs honestly. An operator who can perform a computation more efficiently (i.e., for a lower cost) will receive more data reporting tasks and, consequently, more rewards. @@ -51,8 +51,10 @@ Within the setup() function, an oracle service can spawn multiple WebAssembly th For tasks that require continuous, long-running operationβ€”such as maintaining a live connection to a high-frequency data sourceβ€”the ideal pattern is to decouple the data ingestion from the on-demand query execution. -Motivating Example: Real-Time Price Feeds +**Motivating Example: Real-Time Price Feeds** + Consider an oracle service designed to provide the most up-to-the-second price for a volatile asset. This requires maintaining persistent WebSocket connections to multiple cryptocurrency exchanges, a task ill-suited for the synchronous, request-response model of the query function. + The Blocksense architecture solves this with a powerful pattern: 1. **Launch in setup():** In the setup() hook, the oracle service launches a long-running external process. This process is responsible for establishing and maintaining WebSocket connections to multiple exchanges. @@ -73,40 +75,38 @@ This forces the oracle to report these costs on every invocation, making them an An oracle service that uses an external process to track WebSocket data might define its return type as follows: -Rust - +```rust // In the oracle's metadata, a custom cost unit is declared: -// custom_costs \= \["websocket_bandwidth_bytes"\] +// custom_costs = ["websocket_bandwidth_bytes"] // The return struct for the query function. pub struct PriceFeedResult { -// The primary data result of the query. -pub price: u64, -pub timestamp: u64, + // The primary data result of the query. + pub price: u64, + pub timestamp: u64, // This field is annotated as a cost unit. The runtime will parse this // and include it in the final cost report for the query. - \#\[cost\_unit(name \= "websocket\_bandwidth\_bytes")\] - pub bandwidth\_used: u64, - + #[cost_unit(name = "websocket_bandwidth_bytes")] + pub bandwidth_used: u64, } // The implementation of the query function. -pub fn query(params: Vec\) \-\> PriceFeedResult { -// Read the latest price and the measured bandwidth cost -// from the shared memory table populated by the external process. -let (latest_price, bandwidth) \= read_from_shared_memory(); +pub fn query(params: Vec) -> PriceFeedResult { + // Read the latest price and the measured bandwidth cost + // from the shared memory table populated by the external process. + let (latest_price, bandwidth) = read_from_shared_memory(); PriceFeedResult { - price: latest\_price, - timestamp: get\_current\_time(), - bandwidth\_used: bandwidth, + price: latest_price, + timestamp: get_current_time(), + bandwidth_used: bandwidth, } - } +``` This annotation-based system provides a strongly-typed, explicit, and verifiable way for oracle services to report their extensible costs, ensuring the integrity of the network's pricing markets. -#### **Works cited** +## **Works Cited** -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles diff --git a/spec/content/oracle-system/sdk/oracle-service-lifecycle.md b/spec/content/oracle-system/sdk/oracle-service-lifecycle.md index 587bfed517..4147e200bd 100644 --- a/spec/content/oracle-system/sdk/oracle-service-lifecycle.md +++ b/spec/content/oracle-system/sdk/oracle-service-lifecycle.md @@ -6,17 +6,17 @@ Intersubjective Services (Oracle Services) on Blocksense are designed to be powe Many advanced oracle services require an expensive, one-time setup. For example, a parametric insurance oracle designed to automatically settle claims for cargo ships must first process vast amounts of geographical and historical weather data to build a baseline risk model. Performing this setup for every single query would be prohibitively slow and costly. -To solve this, Blocksense recognizes that zkSchellingCoin committee members (the nodes that run oracle services) are assigned their duties for prolonged periods, often several hours at a time.1 This stability makes it economically viable to perform an initial setup. The SDK exposes this capability through a simple three-stage lifecycle, allowing developers to amortize the cost of expensive initializations over thousands of subsequent queries. +To solve this, Blocksense recognizes that zkSchellingCoin committee members (the nodes that run oracle services) are assigned their duties for prolonged periods, often several hours at a time.[^1] This stability makes it economically viable to perform an initial setup. The SDK exposes this capability through a simple three-stage lifecycle, allowing developers to amortize the cost of expensive initializations over thousands of subsequent queries. ### **1.1. Lifecycle Hooks** An oracle service is structured around three core functions, or "hooks," that the developer implements. The oracle service runtime keeps the WebAssembly module instance alive between query calls, allowing state to be maintained in memory. -- setup(): This function is called **once** when a new instance of the oracle service is initialized on a node. It is the ideal place for performing one-time, expensive setup tasks, such as creating temporary files in the cache, or spawning long-running WebAssembly threads and external processes. +- **setup():** This function is called **once** when a new instance of the oracle service is initialized on a node. It is the ideal place for performing one-time, expensive setup tasks, such as creating temporary files in the cache, or spawning long-running WebAssembly threads and external processes. - **Use Case (Parametric Insurance Oracle):** The setup() function would download large datasets, such as global shipping lane maps (GIS data) and historical hurricane track data. It would then write this data to files in the local cache and load it into an efficient, queryable data structure in the WebAssembly module's memory. -- query(params: Vec\) \-\> Vec\: This is the primary function of the service and is invoked for **every individual data request**. It receives request-specific parameters from the objective layer (e.g., a specific policy ID to evaluate) and is responsible for executing the core logic and returning a result. +- **query(params: Vec) -> Vec:** This is the primary function of the service and is invoked for **every individual data request**. It receives request-specific parameters from the objective layer (e.g., a specific policy ID to evaluate) and is responsible for executing the core logic and returning a result. - **Use Case (Parametric Insurance Oracle):** The query() function would take a policy ID as input. It would then fetch real-time data for the associated vessel, such as its current GPS location. It would compare this live data against the in-memory risk models (loaded from the cache during setup) to determine if a trigger event has occurred and return the outcome. -- teardown(): This function is called **once** when a service instance is being shut down or decommissioned on a node. It allows for the graceful cleanup of any resources allocated in the setup() phase that are not managed automatically by the system. +- **teardown():** This function is called **once** when a service instance is being shut down or decommissioned on a node. It allows for the graceful cleanup of any resources allocated in the setup() phase that are not managed automatically by the system. ## **2\. The Multi-Tiered Storage Model** @@ -45,12 +45,14 @@ Because of this strict requirement, writing to Consensus Storage is recommended - A service that processes a sequence of events could store the ID of the last processed event to prevent duplicates. - An oracle monitoring a specific satellite feed could store the hash of the latest processed image tile to ensure no data is missed or re-processed. - **Conceptual API:** - Rust - // Writes a key-value pair to consensus storage. This action becomes part of the transaction result. - fn storage::write(key: Vec\, value: Vec\); - // Reads a value from the consensus state. - fn storage::read(key: Vec\) \-\> Option\\>; +```rust +// Writes a key-value pair to consensus storage. This action becomes part of the transaction result. +fn storage::write(key: Vec, value: Vec); + +// Reads a value from the consensus state. +fn storage::read(key: Vec) -> Option>; +``` ### **2.3. Tier 3: Persistent Storage via Self-Elected Capabilities** @@ -59,7 +61,7 @@ Some oracle services require access to large, persistent, and constantly evolvin This is best modeled as a **self-elected capability**. Instead of a generic storage API, this represents a specialized service that a node operator explicitly chooses to provide. - **Mechanism:** A node operator can elect to run and maintain the necessary infrastructure (e.g., a full Ethereum client). The oracle service can then declare a dependency on this capability in its metadata. -- **Custom Cost Model:** Services that rely on these capabilities define their own custom cost models. The cost is not based on standard WASM metering but on metrics relevant to the service (e.g., cost per database query, cost per block data read). This allows the Blocksense marketplace to accurately price these more complex and resource-intensive services.1 +- **Custom Cost Model:** Services that rely on these capabilities define their own custom cost models. The cost is not based on standard WASM metering but on metrics relevant to the service (e.g., cost per database query, cost per block data read). This allows the Blocksense marketplace to accurately price these more complex and resource-intensive services.[^1] ## **3\. A Note on Stateful Logic: The Correct Pattern** @@ -68,12 +70,12 @@ The strict "exact match" requirement for the on-chain Consensus Storage API mean The correct architectural pattern for managing such state involves a clear separation of concerns between the intersubjective and objective layers: 1. **Intersubjective Layer (Oracle Service):** The insurance oracle service determines if a specific policy should be paid out (e.g., it encountered a hurricane). It returns a structured result like {"policy_id": "XYZ", "payout_due": true}. The consensus method for this result could be a simple majority vote. -2. **Consensus:** The zkSchellingCoin mechanism establishes a final, agreed-upon result from the reports of all committee members.1 +2. **Consensus:** The zkSchellingCoin mechanism establishes a final, agreed-upon result from the reports of all committee members.[^1] 3. **Objective Layer (ZK Program):** The main insurance dApp contract receives this single, finalized result. It is this programβ€”not the oracle serviceβ€”that is responsible for managing the application's state. It can, for example, update a stateful object it owns that tracks the total number of claims paid out in a specific region. 4. **Data Flow:** If the oracle needed to know about past payouts to adjust its risk model, the Objective Program would pass that historical data _into_ the next query call as a parameter. This pattern correctly places the responsibility of state management on the deterministic Objective Layer, while using the Intersubjective Layer for its core purpose: establishing consensus on external, non-deterministic information. -#### **Works cited** +## **Works Cited** -1. Blocksense\_ A Litepaper for the Universal Verification Layer.pdf +[^1]: [[Blocksense Litepaper|blocksense-litepaper]] - Core protocol overview and design principles diff --git a/spec/content/tooling/cli.md b/spec/content/tooling/cli.md index ec58f16049..f0f285061c 100644 --- a/spec/content/tooling/cli.md +++ b/spec/content/tooling/cli.md @@ -17,8 +17,8 @@ The design of the blocksense CLI is guided by several core principles: These options can be used with any blocksense command. -- \--help, \-h: Displays help information for the specified command. -- \--version, \-V: Displays the current version of the blocksense CLI. +- `--help`, `-h`: Displays help information for the specified command. +- `--version`, `-V`: Displays the current version of the blocksense CLI. --- @@ -32,26 +32,26 @@ Initializes a new Blocksense project from a predefined or custom template. This **Usage:** -Bash - -blocksense init \ \ +```bash +blocksense init