mdm

Documentation

Index

• Constants
• Variables
• func AppendCost(pt modules.RPCPriceTable) (types.Currency, types.Currency)
• func AppendMemory() uint64
• func CopyCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency
• func HasSectorCost(pt modules.RPCPriceTable) (types.Currency, types.Currency)
• func HasSectorMemory() uint64
• func InitCost(pt modules.RPCPriceTable, programLen uint64) types.Currency
• func MemoryCost(pt modules.RPCPriceTable, usedMemory, time uint64) types.Currency
• func NewAppendInstruction(dataOffset uint64, merkleProof bool) modules.Instruction
• func NewHasSectorInstruction(merkleRootOffset uint64) modules.Instruction
• func NewReadSectorInstruction(lengthOffset, offsetOffset, merkleRootOffset uint64, merkleProof bool) modules.Instruction
• func ReadCost(pt modules.RPCPriceTable, readLength uint64) (types.Currency, types.Currency)
• func ReadMemory() uint64
• func SwapCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency
• func TruncateCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency
• func WriteCost(pt modules.RPCPriceTable, writeLength uint64) (types.Currency, types.Currency)
• type Host
• type MDM
  • func New(h Host) *MDM
  • func (mdm *MDM) ExecuteProgram(ctx context.Context, pt modules.RPCPriceTable, ...) (func() error, <-chan Output, error)
  • func (mdm *MDM) Stop() error
• type Output
• type Program
• type StorageObligation

Constants

const (
	// ProgramInitTime is the time it takes to execute a program. This is a
	// hardcoded value which is meant to be replaced in the future.
	// TODO: The time is hardcoded to 10 for now until we add time management in the
	// future.
	ProgramInitTime = 10

	// TimeAppend is the time for executing an 'Append' instruction.
	TimeAppend = 10000

	// TimeCommit is the time used for executing managedFinalize.
	TimeCommit = 50e3

	// TimeHasSector is the time for executing a 'HasSector' instruction.
	TimeHasSector = 1

	// TimeReadSector is the time for executing a 'ReadSector' instruction.
	TimeReadSector = 1000

	// TimeWriteSector is the time for executing a 'WriteSector' instruction.
	TimeWriteSector = 10000
)

The following constants defines the time modifiers used for memory price calculations in the MDM.

Variables

var ErrInsufficientBudget = errors.New("remaining budget is insufficient")

ErrInsufficientBudget is the error returned if the remaining budget of a program is not sufficient to execute the next instruction.

var (
	// ErrInterrupted indicates that the program was interrupted during
	// execution and couldn't finish.
	ErrInterrupted = errors.New("execution of program was interrupted")
)

Functions

func AppendCost

func AppendCost(pt modules.RPCPriceTable) (types.Currency, types.Currency)

AppendCost is the cost of executing an 'Append' instruction.

func AppendMemory

func AppendMemory() uint64

AppendMemory returns the additional memory consumption of a 'Append' instruction.

func CopyCost

func CopyCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency

CopyCost is the cost of executing a 'Copy' instruction.

func HasSectorCost

func HasSectorCost(pt modules.RPCPriceTable) (types.Currency, types.Currency)

HasSectorCost is the cost of executing a 'HasSector' instruction.

func HasSectorMemory

func HasSectorMemory() uint64

HasSectorMemory returns the additional memory consumption of a 'HasSector' instruction.

func InitCost

func InitCost(pt modules.RPCPriceTable, programLen uint64) types.Currency

InitCost is the cost of instantiatine the MDM. It is defined as: 'InitBaseCost' + 'MemoryTimeCost' * 'programLen' * Time

func MemoryCost

func MemoryCost(pt modules.RPCPriceTable, usedMemory, time uint64) types.Currency

MemoryCost computes the memory cost given a price table, memory and time.

func NewAppendInstruction

func NewAppendInstruction(dataOffset uint64, merkleProof bool) modules.Instruction

NewAppendInstruction creates a modules.Instruction from arguments.

func NewHasSectorInstruction

func NewHasSectorInstruction(merkleRootOffset uint64) modules.Instruction

NewHasSectorInstruction creates a modules.Instruction from arguments.

func NewReadSectorInstruction

func NewReadSectorInstruction(lengthOffset, offsetOffset, merkleRootOffset uint64, merkleProof bool) modules.Instruction

NewReadSectorInstruction creates a modules.Instruction from arguments.

func ReadCost

func ReadCost(pt modules.RPCPriceTable, readLength uint64) (types.Currency, types.Currency)

ReadCost is the cost of executing a 'Read' instruction. It is defined as: 'readBaseCost' + 'readLengthCost' * `readLength`

func ReadMemory

func ReadMemory() uint64

ReadMemory returns the additional memory consumption of a 'Read' instruction.

func SwapCost

func SwapCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency

SwapCost is the cost of executing a 'Swap' instruction.

func TruncateCost

func TruncateCost(pt modules.RPCPriceTable, contractSize uint64) types.Currency

TruncateCost is the cost of executing a 'Truncate' instruction.

func WriteCost

func WriteCost(pt modules.RPCPriceTable, writeLength uint64) (types.Currency, types.Currency)

WriteCost is the cost of executing a 'Write' instruction of a certain length.

Types

type Host

type Host interface {
	BlockHeight() types.BlockHeight
	HasSector(crypto.Hash) (bool, error)
	ReadSector(sectorRoot crypto.Hash) ([]byte, error)
}

Host defines the minimal interface a Host needs to implement to be used by the mdm.

type MDM

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

MDM (Merklized Data Machine) is a virtual machine that executes instructions on the data in a I3v file contract. The file contract tracks the size and Merkle root of the underlying data, which the MDM will update when running instructions that modify the file contract data. Each instruction can optionally produce a cryptographic proof that the instruction was executed honestly. Every instruction has an execution cost, and instructions are batched into atomic sets called 'programs' that are either entirely applied or are not applied at all.

func New

func New(h Host) *MDM

New creates a new MDM.

func (*MDM) ExecuteProgram

func (mdm *MDM) ExecuteProgram(ctx context.Context, pt modules.RPCPriceTable, instructions []modules.Instruction, budget types.Currency, so StorageObligation, programDataLen uint64, data io.Reader) (func() error, <-chan Output, error)

ExecuteProgram initializes a new program from a set of instructions and a reader which can be used to fetch the program's data and executes it.

func (*MDM) Stop

func (mdm *MDM) Stop() error

Stop will stop the MDM and wait for all of the spawned programs to stop executing while also preventing new programs from being started.

type Output

type Output struct {
	ExecutionCost   types.Currency
	PotentialRefund types.Currency
	// contains filtered or unexported fields
}

Output is the type of the outputs returned by a program run on the MDM.

type Program

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

Program is a collection of instructions. Within a program, each instruction will potentially modify the size and merkle root of a file contract. After the final instruction is executed, the MDM will create an updated revision of the FileContract which has to be signed by the renter and the host.

type StorageObligation

type StorageObligation interface {
	// ContractSize returns the current contract size of the storage obligation.
	ContractSize() uint64
	// Locked returns whether or not the storage obligation is locked.
	Locked() bool
	// MerkleRoot returns the filecontract's current root.
	MerkleRoot() crypto.Hash
	// SectorRoots returns the roots of the storage obligation.
	SectorRoots() []crypto.Hash
	// Update updates the storage obligation.
	Update(sectorRoots, sectorsRemoved []crypto.Hash, sectorsGained map[crypto.Hash][]byte) error
}

StorageObligation defines the minimal interface a StorageObligation needs to implement to be used by the mdm.