proto

Documentation

Overview

Package proto implements the renter side of the Sia renter-host protocol.

Index

• Variables
• func SubmitContractRevision(c ContractRevision, w Wallet, tpool TransactionPool) error
• type ContractEditor
• type ContractRevision
  • func FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, ...) (ContractRevision, error)
  • func RenewContract(w Wallet, tpool TransactionPool, contract ContractEditor, ...) (ContractRevision, error)
  • func (c ContractRevision) EndHeight() types.BlockHeight
  • func (c ContractRevision) HostKey() hostdb.HostPublicKey
  • func (c ContractRevision) ID() types.FileContractID
  • func (c ContractRevision) IsValid() bool
  • func (c ContractRevision) RenterFunds() types.Currency
• type DialStats
• type DownloadStats
• type Session
  • func NewSession(hostIP modules.NetAddress, contract ContractEditor, ...) (*Session, error)
  • func NewUnlockedSession(hostIP modules.NetAddress, hostKey hostdb.HostPublicKey, ...) (*Session, error)
  • func (s *Session) Close() error
  • func (s *Session) DialStats() DialStats
  • func (s *Session) FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, ...) (ContractRevision, error)
  • func (s *Session) HostKey() hostdb.HostPublicKey
  • func (s *Session) LastDownloadStats() DownloadStats
  • func (s *Session) LastUploadStats() UploadStats
  • func (s *Session) Lock(contract ContractEditor) error
  • func (s *Session) Read(w io.Writer, sections []renterhost.RPCReadRequestSection) error
  • func (s *Session) RenewContract(w Wallet, tpool TransactionPool, contract ContractEditor, ...) (ContractRevision, error)
  • func (s *Session) SectorRoots(offset, n int) ([]crypto.Hash, error)
  • func (s *Session) Settings() (hostdb.HostSettings, error)
  • func (s *Session) Unlock() error
  • func (s *Session) Write(actions []renterhost.RPCWriteAction) error
• type TransactionPool
• type UploadStats
• type Wallet

Variables

var ErrInvalidMerkleProof = errors.New("host supplied invalid Merkle proof")

ErrInvalidMerkleProof is returned by various RPCs when the host supplies an invalid Merkle proof.

Functions

func SubmitContractRevision

func SubmitContractRevision(c ContractRevision, w Wallet, tpool TransactionPool) error

SubmitContractRevision submits the latest revision of a contract to the blockchain, finalizing the renter and host payouts as they stand in the revision. Submitting a revision with a higher revision number will replace the previously-submitted revision.

Submitting revision transactions is a way for the renter to punish the host. If the host is well-behaved, there is no incentive for the renter to submit revision transactions. But if the host misbehaves, submitting the revision ensures that the host will lose the collateral it committed.

Types

type ContractEditor

type ContractEditor interface {
	// Revision returns the latest revision of the file contract.
	Revision() ContractRevision

	// SetRevision sets the current revision of the file contract. The revision
	// signatures do not need to be verified.
	SetRevision(rev ContractRevision) error

	// Key returns the renter's signing key.
	Key() ed25519.PrivateKey
}

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 ContractRevision

type ContractRevision struct {
	Revision   types.FileContractRevision
	Signatures [2]types.TransactionSignature
}

A ContractRevision contains the most recent revision to a file contract and its signatures.

func FormContract

func FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, host hostdb.ScannedHost, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractRevision, 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) (ContractRevision, error)

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

func (ContractRevision) EndHeight

func (c ContractRevision) EndHeight() types.BlockHeight

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

func (ContractRevision) HostKey

func (c ContractRevision) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host.

func (ContractRevision) ID

func (c ContractRevision) ID() types.FileContractID

ID returns the ID of the original FileContract.

func (ContractRevision) IsValid

func (c ContractRevision) IsValid() bool

IsValid returns false if the ContractRevision has the wrong number of public keys or outputs.

func (ContractRevision) RenterFunds

func (c ContractRevision) RenterFunds() types.Currency

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

type DialStats

type DialStats struct {
	DialStart     time.Time `json:"dialStart"`
	ProtocolStart time.Time `json:"protocolStart"`
	ProtocolEnd   time.Time `json:"protocolEnd"`
}

DialStats records metrics about dialing a host.

type DownloadStats

type DownloadStats struct {
	Bytes         int64          `json:"bytes"`
	Cost          types.Currency `json:"cost"`
	ProtocolStart time.Time      `json:"protocolStart"`
	ProtocolEnd   time.Time      `json:"protocolEnd"`
	TransferStart time.Time      `json:"transferStart"`
	TransferEnd   time.Time      `json:"transferEnd"`
}

DownloadStats records metrics about downloading sector data from a host.

type Session

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

A Session is an ongoing exchange of RPCs via the renter-host protocol.

func NewSession

func NewSession(hostIP modules.NetAddress, contract ContractEditor, currentHeight types.BlockHeight) (*Session, error)

NewSession initiates a new renter-host protocol session with the specified host. The supplied contract will be locked and synchronized with the host. The host's settings will also be requested.

func NewUnlockedSession

func NewUnlockedSession(hostIP modules.NetAddress, hostKey hostdb.HostPublicKey, currentHeight types.BlockHeight) (*Session, error)

NewUnlockedSession initiates a new renter-host protocol session with the specified host, without locking an associated contract or requesting the host's settings.

func (*Session) Close

func (s *Session) Close() error

Close gracefully terminates the session and closes the underlying connection.

func (*Session) DialStats

func (s *Session) DialStats() DialStats

DialStats returns the metrics of the initial connection to the host.

func (*Session) FormContract

func (s *Session) FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractRevision, error)

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

func (*Session) HostKey

func (s *Session) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host.

func (*Session) LastDownloadStats

func (s *Session) LastDownloadStats() DownloadStats

LastDownloadStats returns the metrics of the most recent successful download.

func (*Session) LastUploadStats

func (s *Session) LastUploadStats() UploadStats

LastUploadStats returns the metrics of the most recent successful upload.

func (*Session) Lock

func (s *Session) Lock(contract ContractEditor) error

Lock calls the Lock RPC, locking the supplied contract and synchronizing its state with the host's most recent revision. Subsequent RPCs will modify the supplied contract.

func (*Session) Read

func (s *Session) Read(w io.Writer, sections []renterhost.RPCReadRequestSection) error

Read calls the Read RPC, writing the requested sections of sector data to w. Merkle proofs are always requested.

func (*Session) RenewContract

func (s *Session) RenewContract(w Wallet, tpool TransactionPool, contract ContractEditor, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractRevision, error)

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

func (*Session) SectorRoots

func (s *Session) SectorRoots(offset, n int) ([]crypto.Hash, error)

SectorRoots calls the SectorRoots RPC, returning the requested range of sector Merkle roots of the currently-locked contract.

func (*Session) Settings

func (s *Session) Settings() (hostdb.HostSettings, error)

Settings calls the Settings RPC, returning the host's reported settings.

func (*Session) Unlock

func (s *Session) Unlock() error

Unlock calls the Unlock RPC, unlocking the currently-locked contract.

It is typically not necessary to manually unlock a contract, as the host will automatically unlock any locked contracts when the connection closes.

func (*Session) Write

func (s *Session) Write(actions []renterhost.RPCWriteAction) error

Write implements the Write RPC, except for ActionUpdate. A Merkle proof is always requested.

type TransactionPool

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

A TransactionPool can broadcast transactions and estimate transaction fees.

type UploadStats

type UploadStats struct {
	Bytes         int64          `json:"bytes"`
	Cost          types.Currency `json:"cost"`
	Collateral    types.Currency `json:"collateral"`
	ProtocolStart time.Time      `json:"protocolStart"`
	ProtocolEnd   time.Time      `json:"protocolEnd"`
	TransferStart time.Time      `json:"transferStart"`
	TransferEnd   time.Time      `json:"transferEnd"`
}

UploadStats records metrics about uploading sector data to a host.

type Wallet

type Wallet interface {
	NewWalletAddress() (types.UnlockHash, error)
	SignTransaction(txn *types.Transaction, toSign []crypto.Hash) error
	UnspentOutputs() ([]modules.UnspentOutput, error)
	UnlockConditions(addr types.UnlockHash) (types.UnlockConditions, error)
}

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