proto

package
v0.19.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2022 License: MIT Imports: 20 Imported by: 8

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInsufficientFunds is returned by various RPCs when the renter is
	// unable to provide sufficient payment to the host.
	ErrInsufficientFunds = errors.New("insufficient funds")

	// ErrInvalidMerkleProof is returned by various RPCs when the host supplies
	// an invalid Merkle proof.
	ErrInvalidMerkleProof = errors.New("host supplied invalid Merkle proof")

	// ErrContractLocked is returned by the Lock RPC when the contract in
	// question is already locked by another party. This is a transient error;
	// the caller should retry later.
	ErrContractLocked = errors.New("contract is locked by another party")

	// ErrNoContractLocked is returned by RPCs that require a locked contract
	// when no contract is locked.
	ErrNoContractLocked = errors.New("no contract locked")

	// ErrContractFinalized is returned by the Lock RPC when the contract in
	// question has reached its maximum revision number, meaning the contract
	// can no longer be revised.
	ErrContractFinalized = errors.New("contract cannot be revised further")
)

Functions

func SubmitContractRevision added in v0.2.0 

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 ContractRevision added in v0.2.0 

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, []types.Transaction, 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, id types.FileContractID, key ed25519.PrivateKey, host hostdb.ScannedHost, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (ContractRevision, []types.Transaction, error)

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

func (ContractRevision) EndHeight added in v0.2.0 

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 added in v0.2.0 

func (c ContractRevision) HostKey() hostdb.HostPublicKey

HostKey returns the public key of the host.

func (ContractRevision) ID added in v0.2.0 

func (c ContractRevision) ID() types.FileContractID

ID returns the ID of the original FileContract.

func (ContractRevision) IsValid added in v0.2.0 

func (c ContractRevision) IsValid() bool

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

func (ContractRevision) NumSectors added in v0.5.0 

func (c ContractRevision) NumSectors() int

NumSectors returns the number of sectors covered by the contract.

func (ContractRevision) RenterFunds added in v0.2.0 

func (c ContractRevision) RenterFunds() types.Currency

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

type RPCStats added in v0.16.1 

type RPCStats struct {
	Host     hostdb.HostPublicKey
	Contract types.FileContractID // empty if no contract is locked
	RPC      renterhost.Specifier
	// Timestamp is the moment the RPC method was invoked; likewise, Elapsed is
	// measured at the moment the RPC method returns. Consequently, these stats
	// do *not* enable direct measurement of host throughput. However, stats may
	// be compared *across* hosts in order to rank their relative performance.
	Timestamp  time.Time
	Elapsed    time.Duration
	Err        error
	Uploaded   uint64
	Downloaded uint64
	Cost       types.Currency
}

RPCStats contains various statistics related to an RPC.

type RPCStatsRecorder added in v0.16.1 

type RPCStatsRecorder interface {
	RecordRPCStats(stats RPCStats)
}

A RPCStatsRecorder records RPCStats, as reported by a Session.

type Session added in v0.2.0 

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

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

func NewSession added in v0.2.0 

func NewSession(hostIP modules.NetAddress, hostKey hostdb.HostPublicKey, id types.FileContractID, key ed25519.PrivateKey, 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 added in v0.2.0 

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 NewUnlockedSessionFromConn added in v0.16.2 

func NewUnlockedSessionFromConn(conn net.Conn, hostKey hostdb.HostPublicKey, currentHeight types.BlockHeight) (_ *Session, err error)

NewUnlockedSessionFromConn initiates a new renter-host protocol session on top of the provided conn, without locking an associated contract or requesting the host's settings. The conn should have a deadline appropriate for the renter-host protocol handshake.

func (*Session) Append added in v0.12.0 

func (s *Session) Append(sector *[renterhost.SectorSize]byte) (crypto.Hash, error)

Append calls the Write RPC with a single action, appending the provided sector. It returns the Merkle root of the sector.

func (*Session) Close added in v0.2.0 

func (s *Session) Close() (err error)

Close gracefully terminates the session and closes the underlying connection.

func (*Session) DeleteSectors added in v0.13.0 

func (s *Session) DeleteSectors(roots []crypto.Hash) error

DeleteSectors calls the Write RPC with a set of Swap and Trim actions that delete the specified sectors.

func (*Session) FormContract added in v0.2.0 

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

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

func (*Session) HostKey added in v0.2.0 

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

HostKey returns the public key of the host.

func (*Session) IsClosed added in v0.14.4 

func (s *Session) IsClosed() bool

IsClosed returns whether the Session is closed.

func (*Session) Lock added in v0.2.0 

func (s *Session) Lock(id types.FileContractID, key ed25519.PrivateKey, timeout time.Duration) (err error)

Lock calls the Lock RPC, locking the supplied contract and synchronizing its state with the host's most recent revision. The timeout specifies how long the host should wait while attempting to acquire the lock. Note that timeouts are serialized in milliseconds, so a timeout of less than 1ms will be rounded down to 0. (A timeout of 0 is valid: it means that the lock will only be acquired if the contract is unlocked at the moment the host receives the RPC.)

Lock returns ErrContractFinalized if the contract can no longer be revised. The contract will still be available via the Revision method, but invoking other RPCs may result in errors or panics.

func (*Session) Read added in v0.2.0 

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.

Note that sector data is streamed to w before it has been validated. Callers MUST check the returned error, and discard any data written to w if the error is non-nil. Failure to do so may allow an attacker to inject malicious data.

func (*Session) RenewContract added in v0.2.0 

func (s *Session) RenewContract(w Wallet, tpool TransactionPool, renterPayout types.Currency, startHeight, endHeight types.BlockHeight) (_ ContractRevision, _ []types.Transaction, err error)

RenewContract negotiates a new file contract and initial revision for data already stored with a host. The old contract is "cleared," reverting its filesize to zero.

func (*Session) Revision added in v0.10.0 

func (s *Session) Revision() ContractRevision

Revision returns the most recent revision of the locked contract.

func (*Session) SectorRoots added in v0.2.0 

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) SetLatency added in v0.14.4 

func (s *Session) SetLatency(d time.Duration)

SetLatency sets the latency deadline for RPCs.

func (*Session) SetRPCStatsRecorder added in v0.16.1 

func (s *Session) SetRPCStatsRecorder(stats RPCStatsRecorder)

SetRPCStatsRecorder sets the RPCStatsRecorder for the Session.

func (*Session) SetReadDeadline added in v0.14.3 

func (s *Session) SetReadDeadline(d time.Duration)

SetReadDeadline sets the per-byte read deadline for RPCs. For example, to time out after 1 minute when downloading a sector, set the per-byte deadline to time.Minute / renterhost.SectorSize.

func (*Session) SetWriteDeadline added in v0.14.3 

func (s *Session) SetWriteDeadline(d time.Duration)

SetWriteDeadline sets the per-byte write deadline for RPCs. For example, to time out after 1 minute when uploading a sector, set the per-byte deadline to time.Minute / renterhost.SectorSize.

func (*Session) Settings added in v0.2.0 

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

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

func (*Session) Unlock added in v0.2.0 

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 added in v0.2.0 

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(txnSet []types.Transaction) error
	UnconfirmedParents(txn types.Transaction) ([]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 {
	// Address returns an address controlled by the wallet.
	Address() (types.UnlockHash, error)
	// FundTransaction adds inputs to txn worth at least amount, adding a change
	// output if needed. It returns the added input IDs, for use with
	// SignTransaction. It also returns a function that will "unclaim" the
	// inputs; this function must be called once the transaction has been
	// broadcast or discarded.
	FundTransaction(txn *types.Transaction, amount types.Currency) ([]crypto.Hash, func(), error)
	// SignTransaction signs the specified transaction using keys derived from the
	// wallet seed. If toSign is nil, SignTransaction will automatically add
	// TransactionSignatures for each input owned by the seed. If toSign is not nil,
	// it a list of indices of TransactionSignatures already present in txn;
	// SignTransaction will fill in the Signature field of each.
	SignTransaction(txn *types.Transaction, toSign []crypto.Hash) error
}

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.