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) (err 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) NumSectors() int
  • func (c ContractRevision) RenterFunds() types.Currency
• type Session
  • func NewSession(hostIP modules.NetAddress, contract ContractEditor, ...) (_ *Session, err error)
  • func NewUnlockedSession(hostIP modules.NetAddress, hostKey hostdb.HostPublicKey, ...) (_ *Session, err error)
  • func (s *Session) Close() (err error)
  • func (s *Session) FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, ...) (_ ContractRevision, err error)
  • func (s *Session) HostKey() hostdb.HostPublicKey
  • func (s *Session) Lock(contract ContractEditor) (err error)
  • func (s *Session) Read(w io.Writer, sections []renterhost.RPCReadRequestSection) (err error)
  • func (s *Session) RenewContract(w Wallet, tpool TransactionPool, renterPayout types.Currency, ...) (_ ContractRevision, err error)
  • func (s *Session) SectorRoots(offset, n int) (_ []crypto.Hash, err error)
  • func (s *Session) Settings() (_ hostdb.HostSettings, err error)
  • func (s *Session) Unlock() (err error)
  • func (s *Session) Write(actions []renterhost.RPCWriteAction) (err error)
• type TransactionPool
• 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) (err 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) NumSectors

func (c ContractRevision) NumSectors() int

NumSectors returns the number of sectors covered by the contract.

func (ContractRevision) RenterFunds

func (c ContractRevision) RenterFunds() types.Currency

RenterFunds returns the funds remaining in the contract's Renter payout.

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, err 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, err 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() (err error)

Close gracefully terminates the session and closes the underlying connection.

func (*Session) FormContract

func (s *Session) FormContract(w Wallet, tpool TransactionPool, key ed25519.PrivateKey, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (_ ContractRevision, err 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) Lock

func (s *Session) Lock(contract ContractEditor) (err 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) (err 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, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (_ ContractRevision, err 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, err 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, err error)

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

func (*Session) Unlock

func (s *Session) Unlock() (err 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) (err 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 Wallet

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

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