README
¶
us
us is an alternative interface to the Sia
network. It provides low-level, developer-oriented APIs and formats that
facilitate the storage and retrieval of files on Sia. "Low-level" means that
us generally avoids making decisions on behalf of the user. For example,
when renting storage, the user must decide which hosts to form contracts with,
how many coins to spend on each contract, when to renew contracts, when to
migrate data to new hosts, etc. These questions do not have simple answers;
they vary according to the context and goals of the user. Recognizing this,
the us philosophy is to provide the user with a set of building blocks
rather than a one-size-fits-all solution.
Why should I care?
us enables you to do a number of cool things with Sia that were previously
infeasible, difficult, or inefficient. You can specify exactly which hosts you
want to use. You can collect data on exactly how much you paid to download a
file, and exactly how long it took the host to transfer it to you. You can use
this information to manually blacklist hosts, selecting only the cheapest or
fastest hosts when downloading. You can "pack" multiple files into a single
uploaded sector: if you're uploading an album of JPEGs averaging 250 KB each,
this reduces storage and bandwidth costs by about 16x. You can download one of
those JPEGs without downloading the full sector, too. You can trivially share
files, just by sending the metadata to a friend. You can stream files over
HTTP or mount a virtual Sia filesystem with FUSE, enjoying low latency as a
result of partial downloads. You can upload and download without needing to
run a full consensus node. And most importantly, you can build apps that
leverage Sia to store and serve content.
Here are some ideas for apps you could build with us:
- A storage backend for go-cloud, upspin, or minio
- A site where you can buy contracts directly, paying with BTC (via LN?) instead of SC
- A cron job that downloads 1 KB from a host every 24 hours and reports various metrics (latency, bandwidth, price)
- A site that aggregates host metrics to provide a centralized host database
- A gateway that serves static websites stored on Sia
- A mobile app that stores and retrieves files stored on Sia
What do I need to get started?
Run go get gitlab.com/SiaPrime/us/... to install us and its
dependencies. For subsequent builds, run make. No pre-built binaries
are provided at this time.
If you want to use us to manage your contracts and files manually, you're
looking for user, a CLI tool that provides convenient access to us
functionality. A usage guide is available here.
If you want to use us to build apps, please read DEVELOPERS.md.
If you would like to contribute (thank you!), please read CONTRIBUTING.md.
What else do I need to know?
user demands much more work on behalf of the user than siad. You are
responsible for choosing good hosts to form contracts with, and for migrating
file data to new hosts if the old hosts flake out. Failure to perform these
duties can result in loss of data.
Please be aware that us is in an experimental, unstable state. us
contracts and files differ from the corresponding siad formats, so you
should not assume that contracts formed and files uploaded using us are
transferable to siad, nor vice versa. Until us is marked as stable,
don't spend any siacoins on us that you can't afford to lose.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
Package hostdb defines types and functions relevant to scanning hosts.
|
Package hostdb defines types and functions relevant to scanning hosts. |
|
internal
|
|
|
ed25519
Package ed25519 implements the Ed25519 signature algorithm.
|
Package ed25519 implements the Ed25519 signature algorithm. |
|
reedsolomon
Package reedsolomon enables Erasure Coding in Go
|
Package reedsolomon enables Erasure Coding in Go |
|
Package merkle provides Sia-specific Merkle tree utilities.
|
Package merkle provides Sia-specific Merkle tree utilities. |
|
Package renter provides formats for contracts and files.
|
Package renter provides formats for contracts and files. |
|
proto
Package proto implements the renter side of the Sia renter-host protocol.
|
Package proto implements the renter side of the Sia renter-host protocol. |
|
renterutil
Package renterutil provides convenience functions for common renter actions.
|
Package renterutil provides convenience functions for common renter actions. |
|
Package renterhost implements the handshake and transport for the Sia renter-host protocol.
|
Package renterhost implements the handshake and transport for the Sia renter-host protocol. |