proto

Documentation

Overview

Package proto implements the Sia renter-host protocol.

Index

• Constants
• Variables
• func CachedMerkleRoot(roots []crypto.Hash) crypto.Hash
• func SectorMerkleRoot(sector *[SectorSize]byte) crypto.Hash
• type ContractEditor
• type ContractTransaction
  • func FormContract(w Wallet, tpool TransactionPool, host hostdb.ScannedHost, ...) (ContractTransaction, error)
  • func RenewContract(w Wallet, tpool TransactionPool, contract ContractEditor, ...) (ContractTransaction, error)
  • func (c ContractTransaction) CurrentRevision() types.FileContractRevision
  • func (c ContractTransaction) EndHeight() types.BlockHeight
  • func (c ContractTransaction) HostKey() hostdb.HostPublicKey
  • func (c ContractTransaction) ID() types.FileContractID
  • func (c ContractTransaction) IsValid() bool
  • func (c ContractTransaction) RenterFunds() types.Currency
• type Downloader
  • func NewDownloader(host hostdb.ScannedHost, contract ContractEditor) (*Downloader, error)
  • func (d *Downloader) Close() error
  • func (d *Downloader) HostKey() hostdb.HostPublicKey
  • func (d *Downloader) PartialSector(root crypto.Hash, offset, length uint32) ([]byte, error)
  • func (d *Downloader) Sector(root crypto.Hash) (*[SectorSize]byte, error)
• type TransactionPool
• type Uploader
  • func NewUploader(host hostdb.ScannedHost, contract ContractEditor, ...) (*Uploader, error)
  • func (u *Uploader) Close() error
  • func (u *Uploader) HostKey() hostdb.HostPublicKey
  • func (u *Uploader) Upload(data *[SectorSize]byte) (crypto.Hash, error)
• type Wallet

Constants

const (
	// SegmentSize is the number of bytes in each leaf node of a sector's Merkle
	// tree.
	SegmentSize = 64

	// SegmentsPerSector is a convenience value.
	SegmentsPerSector = SectorSize / SegmentSize
)

const SectorSize = 1 << 22 // 4 MiB

SectorSize is the size of one sector in bytes.

Variables

var ErrDesynchronized = errors.New("renter contract has permanently desynchronized from host")

ErrDesynchronized is returned by ContractEditor.SyncWithHost to indicate that synchronization is impossible.

Functions

func CachedMerkleRoot

func CachedMerkleRoot(roots []crypto.Hash) crypto.Hash

CachedMerkleRoot calculates the root of a set of existing Merkle roots.

func SectorMerkleRoot

func SectorMerkleRoot(sector *[SectorSize]byte) crypto.Hash

SectorMerkleRoot computes the Merkle root of a sector, using the standard Sia leaf size.

Types

type ContractEditor

type ContractEditor interface {
	// Transaction returns the transaction containing the latest revision of
	// the file contract.
	Transaction() ContractTransaction

	// Revise sets the latest revision of the contract.
	Revise(rev types.FileContractRevision) error

	// AppendRoot appends a sector root to the contract, returning the new
	// top-level Merkle root. The root should be written to durable storage.
	AppendRoot(root crypto.Hash) (crypto.Hash, error)

	// NumSectors returns the number of sector roots in the contract.
	NumSectors() int

	// SyncWithHost synchronizes the local version of the contract with the
	// host's version. This may involve modifying the sector roots and/or
	// contract revision. SyncWithHost returns ErrDesynchronized iff the
	// contract has permanently desynchronized with the host and recovery is
	// impossible.
	SyncWithHost(rev types.FileContractRevision, hostSignatures []types.TransactionSignature) error
}

A ContractEditor provides an interface for viewing and updating a file contract transaction and the Merkle roots of each sector covered by the contract.

type ContractTransaction

type ContractTransaction struct {
	Transaction types.Transaction
	RenterKey   crypto.SecretKey
}

A ContractTransaction contains a file contract transaction and the secret key used to sign it.

func FormContract

func FormContract(w Wallet, tpool TransactionPool, host hostdb.ScannedHost, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractTransaction, error)

FormContract forms a contract with a host. The resulting contract will have renterPayout coins in the renter output.

func RenewContract

func RenewContract(w Wallet, tpool TransactionPool, contract ContractEditor, host hostdb.ScannedHost, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractTransaction, error)

RenewContract negotiates a new file contract and initial revision for data already stored with a host.

func (ContractTransaction) CurrentRevision

func (c ContractTransaction) CurrentRevision() types.FileContractRevision

CurrentRevision returns the most recently negotiated revision of the original FileContract.

func (ContractTransaction) EndHeight

func (c ContractTransaction) EndHeight() types.BlockHeight

EndHeight returns the height at which the host is no longer obligated to store contract data.

func (ContractTransaction) HostKey

func (c ContractTransaction) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host.

func (ContractTransaction) ID

func (c ContractTransaction) ID() types.FileContractID

ID returns the ID of the original FileContract.

func (ContractTransaction) IsValid

func (c ContractTransaction) IsValid() bool

IsValid returns false if the Contract does not contain a FileContractRevision, or contains a FileContractRevision without the proper number of outputs.

func (ContractTransaction) RenterFunds

func (c ContractTransaction) RenterFunds() types.Currency

RenterFunds returns the funds remaining in the contract's Renter payout as of the most recent revision.

type Downloader

type Downloader struct {
	// contains filtered or unexported fields
}

A Downloader retrieves sectors by calling the download RPC on a host. It updates the corresponding contract after each iteration of the download protocol.

func NewDownloader

func NewDownloader(host hostdb.ScannedHost, contract ContractEditor) (*Downloader, error)

NewDownloader initiates the download request loop with a host, and returns a Downloader.

func (*Downloader) Close

func (d *Downloader) Close() error

Close cleanly terminates the download loop with the host and closes the connection.

func (*Downloader) HostKey

func (d *Downloader) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host being downloaded from.

func (*Downloader) PartialSector

func (d *Downloader) PartialSector(root crypto.Hash, offset, length uint32) ([]byte, error)

PartialSector retrieves the slice of sector data uniquely identified by root, offset, and length, and revises the underlying contract to pay the host proportionally to the data retrieved. The returned slice is only valid until the next call to Sector.

Unlike Sector, the integrity of the data cannot be verified by computing its Merkle root. Callers must implement a different means of integrity- checking, such as comparing against a known checksum.

Calls to PartialSector must be serialized.

func (*Downloader) Sector

func (d *Downloader) Sector(root crypto.Hash) (*[SectorSize]byte, error)

Sector retrieves the sector with the specified Merkle root, and revises the underlying contract to pay the host appropriately. Sector verifies the integrity of the retrieved data by comparing its computed Merkle root to root. The returned slice is only valid until the next call to Sector.

Calls to Sector must be serialized.

type TransactionPool

type TransactionPool interface {
	AcceptTransactionSet([]types.Transaction) error
	FeeEstimate() (min types.Currency, max types.Currency)
}

A TransactionPool can broadcast transactions and estimate transaction fees.

type Uploader

type Uploader struct {
	// contains filtered or unexported fields
}

An Uploader uploads sectors by calling the revise RPC on a host. It updates the underlying file contract after each iteration of the upload protocol.

func NewUploader

func NewUploader(host hostdb.ScannedHost, contract ContractEditor, currentHeight types.BlockHeight) (*Uploader, error)

NewUploader initiates the contract revision process with a host, and returns an Uploader.

func (*Uploader) Close

func (u *Uploader) Close() error

Close cleanly terminates the revision loop with the host and closes the connection.

func (*Uploader) HostKey

func (u *Uploader) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host being uploaded to.

func (*Uploader) Upload

func (u *Uploader) Upload(data *[SectorSize]byte) (crypto.Hash, error)

Upload negotiates a revision that adds a sector to a file contract, and revises the underlying contract to pay the host appropriately. Calls to Upload must be serialized.

type Wallet

type Wallet interface {
	NewWalletAddress() (types.UnlockHash, error)
	SignTransaction(txn *types.Transaction, toSign map[types.OutputID]types.UnlockHash) error
	SpendableOutputs() []modules.SpendableOutput
}

A Wallet provides addresses and outputs, and can sign transactions.