Crate sia_storage

Expand description

A Rust SDK for storing and retrieving data on the Sia decentralized storage network.

Sia is a decentralized cloud storage platform where data is stored across a global network of independent hosts. Storage contracts are enforced by the Sia blockchain, so no single party controls your data. Compared to centralized providers, Sia offers lower costs, stronger privacy (data is client-side encrypted by default), and censorship resistance.

This crate provides a high-level interface for interacting with Sia through an indexer service. Data is automatically erasure-coded, encrypted, and distributed across hosts on the network.

§Getting started

Define your AppMetadata as a constant. The AppID is used to derive the user’s encryption keys – if it changes, previously stored data becomes inaccessible. Generate it once (e.g. with a random hash) and never change it.

Use Builder to connect to an indexer and obtain an SDK instance. There are two paths:

First time: Call Builder::request_connection to start the approval flow, then Builder::wait_for_approval once the user has approved, and finally Builder::register to complete setup. This derives an AppKey from the user’s recovery phrase.
Returning: Call Builder::connected with a previously exported AppKey.

Once you have an SDK, use it to upload, download, and manage objects:

// Upload
let object = sdk.upload(Object::default(), reader, UploadOptions::default()).await?;
sdk.pin_object(&object).await?;

// Download
sdk.download(&mut writer, &object, DownloadOptions::default()).await?;

§Key management

The AppKey grants full access to a user’s data. After connecting, retrieve it with SDK::app_key, then persist it using AppKey::export and restore it with AppKey::import so users don’t need to re-approve on every launch.

Macros§

app_id: A macro to create an AppID from a literal hex string. The string must be 64 characters long.

Structs§

Account: Information about the user’s account on the indexer.
App: Metadata about a registered application on the indexer.
AppKey: An application key used for authentication with the indexd service, derived from the user’s mnemonic and a shared secret from the approval process.
AppMetadata: Application metadata for registering with an indexer.
ApprovedState: The state of the SDK builder after the application has been approved.
Builder: A builder for creating an SDK instance.
DateTime: ISO 8601 combined date and time with time zone.
DisconnectedState: The initial state of the SDK builder, before connecting to the indexd service.
DownloadOptions: Options for configuring a download.
EncryptionKey: A 256-bit symmetric encryption key used to encrypt and decrypt slab data.
GeoLocation: A host’s estimated geographic location represented as latitude and longitude coordinates.
Hash256
Host: Represents a host in the Sia network. The addresses can be used to connect to the host. A storage host on the Sia network.
HostQuery: Parameters for filtering hosts returned by SDK::hosts.
Object: A file stored on the Sia network, consisting of erasure-coded slabs and optional metadata.
ObjectEvent: An ObjectEvent represents an object and whether it was deleted or not.
ObjectsCursor: A cursor for paginating through object events returned by SDK::object_events.
PackedUpload: A packed upload allows multiple objects to be uploaded together in a single upload. This can be more efficient than uploading each object separately if the size of the object is less than the minimum slab size.
PinnedSlab: A slab that has been pinned to the indexer.
PublicKey: An ed25519 public key that can be used to verify a signature
RequestingApprovalState: The state of the SDK builder after requesting approval for the application.
SDK: The main interface with interacting with the Sia storage network. It provides methods for uploading and downloading objects, as well as managing hosts and account information.
SealedObject: An encrypted, signed representation of an Object that can be stored on the indexer.
Sector: A Sector is a unit of data stored on the Sia network. It can be referenced by its Merkle root.
Signature
Slab: A Slab is an erasure-coded collection of sectors. The sectors can be downloaded and used to recover the original data.
UploadOptions: Options for configuring an upload.
Url: A parsed URL record.
Utc: The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Enums§

AppApiError: Errors that can occur when communicating with the indexer API.
BuilderError: Errors that can occur during the SDK building process.
DownloadError: Errors that can occur during a download.
Error: Errors that can occur when using the SDK.
Protocol
QueueError: Errors from the host selection queue.
RPCError: Errors that can occur during host RPCs.
SealedObjectError: Errors that can occur when opening or verifying a sealed object.
SeedError
UploadError: Errors that can occur during an upload.

Traits§

IntoUrl: A trait to try to convert some type into a Url.

Functions§

generate_recovery_phrase: Generates a new BIP-39 12-word recovery phrase.
validate_recovery_phrase: Validates a BIP-39 recovery phrase.

Type Aliases§

AppID: A unique identifier for an indexer application. It should be constant for an application.