mirror of
https://github.com/logos-blockchain/logos-blockchain-circuits.git
synced 2026-06-10 18:49:25 +00:00
100 lines
3.1 KiB
Markdown
100 lines
3.1 KiB
Markdown
# Logos Blockchain Circuits — Rust
|
|
|
|
Rust bindings for the Logos Blockchain Circuits.
|
|
|
|
Each circuit has a `-sys` crate that wraps the underlying C FFI with a safe Rust API.
|
|
|
|
## Crates
|
|
|
|
| Crate | Description |
|
|
|---------------------|-------------------------------------------------|
|
|
| `lbc-poq-sys` | Witness generator for PoQ (Proof of Quota) |
|
|
| `lbc-pol-sys` | Witness generator for PoL (Proof of Leadership) |
|
|
| `lbc-poc-sys` | Witness generator for PoC (Proof of Claim) |
|
|
| `lbc-signature-sys` | Witness generator for Signature |
|
|
| `lbc-types` | Shared types |
|
|
| `lbc-build` | Build helper |
|
|
|
|
## Providing the circuit libraries
|
|
|
|
Each `-sys` crate needs the compiled circuit library directory for its circuit, containing `lib{circuit}.a` and `witness_generator.dat`.
|
|
There are two ways to provide it, detailed below.
|
|
|
|
### Option A — Prebuilt download
|
|
|
|
Enable the `prebuilt` Cargo feature.
|
|
|
|
The build script downloads the release bundle matching the crate version from GitHub Releases and caches it locally.
|
|
|
|
```toml
|
|
[dependencies]
|
|
lbc-poq-sys = { version = "0.5", features = ["prebuilt"] }
|
|
```
|
|
|
|
The cache location depends on the operating system:
|
|
|
|
- Linux: `~/.cache/logos/blockchain/`
|
|
- macOS: `~/Library/Caches/logos/blockchain/`
|
|
- Windows: `%LOCALAPPDATA%\logos\blockchain\`
|
|
|
|
The downloaded bundle version always matches `CARGO_PKG_VERSION`.
|
|
|
|
### Option B — Custom path
|
|
|
|
Point the build script at any directory containing the compiled circuit libraries:
|
|
|
|
```bash
|
|
LBC_POQ_LIB_DIR=/path/to/poq
|
|
LBC_POL_LIB_DIR=/path/to/pol
|
|
LBC_POC_LIB_DIR=/path/to/poc
|
|
LBC_SIGNATURE_LIB_DIR=/path/to/signature
|
|
LBC_LIB_DIR=/path/to/lib # Directory containing the required libs
|
|
# If using a release bundle, this is the included lib/ directory
|
|
```
|
|
|
|
> The `justfile` at the repo root contains recipes (`just poq`, `just pol`, etc.) that build the circuit libraries from
|
|
> source.
|
|
>
|
|
> This is not yet an officially supported workflow, but it can serve as a reference if you need to produce the
|
|
> libraries yourself.
|
|
|
|
## Usage
|
|
|
|
### In-memory witness generation
|
|
|
|
```rust
|
|
use lbc_poq_sys::native::{PoqWitnessInput, generate_witness};
|
|
use lbc_types::native::{Error, Witness};
|
|
|
|
fn main() -> Result<Witness, Error> {
|
|
let inputs_json = std::fs::read_to_string("poq-input.json").expect("failed to read input");
|
|
let input = PoqWitnessInput::new(inputs_json)?;
|
|
generate_witness(&input)
|
|
}
|
|
```
|
|
|
|
### File-based witness generation
|
|
|
|
```rust
|
|
use lbc_poq_sys::native::generate_witness_from_files;
|
|
use lbc_types::native::Error;
|
|
use std::path::Path;
|
|
|
|
fn main() -> Result<(), Error> {
|
|
generate_witness_from_files(
|
|
Path::new("/path/to/witness_generator"), // Extensionless .dat file
|
|
Path::new("poq-input.json"),
|
|
Path::new("output.wtns"),
|
|
)?;
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
The other circuits follow the same pattern under `lbc_pol_sys`, `lbc_poc_sys` and `lbc_signature_sys`.
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
cargo test
|
|
```
|