types

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jan 15, 2021 License: Apache-2.0, MIT Imports: 33 Imported by: 0

Documentation

Overview

Package actor implements tooling to write and manipulate actors in go.

Index

Constants

View Source 
const DefaultGasCost = 100

DefaultGasCost is default gas cost for the actor calls.

View Source 
const FilecoinPrecision = uint64(1_000_000_000_000_000_000)
View Source 
const MessageVersion = 0

Variables

View Source 
var DefaultMessageSendSpec = MessageSendSpec{

	MaxFee: abi.NewTokenAmount(int64(FilecoinPrecision) / 10),
}
View Source 
var EmptyMessagesCID cid.Cid

EmptyMessagesCID is the cid of an empty collection of messages.

View Source 
var EmptyReceiptsCID cid.Cid

EmptyReceiptsCID is the cid of an empty collection of receipts.

View Source 
var EmptyTxMetaCID cid.Cid

EmptyTxMetaCID is the cid of a TxMeta wrapping empty cids

View Source 
var ErrActorNotFound = errors.New("actor not found")
View Source 
var ErrNotFound = fmt.Errorf("Not found")

ErrNotFound is not the error you are looking for.

View Source 
var ZeroAttoFIL = specsbig.Zero()

ZeroAttoFIL is the zero value for an AttoFIL, exported for consistency in construction of AttoFILs

Functions

func AssertCidsEqual 

func AssertCidsEqual(t *testing.T, m cid.Cid, n cid.Cid)

AssertCidsEqual asserts that two CIDS are identical.

func AssertHaveSameCid 

func AssertHaveSameCid(t *testing.T, m HasCid, n HasCid)

AssertHaveSameCid asserts that two values have identical CIDs.

func BigToUint64 

func BigToUint64(bi specsbig.Int) (uint64, error)

BigToUint64 converts a big Int to a uint64. It will error if the Int is too big to fit into 64 bits or is negative

func CidFromString 

func CidFromString(t *testing.T, input string) cid.Cid

CidFromString generates Cid from string input

func MsgCidsEqual 

func MsgCidsEqual(m1, m2 *UnsignedMessage) bool

MsgCidsEqual returns true if the message cids are equal. It panics if it can't get their cid.

func MustGenerateBLSKeyInfo 

func MustGenerateBLSKeyInfo(n int, seed byte) []crypto.KeyInfo

MustGenerateBLSKeyInfo produces n distinct BLS keyinfos.

func MustGenerateKeyInfo 

func MustGenerateKeyInfo(n int, seed byte) []crypto.KeyInfo

MustGenerateKeyInfo generates `n` distinct keyinfos using seed `seed`. The result is deterministic (for stable tests), don't use this for real keys!

func MustGenerateMixedKeyInfo 

func MustGenerateMixedKeyInfo(m int, n int) []crypto.KeyInfo

MustGenerateMixedKeyInfo produces m bls keys and n secp keys. BLS and Secp will be interleaved. The keys will be valid, but not deterministic.

func NewAttoTokenFromToken 

func NewAttoTokenFromToken(x uint64) abi.TokenAmount

NewAttoTokenFromToken should be moved when we cleanup the types Dragons: clean up and likely move to specs-actors

func NewCidForTestGetter 

func NewCidForTestGetter() func() cid.Cid

NewCidForTestGetter returns a closure that returns a Cid unique to that invocation. The Cid is unique wrt the closure returned, not globally. You can use this function in tests.

func NewForTestGetter 

func NewForTestGetter() func() address.Address

NewForTestGetter returns a closure that returns an address unique to that invocation. The address is unique wrt the closure returned, not globally.

func NewMessageForTestGetter 

func NewMessageForTestGetter() func() *UnsignedMessage

NewMessageForTestGetter returns a closure that returns a message unique to that invocation. The message is unique wrt the closure returned, not globally. You can use this function in tests instead of manually creating messages -- it both reduces duplication and gives us exactly one place to create valid messages for tests if messages require validation in the future.

func NewSignedMessageForTestGetter 

func NewSignedMessageForTestGetter(ms MockSigner) func(uint64) *SignedMessage

NewSignedMessageForTestGetter returns a closure that returns a SignedMessage unique to that invocation. The message is unique wrt the closure returned, not globally. You can use this function in tests instead of manually creating messages -- it both reduces duplication and gives us exactly one place to create valid messages for tests if messages require validation in the future. TODO support chosing from address

func RequireIDAddress 

func RequireIDAddress(t *testing.T, i int) address.Address

func SmsgCidsEqual 

func SmsgCidsEqual(m1, m2 ChainMsg) bool

SmsgCidsEqual returns true if the SignedMessage cids are equal. It panics if it can't get their cid.

func Uint64ToBig 

func Uint64ToBig(u uint64) specsbig.Int

Uint64ToBig converts a uint64 to a big Int. Precodition: don't overflow int64.

Types

type Actor 

type Actor struct {
	// Code is a CID of the VM code for this actor's implementation (or a constant for actors implemented in Go code).
	// Code may be nil for an uninitialized actor (which exists because it has received a balance).
	Code cid.Cid
	// Head is the CID of the root of the actor's state tree.
	Head cid.Cid
	// Nonce is the number expected on the next message from this actor.
	// Messages are processed in strict, contiguous order.
	Nonce uint64
	// Balance is the amount of attoFIL in the actor's account.
	Balance abi.TokenAmount
}

Actor is the central abstraction of entities in the system.

Both individual accounts, as well as contracts (user & system level) are represented as actors. An actor has the following core functionality implemented on a system level: - track a Filecoin balance, using the `Balance` field - execute code stored in the `Code` field - read & write memory - replay protection, using the `Nonce` field

Value sent to a non-existent address will be tracked as an empty actor that has a Balance but nil Code and Memory. You must nil check Code cids before comparing them.

More specific capabilities for individual accounts or contract specific must be implemented inside the code.

Not safe for concurrent access.

func NewActor 

func NewActor(code cid.Cid, balance abi.TokenAmount, head cid.Cid) *Actor

NewActor constructs a new actor.

func (*Actor) Empty 

func (a *Actor) Empty() bool

Empty tests whether the actor's code is defined.

func (*Actor) IncrementSeqNum 

func (a *Actor) IncrementSeqNum()

IncrementSeqNum increments the seq number.

func (*Actor) MarshalCBOR 

func (t *Actor) MarshalCBOR(w io.Writer) error

func (*Actor) UnmarshalCBOR 

func (t *Actor) UnmarshalCBOR(r io.Reader) error

type AttoFIL 

type AttoFIL = specsabi.TokenAmount

AttoFIL represents a signed multi-precision integer quantity of attofilecoin (atto is metric for 10**-18). The zero value for AttoFIL represents the value 0.

Reasons for embedding a big.Int instead of *big.Int:

  • We don't have check for nil in every method that does calculations.
  • Serialization "symmetry" when serializing AttoFIL{}.

func FromFil 

func FromFil(i uint64) AttoFIL

func NewAttoFIL 

func NewAttoFIL(x *big.Int) AttoFIL

NewAttoFIL allocates and returns a new AttoFIL set to x.

func NewAttoFILFromBytes 

func NewAttoFILFromBytes(buf []byte) (AttoFIL, error)

NewAttoFILFromBytes allocates and returns a new AttoFIL set to the value of buf as the bytes of a big-endian unsigned integer.

func NewAttoFILFromFIL 

func NewAttoFILFromFIL(x uint64) AttoFIL

NewAttoFILFromFIL returns a new AttoFIL representing a quantity of attofilecoin equal to x filecoin.

func NewAttoFILFromFILString 

func NewAttoFILFromFILString(s string) (AttoFIL, bool)

NewAttoFILFromFILString allocates a new AttoFIL set to the value of s filecoin, interpreted as a decimal in base 10, and returns it and a boolean indicating success.

func NewAttoFILFromString 

func NewAttoFILFromString(s string, base int) (AttoFIL, bool)

NewAttoFILFromString allocates a new AttoFIL set to the value of s attofilecoin, interpreted in the given base, and returns it and a boolean indicating success.

func NewGasFeeCap 

func NewGasFeeCap(price int64) AttoFIL

func NewGasPremium 

func NewGasPremium(price int64) AttoFIL

type ChainMsg 

type ChainMsg interface {
	Cid() (cid.Cid, error)
	VMMessage() *UnsignedMessage
	ToStorageBlock() (blocks.Block, error)
	// FIXME: This is the *message* length, this name is misleading.
	ChainLength() int
	cbor2.Marshaler
	cbor2.Unmarshaler
}

type ExecutionTrace 

type ExecutionTrace struct {
	Msg        *UnsignedMessage
	MsgRct     *MessageReceipt
	Error      string
	Duration   time.Duration
	GasCharges []*GasTrace

	Subcalls []ExecutionTrace
}

type FIL 

type FIL big2.Int

func MustParseFIL 

func MustParseFIL(s string) FIL

func ParseFIL 

func ParseFIL(s string) (FIL, error)

func (FIL) Format 

func (f FIL) Format(s fmt.State, ch rune)

func (FIL) MarshalText 

func (f FIL) MarshalText() (text []byte, err error)

func (FIL) Short 

func (f FIL) Short() string

func (FIL) String 

func (f FIL) String() string

func (FIL) Unitless 

func (f FIL) Unitless() string

func (FIL) UnmarshalText 

func (f FIL) UnmarshalText(text []byte) error

type GasTrace 

type GasTrace struct {
	Name string

	Location          []Loc `json:"loc"`
	TotalGas          int64 `json:"tg"`
	ComputeGas        int64 `json:"cg"`
	StorageGas        int64 `json:"sg"`
	TotalVirtualGas   int64 `json:"vtg"`
	VirtualComputeGas int64 `json:"vcg"`
	VirtualStorageGas int64 `json:"vsg"`

	TimeTaken time.Duration `json:"tt"`
	Extra     interface{}   `json:"ex,omitempty"`

	Callers []uintptr `json:"-"`
}

func (*GasTrace) MarshalJSON 

func (gt *GasTrace) MarshalJSON() ([]byte, error)

type HasCid 

type HasCid interface {
	Cid() cid.Cid
}

HasCid allows two values with CIDs to be compared.

type Loc 

type Loc struct {
	File     string
	Line     int
	Function string
}

func (Loc) Important 

func (l Loc) Important() bool

func (Loc) Show 

func (l Loc) Show() bool

func (Loc) String 

func (l Loc) String() string

type MessageMaker 

type MessageMaker struct {
	DefaultGasFeeCap  AttoFIL
	DefaultGasPremium AttoFIL
	DefaultGasUnits   int64
	// contains filtered or unexported fields
}

MessageMaker creates unique, signed messages for use in tests.

func NewMessageMaker 

func NewMessageMaker(t *testing.T, keys []crypto.KeyInfo) *MessageMaker

NewMessageMaker creates a new message maker with a set of signing keys.

func (*MessageMaker) Addresses 

func (mm *MessageMaker) Addresses() []address.Address

Addresses returns the addresses for which this maker can sign messages.

func (*MessageMaker) NewSignedMessage 

func (mm *MessageMaker) NewSignedMessage(from address.Address, nonce uint64) *SignedMessage

NewSignedMessage creates a new signed message.

func (*MessageMaker) NewUnsignedMessage 

func (mm *MessageMaker) NewUnsignedMessage(from address.Address, nonce uint64) *UnsignedMessage

NewUnsignedMessage creates a new message.

func (*MessageMaker) Signer 

func (mm *MessageMaker) Signer() *MockSigner

Signer returns the signer with which this maker signs messages.

type MessageReceipt 

type MessageReceipt struct {
	ExitCode    exitcode.ExitCode `json:"exitCode"`
	ReturnValue []byte            `json:"return"`
	GasUsed     int64             `json:"gasUsed"`
}

MessageReceipt is what is returned by executing a message on the vm.

func EmptyReceipts 

func EmptyReceipts(n int) []*MessageReceipt

EmptyReceipts returns a slice of n empty receipts.

func Failure 

func Failure(exitCode exitcode.ExitCode, gasAmount int64) MessageReceipt

Failure returns with a non-zero exit code.

func (*MessageReceipt) MarshalCBOR 

func (t *MessageReceipt) MarshalCBOR(w io.Writer) error

func (*MessageReceipt) String 

func (r *MessageReceipt) String() string

func (*MessageReceipt) UnmarshalCBOR 

func (t *MessageReceipt) UnmarshalCBOR(r io.Reader) error

type MessageSendSpec 

type MessageSendSpec struct {
	MaxFee abi.TokenAmount
}

func (*MessageSendSpec) Get 

func (ms *MessageSendSpec) Get() MessageSendSpec

type MockSigner 

type MockSigner struct {
	AddrKeyInfo map[address.Address]crypto.KeyInfo
	Addresses   []address.Address
	PubKeys     [][]byte
}

MockSigner implements the Signer interface

func NewMockSigner 

func NewMockSigner(kis []crypto.KeyInfo) MockSigner

NewMockSigner returns a new mock signer, capable of signing data with keys (addresses derived from) in keyinfo

func NewMockSignersAndKeyInfo 

func NewMockSignersAndKeyInfo(numSigners int) (MockSigner, []crypto.KeyInfo)

NewMockSignersAndKeyInfo is a convenience function to generate a mock signers with some keys.

func (MockSigner) GetAddressForPubKey 

func (ms MockSigner) GetAddressForPubKey(pk []byte) (address.Address, error)

GetAddressForPubKey looks up a KeyInfo address associated with a given PublicKeyForSecpSecretKey for a MockSigner

func (MockSigner) HasAddress 

func (ms MockSigner) HasAddress(_ context.Context, addr address.Address) (bool, error)

HasAddress returns whether the signer can sign with this address

func (MockSigner) SignBytes 

func (ms MockSigner) SignBytes(_ context.Context, data []byte, addr address.Address) (*crypto.Signature, error)

SignBytes cryptographically signs `data` using the `addr`.

type ReceiptMaker 

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

ReceiptMaker generates unique receipts

func NewReceiptMaker 

func NewReceiptMaker() *ReceiptMaker

NewReceiptMaker creates a new receipt maker

func (*ReceiptMaker) NewReceipt 

func (rm *ReceiptMaker) NewReceipt() MessageReceipt

NewReceipt creates a new distinct receipt.

type SignedMessage 

type SignedMessage struct {
	Message   UnsignedMessage  `json:"message"`
	Signature crypto.Signature `json:"signature"`
}

SignedMessage contains a message and its signature TODO do not export these fields as it increases the chances of producing a `SignedMessage` with an empty signature.

func NewSignedMessage 

func NewSignedMessage(ctx context.Context, msg UnsignedMessage, s Signer) (*SignedMessage, error)

NewSignedMessage accepts a message `msg` and a signer `s`. NewSignedMessage returns a `SignedMessage` containing a signature derived from the serialized `msg` and `msg.From` NOTE: this method can only sign message with From being a public-key type address, not an ID address. We should deprecate this and move to more explicit signing via an address resolver.

func NewSignedMsgs 

func NewSignedMsgs(n uint, ms MockSigner) []*SignedMessage

NewSignedMsgs returns n signed messages. The messages returned are unique to this invocation but are not unique globally (ie, a second call to NewSignedMsgs will return the same set of messages).

func SignMsgs 

func SignMsgs(ms MockSigner, msgs []*UnsignedMessage) ([]*SignedMessage, error)

SignMsgs returns a slice of signed messages where the original messages are `msgs`, if signing one of the `msgs` fails an error is returned

func (*SignedMessage) ChainLength 

func (smsg *SignedMessage) ChainLength() int

func (*SignedMessage) Cid 

func (smsg *SignedMessage) Cid() (cid.Cid, error)

Cid returns the canonical CID for the SignedMessage.

func (*SignedMessage) Equals 

func (smsg *SignedMessage) Equals(other *SignedMessage) bool

Equals tests whether two signed messages are equal.

func (*SignedMessage) MarshalCBOR 

func (t *SignedMessage) MarshalCBOR(w io.Writer) error

func (*SignedMessage) Serialize 

func (sm *SignedMessage) Serialize() ([]byte, error)

func (*SignedMessage) String 

func (smsg *SignedMessage) String() string

func (*SignedMessage) ToNode 

func (smsg *SignedMessage) ToNode() (ipld.Node, error)

ToNode converts the SignedMessage to an IPLD node.

func (*SignedMessage) ToStorageBlock 

func (smsg *SignedMessage) ToStorageBlock() (blocks.Block, error)

func (*SignedMessage) UnmarshalCBOR 

func (t *SignedMessage) UnmarshalCBOR(r io.Reader) error

func (*SignedMessage) VMMessage 

func (smsg *SignedMessage) VMMessage() *UnsignedMessage

type Signer 

type Signer interface {
	SignBytes(ctx context.Context, data []byte, addr address.Address) (*crypto.Signature, error)
	HasAddress(ctx context.Context, addr address.Address) (bool, error)
}

Signer signs data with a private key obtained internally from a provided address.

type TxMeta 

type TxMeta struct {
	BLSRoot  cid.Cid `json:"blsRoot"`
	SecpRoot cid.Cid `json:"secpRoot"`
}

TxMeta tracks the merkleroots of both secp and bls messages separately

func (*TxMeta) Cid 

func (m *TxMeta) Cid() cid.Cid

func (*TxMeta) MarshalCBOR 

func (t *TxMeta) MarshalCBOR(w io.Writer) error

func (TxMeta) String 

func (m TxMeta) String() string

String returns a readable printing string of TxMeta

func (*TxMeta) ToStorageBlock 

func (m *TxMeta) ToStorageBlock() (block.Block, error)

func (*TxMeta) UnmarshalCBOR 

func (t *TxMeta) UnmarshalCBOR(r io.Reader) error

type UnsignedMessage 

type UnsignedMessage struct {
	Version uint64 `json:"version"`

	To   address.Address `json:"to"`
	From address.Address `json:"from"`
	// When receiving a message from a user account the nonce in
	// the message must match the expected nonce in the from actor.
	// This prevents replay attacks.
	Nonce uint64 `json:"nonce"`

	Value AttoFIL `json:"value"`

	GasLimit   int64   `json:"gasLimit"`
	GasFeeCap  AttoFIL `json:"gasFeeCap"`
	GasPremium AttoFIL `json:"gasPremium"`

	Method abi.MethodNum `json:"method"`
	Params []byte        `json:"params"`
}

UnsignedMessage is an exchange of information between two actors modeled as a function call.

func DecodeMessage 

func DecodeMessage(b []byte) (*UnsignedMessage, error)

func NewMeteredMessage 

func NewMeteredMessage(from, to address.Address, nonce uint64, value AttoFIL, method abi.MethodNum, params []byte, gasFeeCap, gasPremium AttoFIL, limit int64) *UnsignedMessage

NewMeteredMessage adds gas price and gas limit to the message

func NewMsgs 

func NewMsgs(n int) []*UnsignedMessage

NewMsgs returns n messages. The messages returned are unique to this invocation but are not unique globally (ie, a second call to NewMsgs will return the same set of messages).

func NewMsgsWithAddrs 

func NewMsgsWithAddrs(n int, a []address.Address) []*UnsignedMessage

NewMsgsWithAddrs returns a slice of `n` messages who's `From` field's are pulled from `a`. This method should be used when the addresses returned are to be signed at a later point.

func NewUnsignedMessage 

func NewUnsignedMessage(from, to address.Address, nonce uint64, value AttoFIL, method abi.MethodNum, params []byte) *UnsignedMessage

NewUnsignedMessage creates a new message.

func (*UnsignedMessage) ChainLength 

func (msg *UnsignedMessage) ChainLength() int

func (*UnsignedMessage) Cid 

func (msg *UnsignedMessage) Cid() (cid.Cid, error)

Cid returns the canonical CID for the message. TODO: can we avoid returning an error?

func (*UnsignedMessage) Equals 

func (msg *UnsignedMessage) Equals(other *UnsignedMessage) bool

Equals tests whether two messages are equal

func (*UnsignedMessage) MarshalCBOR 

func (t *UnsignedMessage) MarshalCBOR(w io.Writer) error

func (*UnsignedMessage) RequiredFunds 

func (msg *UnsignedMessage) RequiredFunds() tbig.Int

func (*UnsignedMessage) String 

func (msg *UnsignedMessage) String() string

func (*UnsignedMessage) ToNode 

func (msg *UnsignedMessage) ToNode() (ipld.Node, error)

ToNode converts the Message to an IPLD node.

func (*UnsignedMessage) ToStorageBlock 

func (msg *UnsignedMessage) ToStorageBlock() (blocks.Block, error)

func (*UnsignedMessage) UnmarshalCBOR 

func (t *UnsignedMessage) UnmarshalCBOR(r io.Reader) error

func (*UnsignedMessage) VMMessage 

func (msg *UnsignedMessage) VMMessage() *UnsignedMessage

func (*UnsignedMessage) ValidForBlockInclusion 

func (msg *UnsignedMessage) ValidForBlockInclusion(minGas int64, version network.Version) error

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.