logos-blockchain/lssa
1
0
Fork 0
mirror of https://github.com/logos-blockchain/lssa.git synced 2026-02-17 20:03:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

update README.md

Browse Source 
updated the introduction to include LEZ and LEE and rewrite some parts.
This commit is contained in:
Moudy 2026-02-04 13:32:40 +01:00 committed by GitHub
parent 9a7c851dcf
commit a08a7824c0
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 65 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
README.md
View File

@ -1,70 +1,75 @@
# Nescience
# Logos Execution Zone (LEZ)
Logos Execution Zone (LEZ) is a programmable blockchain that cleanly separates public and private state while keeping them fully interoperable. Developers can build apps that operate across transparent and privacy-preserving accounts without changing their logic. Privacy is enforced by the protocol itself through zero-knowledge proofs (ZKPs), so it is always available and automatic.
Nescience State Separation Architecture (NSSA) is a programmable blockchain system that introduces a clean separation between public and private states, while keeping them fully interoperable. It lets developers build apps that can operate across both transparent and privacy-preserving accounts. Privacy is handled automatically by the protocol through zero-knowledge proofs (ZKPs). The result is a programmable blockchain where privacy comes built-in.
## Background
Typically, public blockchains maintain a fully transparent state, where the mapping from account IDs to account values is entirely visible. In NSSA, we introduce a parallel *private state*, a new layer of accounts that coexists with the public one. The public and private states can be viewed as a partition of the account ID space: accounts with public IDs are openly visible, while private accounts are accessible only to holders of the corresponding viewing keys. Consistency across both states is enforced through zero-knowledge proofs (ZKPs).
These features are provided by the Logos Execution Environment (LEE). Traditional public blockchains expose a fully transparent state: the mapping from account IDs to account values is entirely visible. LEE introduces a parallel *private state* that coexists with the public one. Together, public and private accounts form a partition of the account ID space: public IDs are visible on-chain, while private accounts are accessible only to holders of the corresponding viewing keys. Consistency across both states is enforced by ZKPs.
Public accounts are stored on-chain as a visible map from IDs to account states, and their values are updated in place. Private accounts are never stored on-chain in raw form. Each update produces a new commitment that binds the current value while keeping it hidden. Previous commitments remain on-chain, but a nullifier set marks old versions as spent, ensuring that only the most recent private state can be used in execution.
Public accounts are represented on-chain as a visible map from IDs to account states and are modified in-place when their values change. Private accounts, by contrast, are never stored in raw form on-chain. Each update creates a new commitment, which cryptographically binds the current value of the account while preserving privacy. Commitments of previous valid versions remain on-chain, but a nullifier set is maintained to mark old versions as spent, ensuring that only the most up-to-date version of each private account can be used in any execution.
### Programmability and selective privacy
Our goal is to enable full programmability within this hybrid model, matching the flexibility and composability of public blockchains. Developers write and deploy programs in NSSA just as they would on any other blockchain. Privacy, along with the ability to execute programs involving any combination of public and private accounts, is handled entirely at the protocol level and available out of the box for all programs. From the program’s perspective, all accounts are indistinguishable. This abstraction allows developers to focus purely on business logic, while the system transparently enforces privacy and consistency guarantees.
LEZ aims to deliver full programmability in a hybrid public/private model, with the same flexibility and composability as public blockchains. Developers write and deploy programs in LEZ just as they would elsewhere. The protocol automatically supports executions that involve any combination of public and private accounts. From the program’s perspective, all accounts look the same, and privacy is enforced transparently. This lets developers focus on business logic while the system guarantees privacy and correctness.
To the best of our knowledge, this approach is unique to Nescience. Other programmable blockchains with a focus on privacy typically adopt a developer-driven model for private execution, meaning that dApp logic must explicitly handle private inputs correctly. In contrast, Nescience handles privacy at the protocol level, so developers do not need to modify their programs—private and public accounts are treated uniformly, and privacy-preserving execution is available out of the box.
To our knowledge, this design is unique to LEZ. Other privacy-focused programmable blockchains often require developers to explicitly handle private inputs inside their app logic. In LEZ, privacy is protocol-level: programs do not change, accounts are treated uniformly, and private execution works out of the box.
### Example: creating and transferring tokens across states
---
## Example: creating and transferring tokens across states
1. Token creation (public execution)
- Alice submits a transaction that executes the token program `New` function on-chain.
- A new public token definition account is created.
- The minted tokens are recorded on-chain in Alice’s public account.
1. Token creation (public execution):
- Alice submits a transaction to execute the token program `New` function on-chain.
- A new public token account is created, representing the token.
- The minted tokens are recorded on-chain and fully visible on Alice's public account.
2. Transfer from public to private (local / privacy-preserving execution)
- Alice executes the token program `Transfer` function locally, specifying a Bob’s private account as recipient.
- Alice runs the token program `Transfer` function locally, sending to Bob’s private account.
- A ZKP of correct execution is generated.
- The proof is submitted to the blockchain, and validator nodes verify it.
- Alice's public account balance is modified accordingly.
- Bob’s private account and balance remain hidden, while the transfer is provably valid.
- The proof is submitted to the blockchain and verified by validators.
- Alice’s public balance is updated on-chain.
- Bob’s private balance remains hidden, while the transfer is provably correct.
3. Transferring private to public (local / privacy-preserving execution)
- Bob executes the token program `Transfer` function locally, specifying a Charlie’s public account as recipient.
- Bob executes the token program `Transfer` function locally, sending to Charlie’s public account.
- A ZKP of correct execution is generated.
- Bob’s private account and balance still remain hidden.
- Charlie's public account is modified with the new tokens added.
4. Transferring public to public (public execution):
- Alice submits a transaction to execute the token program `Transfer` function on-chain, specifying Charlie's public account as recipient.
- The execution is handled on-chain without ZKPs involved.
- Alice's and Charlie's accounts are modified according to the transaction.
- Bob’s private balance stays hidden.
- Charlie’s public account is updated on-chain.
4. Transfer from public to public (public execution)
- Alice submits an on-chain transaction to run `Transfer`, sending to Charlie’s public account.
- Execution is handled fully on-chain without ZKPs.
- Alice’s and Charlie’s public balances are updated.
#### Key points:
- The same token program is used in all executions.
- The difference lies in execution mode: public executions update visible accounts on-chain, while private executions rely on ZKPs.
- Validators only need to verify proofs for privacy-preserving transactions, keeping processing efficient.
### Key points:
- The same token program is used in every execution.
- The only difference is execution mode: public execution updates visible state on-chain, while private execution relies on ZKPs.
- Validators verify proofs only for privacy-preserving transactions, keeping processing efficient.
### The account’s model
---
To achieve both state separation and full programmability, NSSA adopts a stateless program model. Programs do not hold internal state. Instead, all persistent data resides in accounts explicitly passed to the program during execution. This design enables fine-grained control over access and visibility while maintaining composability across public and private states.
## The account’s model
To achieve both state separation and full programmability, LEZ uses a stateless program model. Programs hold no internal state. All persistent data is stored in accounts passed explicitly into each execution. This enables precise access control and visibility while preserving composability across public and private states.
### Execution types
Execution is divided into two fundamentally distinct types based on how they are processed: public execution, which is executed transparently on-chain, and private execution, which occurs off-chain. For private execution, the blockchain relies on ZKPs to verify the correctness of execution and ensure that all system invariants are preserved.
LEZ supports two execution types:
- Public execution runs transparently on-chain.
- Private execution runs off-chain and is verified on-chain with ZKPs.
Both public and private executions of the same program are enforced to use the same Risc0 VM bytecode. For public transactions, programs are executed directly on-chain like any standard RISC-V VM execution, without generating or verifying proofs. For privacy-preserving transactions, users generate Risc0 ZKPs of correct execution, and validator nodes only verify these proofs rather than re-executing the program. This design ensures that from a validator’s perspective, public transactions are processed as quickly as any RISC-V–based VM, while verification of ZKPs keeps privacy-preserving transactions efficient as well. Additionally, the system naturally supports parallel execution similar to Solana, further increasing throughput. The main computational bottleneck for privacy-preserving transactions lies on the user side, in generating zk proofs.
Both public and private executions use the same Risc0 VM bytecode. Public transactions are executed directly on-chain like any standard RISC-V VM call, without proof generation. Private transactions are executed locally by users, who generate Risc0 proofs that validators verify instead of re-executing the program.
### Resources
- [IFT Research call](https://forum.vac.dev/t/ift-research-call-september-10th-2025-updates-on-the-development-of-nescience/566)
- [NSSA v0.2 specs](https://www.notion.so/NSSA-v0-2-specifications-2848f96fb65c800c9818e6f66d9be8f2)
- [Choice of VM/zkVM](https://www.notion.so/Conclusion-on-the-chosen-VM-and-zkVM-for-NSSA-2318f96fb65c806a810ed1300f56992d)
- [NSSA vs other privacy projects](https://www.notion.so/Privacy-projects-comparison-2688f96fb65c8096b694ecf7e4deca30)
- [NSSA state model](https://www.notion.so/Public-state-model-decision-2388f96fb65c80758b20c76de07b1fcc)
- [NSSA sequencer specs](https://www.notion.so/Sequencer-specs-2428f96fb65c802da2bfea7b0b214ecb)
- [NSSA sequencer code](https://www.notion.so/NSSA-sequencer-pseudocode-2508f96fb65c805e8859e047dffd6785)
- [NSSA Token program desing](https://www.notion.so/Token-program-design-2538f96fb65c80a1b4bdc4fd9dd162d7)
- [NSSA cross program calls](https://www.notion.so/NSSA-cross-program-calls-Tail-call-model-proposal-extended-version-2838f96fb65c8096b3a2d390444193b6)
This design keeps public transactions as fast as any RISC-V–based VM and makes private transactions efficient for validators. It also supports parallel execution similar to Solana, improving throughput. The main computational cost for privacy-preserving transactions is on the user side, where ZK proofs are generated.
---
---
# Install dependencies
Install build dependencies
### Install build dependencies
- On Linux
Ubuntu / Debian
@ -72,7 +77,7 @@ Ubuntu / Debian
apt install build-essential clang libclang-dev libssl-dev pkg-config
```
Fedora
- On Fedora
```sh
sudo dnf install clang clang-devel openssl-devel pkgconf
```
@ -83,25 +88,26 @@ xcode-select --install
brew install pkg-config openssl
```
Install Rust
### Install Rust
```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Install Risc0
### Install Risc0
```sh
curl -L https://risczero.com/install | bash
```
Then restart your shell and run
### Then restart your shell and run
```sh
rzup install
```
# Run tests
The NSSA repository includes both unit and integration test suites.
The LEZ repository includes both unit and integration test suites.
### Unit tests
@ -123,19 +129,19 @@ RUST_LOG=info RISC0_DEV_MODE=1 cargo run $(pwd)/configs/debug all
The sequencer and node can be run locally:
### 1. On one terminal go to the ⁨`logos-blockchain/logos-blockchain`⁩ repo and run a local logos blockchain node:
- ⁨`git checkout master; git pull`⁩
- ⁨`cargo clean`⁩
- ⁨`rm ~/.logos-blockchain-circuits`⁩
- ⁨`./scripts/setup-logos-blockchain-circuits.sh`⁩
- ⁨`cargo build --all-features`⁩
- ⁨`./target/debug/logos-blockchain-node nodes/node/config-one-node.yaml`⁩
1. On one terminal go to the ⁨`logos-blockchain/logos-blockchain`⁩ repo and run a local logos blockchain node:
- ⁨`git checkout master; git pull`⁩
- ⁨`cargo clean`⁩
- ⁨`rm ~/.logos-blockchain-circuits`⁩
- ⁨`./scripts/setup-logos-blockchain-circuits.sh`⁩
- ⁨`cargo build --all-features`⁩
- ⁨`./target/debug/logos-blockchain-node nodes/node/config-one-node.yaml`⁩
### 2. On another terminal go to the ⁨`logos-blockchain/lssa`⁩ repo and run indexer service:
- ⁨`git checkout schouhy/full-bedrock-integration`⁩
- ⁨`RUST_LOG=info cargo run --release -p indexer_service $(pwd)/integration_tests/configs/indexer/indexer_config.json`⁩
2. On another terminal go to the ⁨`logos-blockchain/lssa`⁩ repo and run indexer service:
- ⁨`git checkout schouhy/full-bedrock-integration`⁩
- ⁨`RUST_LOG=info cargo run --release -p indexer_service $(pwd)/integration_tests/configs/indexer/indexer_config.json`⁩
### 3. On another terminal go to the ⁨`logos-blockchain/lssa`⁩ repo and run the sequencer:
- ⁨`git checkout schouhy/full-bedrock-integration`⁩
- ⁨`RUST_LOG=info RISC0_DEV_MODE=1 cargo run --release -p sequencer_runner sequencer_runner/configs/debug`⁩
3. On another terminal go to the ⁨`logos-blockchain/lssa`⁩ repo and run the sequencer:
- ⁨`git checkout schouhy/full-bedrock-integration`⁩
- ⁨`RUST_LOG=info RISC0_DEV_MODE=1 cargo run --release -p sequencer_runner sequencer_runner/configs/debug`⁩