Crate satellite_shard

Expand description

§Satellite Account Shards

A high-performance library for managing sharded account state in Bitcoin-based blockchain programs. This crate provides ergonomic tools for working with distributed UTXO sets across multiple shards while maintaining atomicity and consistency.

§Overview

This library is designed for applications that need to manage large amounts of Bitcoin UTXOs and Rune tokens across multiple shards for scalability. It provides:

Type-safe shard management with compile-time state tracking
Efficient UTXO distribution across shards
Atomic transaction building with proper fee calculation
Rune token support for managing fungible tokens on Bitcoin
Zero-copy serialization for high-performance applications

§Quick start

Add the dependency to your Cargo.toml (defaults enable runes and utxo-consolidation):

saturn-account-shards = "0.1"

Create a ShardSet, select shards, call helpers:

use satellite_shard::{ShardSet, StateShard};

// Build an *unselected* set and then pick the shards we need.
let shard_set = ShardSet::<SingleRuneSet, UtxoInfo<SingleRuneSet>, DummyShard, 2>::from_loaders(&mut loaders);
let mut selected = shard_set.select_with([0, 1]).unwrap();

// Call any of the high-level helpers, e.g. redistribute BTC back to the shards.
// selected.redistribute_remaining_btc_to_shards(...);

§Features

Feature flag	Purpose	Default
`runes`	Support for the Bitcoin Runes protocol (adds Rune-specific helpers)	✅
`utxo-consolidation`	Convenience helpers to combine many small UTXOs into fewer large ones	✅
`serde`	Enable `serde::{Serialize, Deserialize}` implementations where possible	❌

All items that require a feature are tagged on docs.rs via cfg(feature = "…") in their rust-doc header.

§Glossary

Term	Meaning
Shard	A single on-chain account that stores a portion of the global program state.
Pool	A collection of shards that together form one logical program state.
UTXO	Unspent Transaction Output: holds satoshis (and optionally Rune amounts) on the Bitcoin chain.
Rune	A fungible token defined by the Runes protocol and transported inside a Bitcoin UTXO.

§Key Components

§ShardSet

The central abstraction is [ShardSet], which provides a type-safe wrapper around a collection of shards. It uses the typestate pattern to ensure proper usage:

// Create an unselected shard set
let shard_set = ShardSet::<SingleRuneSet, UtxoInfo<SingleRuneSet>, DummyShard, 2>::new(&mut shards);

// Select shards to work with
let selected = shard_set.select_with([0, 1]).unwrap();

// Now high-level operations are available
// selected.redistribute_remaining_btc_to_shards(...);

§StateShard Trait

All shards must implement the StateShard trait, which provides a unified interface for managing both Bitcoin UTXOs and Rune tokens:

struct MyShard {
    btc_utxos: Vec<UtxoInfo<SingleRuneSet>>,
    rune_utxo: Option<UtxoInfo<SingleRuneSet>>,
}

impl StateShard<UtxoInfo<SingleRuneSet>, SingleRuneSet> for MyShard {
    fn btc_utxos(&self) -> &[UtxoInfo<SingleRuneSet>] {
        &self.btc_utxos
    }

    fn btc_utxos_mut(&mut self) -> &mut [UtxoInfo<SingleRuneSet>] {
        &mut self.btc_utxos
    }

    // ... implement other required methods

§Common Operations

§Selecting Shards

let shard_set = ShardSet::<SingleRuneSet, UtxoInfo<SingleRuneSet>, DummyShard, 5>::new(&mut shard_refs);

// Select specific shards by index
let selected = shard_set.select_with([0, 2, 4]).unwrap();

// Select the shard with minimum BTC
// let selected = shard_set.select_min_by(|s| s.total_btc()).unwrap();

// Select shards that meet a condition
// let selected = shard_set.select_multiple_by(|s| s.btc_utxos_len() > 0).unwrap();

§Redistributing Liquidity

// Redistribute remaining BTC evenly across selected shards
let redistributed = selected.redistribute_remaining_btc_to_shards(
    &mut tx_builder,
    removed_from_shards,
    program_script,
    &fee_rate,
).unwrap();

Structs§

AccountUtxos: A container holding the UTXOs owned by a single program account.

Enums§

DistributionError: Errors specific to distribution and dust handling logic in this module.

Traits§

IntoShardIndices: Abstraction over “something that can be turned into a list of shard indices”.
StateShard: Abstraction over a shard of state held by an on-chain program.

Functions§

compute_unsettled_btc_in_shards: Sums the BTC value of shard-owned UTXOs that this transaction spends and subtracts the fees paid by the program and any amounts already removed from the shards to produce the unsettled amount.
compute_unsettled_rune_in_shards: Calculates the total Rune token amount still owned by selected shards after accounting for tokens that have already been removed.
ensure_rune_utxo_present_in_all: Validates that each shard in selected_shards currently has a rune UTXO.
plan_rune_distribution_among_shards: Plans an optimal Rune token distribution across selected shards to achieve balanced holdings without applying dust limits.
redistribute_remaining_btc_to_shards: Redistributes the remaining satoshi value belonging to the provided shards back into brand-new outputs (one per retained allocation after dust-limit filtering) to achieve optimal liquidity balance across all participating shards.
redistribute_remaining_rune_to_shards: Redistributes remaining Rune tokens across shards and generates corresponding transaction outputs and runestone edicts for on-chain execution.
select_max_by: Select the shard that maximises the value returned by key_fn. Returns the index of the selected shard, or None if no shards are available.
select_min_by: Select the shard that minimises the value returned by key_fn. Returns the index of the selected shard, or None if no shards are available.
select_multiple_by: Select all shards that satisfy the provided predicate.
select_multiple_sorted: Select a minimal set of shards – ordered by key_fn (descending) – such that the accumulated predicate evaluates to true.
select_with: Select shards by index from a ShardList of shard references.
update_shards_after_transaction: Updates the provided shards to reflect the effects of a transaction that has just been broadcast and accepted.
update_shards_after_transaction_split: Updates shard state after a Bitcoin transaction when the caller already holds two separate mutable slices: one for shards that should store rune-bearing UTXOs and another for shards that should only store plain BTC UTXOs.