Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

185 Commits

Folders and files

Repository files navigation

Unicity State Transition SDK — Rust

Build applications that mint, transfer, and verify digital assets on the Unicity Network. This Rust SDK gives you control over tokens, ownership rules, and payments, with cryptographic verification built in.

Unicity combines private, off-chain token transactions with network-backed protection against double-spending. Token data stays with the parties you share it with, while unicity proofs let recipients verify that assets are spent only once. The network is designed to scale horizontally as demand grows.

  • Create digital assets: mint tokens with your own types and application data payload.
  • Move value: transfer tokens and split fungible tokens for payments.
  • Verify locally: validate token history and unicity proofs against the compact trust base.
  • Integrate with your application: choose ownership predicates, issuance policies, storage, and delivery channels.
  • Use Rust across environments: use the HTTP client in host applications or the no_std verification core in WASM and zkVM guests.

Installation

Requires Rust 1.81 or later. Add the SDK with its HTTP client to your Cargo.toml:

[dependencies]
unicity-token = { version = "4.0", features = ["http"] }

Unicity Network

Mainnet is live. Start with testnet2; for production, use the mainnet gateway and matching trust base.

Network Gateway Network ID
Mainnet https://gateway.mainnet.unicity.network 1
Testnet2 https://gateway.testnet2.unicity.network 4

Pass your gateway API key through HttpAggregatorClient::with_api_key. The public testnet2 key is sk_ddc3cfcc001e4a28ac3fad7407f99590. Use your own mainnet key obtained from Sphere and keep it secure.

Every aggregator request carries X-SDK-Version: rust/<crate version> so that the SDK versions in use can be measured (the aggregator never reads it). Switch it off or set your own value with HttpAggregatorClient::with_sdk_version_header(SdkVersionHeader::Off | Custom(..)).

Client setup

Configure the client below. Verification needs a trust-base history pinned to a known genesis; open it through a session using the mainnet, testnet2 or local setup.

use std::time::Duration;
use unicity_token::client::HttpAggregatorClient;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let aggregator = HttpAggregatorClient::new(
        "https://gateway.testnet2.unicity.network",
    )
    .with_api_key("sk_ddc3cfcc001e4a28ac3fad7407f99590") // Public testnet2 key
    .with_polling(Duration::from_secs(2), 90);

    Ok(())
}

HttpAggregatorClient provides a blocking HTTP transport. Applications can implement the AggregatorClient trait to supply their own transport.

Working with tokens

The SDK handles cryptography and token encoding. Your application manages keys, stores tokens, and delivers them to recipients over your chosen transport.

Task SDK entry points Example
Mint a token client::mint Mint
Transfer ownership client::transfer Transfer
Split a fungible token payment::TokenSplit::split Split
Verify a payment token payment::verify_payment_token Payment verification

client::mint and client::transfer submit the transaction, wait for its unicity proof (InclusionProof in the API), and return the verified token. The split example includes payment verifier setup.

While waiting, the client stops early with HttpError::StateExpired or HttpError::StateUnknown when the aggregator reports that it dropped the request or does not know it. The same signed request can then be submitted again. The wait uses long polling by default: the aggregator holds each request open while the state is pending, so the proof arrives soon after certification. Servers without long polling are polled at the configured interval. See the API reference.

Store, send, and receive

Serialize with token.to_cbor() to save or send a token, and deserialize with Token::from_cbor(bytes) to load it. Verify received tokens before accepting them:

use unicity_token::Token;

// `token_bytes` comes from your storage or transport; `session` is opened as in the API reference.
let token = Token::from_cbor(&token_bytes)?;
token.verify(session.history()?)?;

Token::verify checks cryptographic history; application data remains opaque. Use Token::verify_with for registered mint justifications and payment::verify_payment_token for payments.

Proof consolidation

Each transaction in a token's history has its own unicity proof, usually certified in a different round. Verifying the history in a constrained environment, such as a smart contract or a zkVM guest, means authenticating every one of those certificates. client::ProofClient::consolidate fetches new proofs for the token's history so that they share one unicity certificate, which then has to be authenticated only once. It is optional and the SDK never calls it on its own. See the API reference and examples/consolidate_for_zkvm.rs.

Non-inclusion proofs

A non-inclusion proof shows that a state ID was absent from the aggregator's state tree at one certified snapshot. It does not show that the state is absent now or that a token can be spent. AggregatorClient::get_non_inclusion_proof fetches the proof, and NonInclusionProof::verify_at_snapshot verifies it and returns the authenticated snapshot. Before relying on the result, compare the snapshot's network and round with a checkpoint your application trusts independently. See the API reference.

Run the examples

From a repository checkout, set the public testnet2 key and run a flow:

export UNICITY_API_KEY=sk_ddc3cfcc001e4a28ac3fad7407f99590
cargo run --example mint --features http
cargo run --example transfer --features http
cargo run --example split --features http

These examples open a trust-base session (the testnet2 release pin by default), extend it from the aggregator and verify with session.history(). Configure UNICITY_GATEWAY and UNICITY_API_KEY through your environment or e2e/.env; set UNICITY_NETWORK=mainnet for mainnet or UNICITY_LOCAL_BUNDLE to the complete trust-base bundle of a local deployment. Example keys are discarded on exit. See example configuration.

Security

Unicity proofs provide independently verifiable evidence of certified state transitions being unique, backed by the network's Byzantine fault tolerant consensus. Together with ownership verification, they protect against double-spending without publishing token contents to a public ledger.

Verify tokens against the correct trust-base history and configure accepted issuers through PaymentDataVerifier and MintJustificationRegistry. Cryptographic validity does not authorize an issuer. Keep private keys and token backups secure, and check that received tokens belong to the intended recipient.

Feature flags

Feature Default Purpose
alloc Via std and client Allocated structures used by the verification core.
std Yes Standard library integration and key generation.
client Yes Transaction construction, signing, minting, transfers, and split construction.
file-cache No Optional host filesystem store for trust-base sessions.
http No Blocking HTTP client for host applications. Enables std and client.

For verification in a no_std environment, including WASM and zkVM guests:

[dependencies]
unicity-token = { version = "4.0", default-features = false, features = ["alloc"] }

Token and payment verification remain available in this configuration. Verification is anchored in a pinned TrustBaseHistory; see the API reference.

Development

cargo test
cargo test --all-features
cargo test --no-default-features --features alloc
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings

The live end-to-end test is ignored by default. It reads gateway credentials from e2e/unicity-service and verifies with the testnet2 release-pin session, extended from the aggregator:

cargo test --features http --test e2e -- --ignored --nocapture

Resources

License

MIT OR Apache-2.0.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages