Bee-rs

Rust SDK for the Swarm decentralised storage.

Intended to be used with Bee version 2.5.0.

Quick start

Start a Swarm project using Rust:

cargo new my-dapp
cd my-dapp
cargo add bee-rs

Install

Add the following to your Cargo.toml file:

[dependencies]
bee-rs = "0.1.0" # Replace with the latest version

Import

use bee_rs::Bee;

Overview

Type interfaces

NumberString is a branded type for marking strings that represent numbers. It interops with string and bigint types. Where NumberString is present, number is disallowed in order to avoid pitfalls with unsafe large values.

Byte primitives

All the classes below extend Bytes, therefor the following methods are available on all of them: to_uint8_array, to_hex, to_base64, to_base32, to_utf8, to_json, static keccak256, static from_utf8.

The to_string method uses to_hex.

Bytes and its subclasses may be constructed with new from Uint8Array or hex string.

Elliptic

Name	Description	Methods
PrivateKey	32 bytes private key	public_key, sign
PublicKey	64 bytes public key	address, to_compressed_uint8_array, to_compressed_hex
EthAddress	20 bytes Ethereum address	to_checksum
Signature	65 bytes signature	recover_public_key

Swarm

Name	Description	Methods
Reference	32/64 bytes reference (chunk, feed)	to_cid
Identifier	32 bytes identifier (SOC, Feed)	-
TransactionId	32 bytes transaction ID	-
FeedIndex	8 bytes feed index (BE)	static from_bigint, to_bigint
Topic	32 bytes topic	static from_string
PeerAddress	32 bytes peer address	-
BatchId	32 bytes batch ID	-
Span	8 bytes span (LE)	static from_bigint, to_bigint

Tokens

Name	Description	Methods
DAI	ERC20 DAI token (18 digits)	static from_decimal_string, static from_wei, to_wei_string, to_wei_bigint, to_decimal_string
BZZ	ERC20 BZZ token (16 digits)	static from_decimal_string, static from_plur, to_plur_string, to_plur_bigint, to_decimal_string

Swarm chunks

Name	Description	Creation
Chunk	Span, max. 4096 bytes payload; address dervied from content	make_content_addressed_chunk
SingleOwnerChunk	Identifier, signature, span, max. 4096 bytes payload; address derived from identifier and owner	make_single_owner_chunk

Swarm primitives

Name	Description	Methods
MantarayNode	Compact trie with reference values and JSON metadata	add_fork, remove_fork, calculate_self_address, find, find_closest, collect, marshal, unmarshal, save_recursively, load_recursively
MerkleTree	Streaming BMT of chunks	append, finalize, static root

Swarm objects

Name	Description	Creation
SOCWriter	SingleOwnerChunk writer	bee.make_soc_writer
SOCReader	SingleOwnerChunk reader	bee.make_soc_reader
FeedWriter	Feed writer	bee.make_feed_writer
FeedReader	Feed reader	bee.make_feed_reader

Bee API

Note: This section is a work in progress and may not be accurate for the Rust implementation.

• ❌❌✅ - Full node only
• ❌✅✅ - Light node and full node
• ✅✅✅ - Ultra-light node, light node and full node

JS Call	Bee Endpoint	Bee Mode
upload_file	POST /bzz 🔗	❌✅✅
upload_files_from_directory Node.js	POST /bzz 🔗	❌✅✅
upload_files	POST /bzz 🔗	❌✅✅
upload_collection	POST /bzz 🔗	❌✅✅
upload_data	POST /bytes 🔗	❌✅✅
upload_chunk	POST /chunks 🔗	❌✅✅
stream_directory Node.js	POST /chunks 🔗	❌✅✅
stream_files Browser	POST /chunks 🔗	❌✅✅
soc_writer.upload	POST /soc/:owner/:identifier 🔗	❌✅✅
feed_reader.download	GET /feeds/:owner/:topic 🔗	✅✅✅
feed_writer.update_feed	POST /soc/:owner/:identifier 🔗	❌✅✅
download_file	GET /bzz/:reference 🔗	✅✅✅
download_file	GET /bzz/:reference/:path 🔗	✅✅✅
download_readable_file	GET /bzz/:reference 🔗	✅✅✅
download_data	GET /bytes/:reference 🔗	✅✅✅
download_readable_data	GET /bytes/:reference 🔗	✅✅✅
download_chunk	GET /chunks/:reference 🔗	✅✅✅
create_feed_manifest	POST /feeds/:owner/:topic 🔗	❌✅✅
is_connected	GET /	✅✅✅
get_health	GET /health 🔗	✅✅✅
get_readiness	GET /readiness 🔗	✅✅✅
get_node_info	GET /node 🔗	✅✅✅
get_chain_state	GET /chainstate 🔗	❌✅✅
get_redistribution_state	GET /redistributionstate 🔗	❌❌✅
get_reserve_state	GET /reservestate 🔗	❌❌✅
get_status	GET /status 🔗	✅✅✅
get_wallet	GET /wallet 🔗	❌✅✅
get_topology	GET /topology 🔗	✅✅✅
get_addresses	GET /addresses 🔗	✅✅✅
get_peers	GET /peers 🔗	✅✅✅
get_all_balances	GET /balances 🔗	❌✅✅
get_peer_balance	GET /balances/:peer 🔗	❌✅✅
get_past_due_consumption_balances	GET /consumed 🔗	❌✅✅
get_past_due_consumption_peer_balance	GET /consumed/:peer 🔗	❌✅✅
get_all_settlements	GET /settlements 🔗	❌✅✅
get_settlements	GET /settlements/:peer 🔗	❌✅✅
get_chequebook_address	GET /chequebook/address 🔗	❌✅✅
get_chequebook_balance	GET /chequebook/balance 🔗	❌✅✅
get_last_cheques	GET /chequebook/cheque 🔗	❌✅✅
get_last_cheques_for_peer	GET /chequebook/cheque/:peer 🔗	❌✅✅
get_last_cashout_action	GET /chequebook/cashout/:peer 🔗	❌✅✅
cashout_last_cheque	POST /chequebook/cashout/:peer 🔗	❌✅✅
deposit_tokens	POST /chequebook/deposit 🔗	❌✅✅
withdraw_tokens	POST /chequebook/withdraw 🔗	❌✅✅
get_all_pending_transactions	GET /transactions 🔗	❌✅✅
get_pending_transaction	GET /transactions/:id 🔗	❌✅✅
rebroadcast_transaction	POST /transactions/:id 🔗	❌✅✅
cancel_transaction	DELETE /transactions/:id 🔗	❌✅✅
create_tag	POST /tags 🔗	❌✅✅
retrieve_tag	GET /tags/:id 🔗	❌✅✅
get_all_tags	GET /tags 🔗	❌✅✅
delete_tag	DELETE /tags/:id 🔗	❌✅✅
update_tag	PATCH /tags/:id 🔗	❌✅✅
pin	POST /pins/:reference 🔗	✅✅✅
get_all_pins	GET /pins 🔗	✅✅✅
get_pin	GET /pins/:reference 🔗	✅✅✅
is_reference_retrievable	GET /stewardship/:reference 🔗	✅✅✅
reupload_pinned_data	PUT /stewardship/:reference 🔗	❌✅✅
unpin	DELETE /pins/:reference 🔗	✅✅✅
get_grantees	GET /grantee/:reference 🔗	❌✅✅
create_grantees	POST /grantee 🔗	❌✅✅
patch_grantees	PATCH /grantee/:reference 🔗	❌✅✅
pss_send	POST /pss/send/:topic/:target 🔗	❌✅✅
pss_subscribe Websocket	GET /pss/subscribe/:topic 🔗	❌❌✅
pss_receive	GET /pss/subscribe/:topic 🔗	❌❌✅
get_all_postage_batch	GET /stamps 🔗	❌✅✅
get_global_postage_batches	GET /batches 🔗	❌✅✅
get_postage_batch	GET /stamps/:batchId 🔗	❌✅✅
get_postage_batch_buckets	GET /stamps/:batchId/buckets 🔗	❌✅✅
create_postage_batch	POST /stamps/:amount/:depth 🔗	❌✅✅
top_up_batch	PATCH /stamps/topup/:batchId/:amount 🔗	❌✅✅
dilute_batch	PATCH /stamps/dilute/:batchId/:depth 🔗	❌✅✅
create_envelope	POST /envelope/:reference 🔗	❌✅✅
get_stake	GET /stake 🔗	❌❌✅
deposit_stake	POST /stake 🔗	❌❌✅

Utils

General

• get_collection_size
• get_folder_size

PSS

• make_max_target

Erasure Coding

• approximate_overhead_for_redundancy_level
• get_redundancy_stat
• get_redundancy_stats

Stamps

• get_amount_for_ttl
• get_depth_for_capacity
• get_stamp_cost
• get_stamp_effective_bytes
• get_stamp_maximum_capacity_bytes
• get_stamp_ttl_seconds
• get_stamp_usage

Usage

Upload via Swarm Gateway

use bee_rs::{Bee, NULL_STAMP, SWARM_GATEWAY_URL};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bee = Bee::new(SWARM_GATEWAY_URL);
    let result = bee.upload_data(NULL_STAMP, "Hello, World!").await?;
    println!("{}", result.reference);
    Ok(())
}

Create or select an existing postage batch

Swarm incentivizes nodes in the network to store content, therefor all uploads require a paid postage batch.

use bee_rs::Bee;

async fn get_or_create_postage_batch() -> Result<String, Box<dyn std::error::Error>> {
    let bee = Bee::new("http://localhost:1633");
    let batch_id = if let Some(usable) = bee.get_all_postage_batch().await?.into_iter().find(|x| x.usable) {
        usable.batch_id
    } else {
        bee.buy_storage(Size::from_gigabytes(1), Duration::from_days(7)).await?
    };
    Ok(batch_id)
}

The following examples all assume an existing batch_id.

Upload simple data

use bee_rs::Bee;

let bee = Bee::new("http://localhost:1633");

let upload_result = bee.upload_data(&batch_id, "Bee is awesome!").await?;
let data = bee.download_data(upload_result.reference).await?;

println!("{}", String::from_utf8_lossy(&data)); // prints 'Bee is awesome!'

Upload arbitrary large file

use bee_rs::Bee;
use tokio::fs::File;

let bee = Bee::new("http://localhost:1633");
let file = File::open("./path/to/large.bin").await?;
let upload_result = bee.upload_file(&batch_id, file).await?;

Contribute

Stay up to date by joining the official Discord and by keeping an eye on the releases tab.

We are using Conventional Commits for our commit messages and pull requests, following the Semantic Versioning rules.

There are some ways you can make this module better:

• Consult our open issues and take on one of them
• Help our tests reach 100% coverage!
• Join us in our Discord chat in the #develop-on-swarm channel if you have questions or want to give feedback

Setup

Install project dependencies:

cargo build

Test

cargo test

License

BSD-3-Clause