emulator

package
v0.50.0 Latest Latest
Warning

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

 Go to latest Published: Jun 2, 2023 License: Apache-2.0 Imports: 34 Imported by: 16

Documentation

Overview

Package emulator provides an emulated version of the Flow emulator that can be used for development purposes.

This package can be used as a library or as a standalone application.

When used as a library, this package provides tools to write programmatic tests for Flow applications.

When used as a standalone application, this package implements the Flow Access API and is fully-compatible with Flow gRPC client libraries.

Index

Constants

View Source 
const DefaultServiceKeyHashAlgo = sdkcrypto.SHA3_256
View Source 
const DefaultServiceKeySigAlgo = sdkcrypto.ECDSA_P256
View Source 
const MaxViewIncrease = 3

MaxViewIncrease represents the largest difference in view number between two consecutive blocks. The minimum view increment is 1.

Variables

View Source 
var CommonContracts = func() []ContractDescription {
	chain := flowgo.Emulator.Chain()
	ftAddress := flowsdk.HexToAddress(fvm.FungibleTokenAddress(chain).HexWithPrefix())
	serviceAddress := flowsdk.HexToAddress(chain.ServiceAddress().HexWithPrefix())

	return []ContractDescription{
		{
			Name:        "FUSD",
			Address:     serviceAddress,
			Description: "💵  FUSD contract",
			Source:      fusd.FUSD(ftAddress.String()),
		},
		{
			Name:        "NonFungibleToken",
			Address:     serviceAddress,
			Description: "✨  NFT contract",
			Source:      contracts.NonFungibleToken(),
		},
		{
			Name:        "MetadataViews",
			Address:     serviceAddress,
			Description: "✨  Metadata views contract",
			Source:      contracts.MetadataViews(ftAddress, serviceAddress),
		},
		{
			Name:        "ExampleNFT",
			Address:     serviceAddress,
			Description: "✨  Example NFT contract",
			Source:      contracts.ExampleNFT(serviceAddress, serviceAddress),
		},
		{
			Name:        "NFTStorefrontV2",
			Address:     serviceAddress,
			Description: "✨  NFT Storefront contract v2",
			Source:      nftstorefront.NFTStorefront(2, ftAddress.String(), serviceAddress.String()),
		},
		{
			Name:        "NFTStorefront",
			Address:     serviceAddress,
			Description: "✨  NFT Storefront contract",
			Source:      nftstorefront.NFTStorefront(1, ftAddress.String(), serviceAddress.String()),
		},
	}
}()

Functions

func DeployContracts 

func DeployContracts(b *Blockchain, deployments []ContractDescription) error

Types

type AccessProvider 

type AccessProvider interface {
	Ping() error
	GetNetworkParameters() access.NetworkParameters

	GetLatestBlock() (*flowgo.Block, error)
	GetBlockByID(id flowgo.Identifier) (*flowgo.Block, error)
	GetBlockByHeight(height uint64) (*flowgo.Block, error)

	GetCollectionByID(colID flowgo.Identifier) (*flowgo.LightCollection, error)

	GetTransaction(txID flowgo.Identifier) (*flowgo.TransactionBody, error)
	GetTransactionResult(txID flowgo.Identifier) (*access.TransactionResult, error)
	GetTransactionsByBlockID(blockID flowgo.Identifier) ([]*flowgo.TransactionBody, error)
	GetTransactionResultsByBlockID(blockID flowgo.Identifier) ([]*access.TransactionResult, error)

	GetAccount(address flowgo.Address) (*flowgo.Account, error)
	GetAccountAtBlockHeight(address flowgo.Address, blockHeight uint64) (*flowgo.Account, error)
	GetAccountByIndex(uint) (*flowgo.Account, error)

	GetEventsByHeight(blockHeight uint64, eventType string) ([]flowgo.Event, error)
	GetEventsForBlockIDs(eventType string, blockIDs []flowgo.Identifier) ([]flowgo.BlockEvents, error)
	GetEventsForHeightRange(eventType string, startHeight, endHeight uint64) ([]flowgo.BlockEvents, error)

	ExecuteScript(script []byte, arguments [][]byte) (*types.ScriptResult, error)
	ExecuteScriptAtBlockHeight(script []byte, arguments [][]byte, blockHeight uint64) (*types.ScriptResult, error)
	ExecuteScriptAtBlockID(script []byte, arguments [][]byte, id flowgo.Identifier) (*types.ScriptResult, error)

	GetAccountStorage(address flowgo.Address) (*types.AccountStorage, error)

	SendTransaction(tx *flowgo.TransactionBody) error
	AddTransaction(tx flowgo.TransactionBody) error
}

type AutoMineCapable 

type AutoMineCapable interface {
	EnableAutoMine()
	DisableAutoMine()
}

type Blockchain 

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

Blockchain emulates the functionality of the Flow emulator.

func New 

func New(opts ...Option) (*Blockchain, error)

New instantiates a new emulated emulator with the provided options.

func (*Blockchain) AddTransaction 

func (b *Blockchain) AddTransaction(tx flowgo.TransactionBody) error

AddTransaction validates a transaction and adds it to the current pending block.

func (*Blockchain) CommitBlock 

func (b *Blockchain) CommitBlock() (*flowgo.Block, error)

CommitBlock seals the current pending block and saves it to storage.

This function clears the pending transaction pool and resets the pending block.

func (*Blockchain) CoverageReport 

func (b *Blockchain) CoverageReport() *runtime.CoverageReport

func (*Blockchain) CreateSnapshot 

func (b *Blockchain) CreateSnapshot(name string) error

func (*Blockchain) CurrentScript 

func (b *Blockchain) CurrentScript() (string, string)

func (*Blockchain) DisableAutoMine 

func (b *Blockchain) DisableAutoMine()

func (*Blockchain) EnableAutoMine 

func (b *Blockchain) EnableAutoMine()

func (*Blockchain) EndDebugging 

func (b *Blockchain) EndDebugging()

func (*Blockchain) ExecuteAndCommitBlock 

func (b *Blockchain) ExecuteAndCommitBlock() (*flowgo.Block, []*types.TransactionResult, error)

ExecuteAndCommitBlock is a utility that combines ExecuteBlock with CommitBlock.

func (*Blockchain) ExecuteBlock 

func (b *Blockchain) ExecuteBlock() ([]*types.TransactionResult, error)

ExecuteBlock executes the remaining transactions in pending block.

func (*Blockchain) ExecuteNextTransaction 

func (b *Blockchain) ExecuteNextTransaction() (*types.TransactionResult, error)

ExecuteNextTransaction executes the next indexed transaction in pending block.

func (*Blockchain) ExecuteScript 

func (b *Blockchain) ExecuteScript(
	script []byte,
	arguments [][]byte,
) (*types.ScriptResult, error)

ExecuteScript executes a read-only script against the world state and returns the result.

func (*Blockchain) ExecuteScriptAtBlockHeight 

func (b *Blockchain) ExecuteScriptAtBlockHeight(
	script []byte,
	arguments [][]byte,
	blockHeight uint64,
) (*types.ScriptResult, error)

func (*Blockchain) ExecuteScriptAtBlockID 

func (b *Blockchain) ExecuteScriptAtBlockID(script []byte, arguments [][]byte, id flowgo.Identifier) (*types.ScriptResult, error)

func (*Blockchain) GetAccount 

func (b *Blockchain) GetAccount(address flowgo.Address) (*flowgo.Account, error)

GetAccount returns the account for the given address.

func (*Blockchain) GetAccountAtBlockHeight 

func (b *Blockchain) GetAccountAtBlockHeight(address flowgo.Address, blockHeight uint64) (*flowgo.Account, error)

GetAccountAtBlockHeight returns the account for the given address at specified block height.

func (*Blockchain) GetAccountByIndex 

func (b *Blockchain) GetAccountByIndex(index uint) (*flowgo.Account, error)

GetAccountByIndex returns the account for the given address.

func (*Blockchain) GetAccountStorage 

func (b *Blockchain) GetAccountStorage(
	address flowgo.Address,
) (
	*types.AccountStorage,
	error,
)

func (*Blockchain) GetAccountUnsafe deprecated 

func (b *Blockchain) GetAccountUnsafe(address flowgo.Address) (*flowgo.Account, error)

Deprecated: Needed for the debugger right now, do NOT use for other purposes. TODO: refactor

func (*Blockchain) GetBlockByHeight 

func (b *Blockchain) GetBlockByHeight(height uint64) (*flowgo.Block, error)

GetBlockByHeight gets a block by height.

func (*Blockchain) GetBlockByID 

func (b *Blockchain) GetBlockByID(id flowgo.Identifier) (*flowgo.Block, error)

GetBlockByID gets a block by ID.

func (*Blockchain) GetChain 

func (b *Blockchain) GetChain() flowgo.Chain

func (*Blockchain) GetCollectionByID 

func (b *Blockchain) GetCollectionByID(colID flowgo.Identifier) (*flowgo.LightCollection, error)

func (*Blockchain) GetEventsByHeight 

func (b *Blockchain) GetEventsByHeight(blockHeight uint64, eventType string) ([]flowgo.Event, error)

GetEventsByHeight returns the events in the block at the given height, optionally filtered by type.

func (*Blockchain) GetEventsForBlockIDs 

func (b *Blockchain) GetEventsForBlockIDs(eventType string, blockIDs []flowgo.Identifier) (result []flowgo.BlockEvents, err error)

func (*Blockchain) GetEventsForHeightRange 

func (b *Blockchain) GetEventsForHeightRange(eventType string, startHeight, endHeight uint64) (result []flowgo.BlockEvents, err error)

func (*Blockchain) GetLatestBlock 

func (b *Blockchain) GetLatestBlock() (*flowgo.Block, error)

GetLatestBlock gets the latest sealed block.

func (*Blockchain) GetNetworkParameters 

func (b *Blockchain) GetNetworkParameters() access.NetworkParameters

func (*Blockchain) GetTransaction 

func (b *Blockchain) GetTransaction(txID flowgo.Identifier) (*flowgo.TransactionBody, error)

GetTransaction gets an existing transaction by ID.

The function first looks in the pending block, then the current emulator state.

func (*Blockchain) GetTransactionResult 

func (b *Blockchain) GetTransactionResult(txID flowgo.Identifier) (*access.TransactionResult, error)

func (*Blockchain) GetTransactionResultsByBlockID 

func (b *Blockchain) GetTransactionResultsByBlockID(blockID flowgo.Identifier) ([]*access.TransactionResult, error)

func (*Blockchain) GetTransactionsByBlockID 

func (b *Blockchain) GetTransactionsByBlockID(blockID flowgo.Identifier) ([]*flowgo.TransactionBody, error)

func (*Blockchain) LoadSnapshot 

func (b *Blockchain) LoadSnapshot(name string) error

func (*Blockchain) PendingBlockID 

func (b *Blockchain) PendingBlockID() flowgo.Identifier

PendingBlockID returns the ID of the pending block.

func (*Blockchain) PendingBlockTimestamp 

func (b *Blockchain) PendingBlockTimestamp() time.Time

PendingBlockTimestamp returns the Timestamp of the pending block.

func (*Blockchain) PendingBlockView 

func (b *Blockchain) PendingBlockView() uint64

PendingBlockView returns the view of the pending block.

func (*Blockchain) Ping 

func (b *Blockchain) Ping() error

func (*Blockchain) ReloadBlockchain 

func (b *Blockchain) ReloadBlockchain() error

func (*Blockchain) ResetCoverageReport 

func (b *Blockchain) ResetCoverageReport()

func (*Blockchain) ResetPendingBlock 

func (b *Blockchain) ResetPendingBlock() error

ResetPendingBlock clears the transactions in pending block.

func (*Blockchain) RollbackToBlockHeight 

func (b *Blockchain) RollbackToBlockHeight(height uint64) error

func (*Blockchain) SendTransaction 

func (b *Blockchain) SendTransaction(flowTx *flowgo.TransactionBody) error

SendTransaction submits a transaction to the network.

func (*Blockchain) ServiceKey 

func (b *Blockchain) ServiceKey() ServiceKey

ServiceKey returns the service private key for this emulator.

func (*Blockchain) Snapshots 

func (b *Blockchain) Snapshots() ([]string, error)

func (*Blockchain) StartDebugger 

func (b *Blockchain) StartDebugger() *interpreter.Debugger

type BlocksTicker 

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

func NewBlocksTicker 

func NewBlocksTicker(
	emulator Emulator,
	blockTime time.Duration,
) *BlocksTicker

func (*BlocksTicker) Start 

func (t *BlocksTicker) Start() error

func (*BlocksTicker) Stop 

func (t *BlocksTicker) Stop()

type CadenceHook 

type CadenceHook struct {
	MainLogger *zerolog.Logger
}

func (CadenceHook) Run 

func (h CadenceHook) Run(_ *zerolog.Event, level zerolog.Level, msg string)

type ContractDescription 

type ContractDescription struct {
	Name        string
	Address     flowsdk.Address
	Description string
	Source      []byte
}

type CoverageReportCapable 

type CoverageReportCapable interface {
	CoverageReport() *runtime.CoverageReport
	ResetCoverageReport()
}

type DebuggingCapable 

type DebuggingCapable interface {
	StartDebugger() *interpreter.Debugger
	EndDebugging()
	// Deprecated: Needed for the debugger right now, do NOT use for other purposes.
	// TODO: refactor
	GetAccountUnsafe(address flowgo.Address) (*flowgo.Account, error)
}

type Emulator 

type Emulator interface {
	ServiceKey() ServiceKey

	AccessProvider

	CoverageReportCapable
	DebuggingCapable
	SnapshotCapable
	RollbackCapable
	AutoMineCapable
	ExecutionCapable
}

Emulator defines the method set of an emulated emulator.

type ExecutionCapable 

type ExecutionCapable interface {
	ExecuteAndCommitBlock() (*flowgo.Block, []*types.TransactionResult, error)
	ExecuteNextTransaction() (*types.TransactionResult, error)
	ExecuteBlock() ([]*types.TransactionResult, error)
	CommitBlock() (*flowgo.Block, error)
}

type IndexedTransactionResult 

type IndexedTransactionResult struct {
	fvm.ProcedureOutput
	Index uint32
}

type Option 

type Option func(*config)

Option is a function applying a change to the emulator config.

func Contracts 

func Contracts(contracts []ContractDescription) Option

Contracts allows users to deploy the given contracts. Some default common contracts are pre-configured in the `CommonContracts` global variable. It includes contracts such as: NonFungibleToken, FUSD, MetadataViews, NFTStorefront, NFTStorefrontV2, ExampleNFT The default value is []ContractDescription{}.

func WithChainID 

func WithChainID(chainID flowgo.ChainID) Option

WithChainID sets chain type for address generation The default is emulator.

func WithContractRemovalEnabled 

func WithContractRemovalEnabled(enabled bool) Option

WithContractRemovalEnabled restricts/allows removal of already deployed contracts.

The default is provided by on-chain value.

func WithCoverageReport 

func WithCoverageReport(coverageReport *runtime.CoverageReport) Option

WithCoverageReport injects a CoverageReport to collect coverage information.

The default is nil.

func WithGenesisTokenSupply 

func WithGenesisTokenSupply(supply cadence.UFix64) Option

WithGenesisTokenSupply sets the genesis token supply.

func WithLogger 

func WithLogger(
	logger zerolog.Logger,
) Option

WithLogger sets the fvm logger

func WithMinimumStorageReservation 

func WithMinimumStorageReservation(minimumStorageReservation cadence.UFix64) Option

WithMinimumStorageReservation sets the minimum account balance.

The cost of creating new accounts is also set to this value. The default is taken from fvm.DefaultMinimumStorageReservation

func WithScriptGasLimit 

func WithScriptGasLimit(limit uint64) Option

WithScriptGasLimit sets the gas limit for scripts.

This limit does not affect transactions, which declare their own limit. Use WithTransactionMaxGasLimit to set the maximum gas limit for transactions.

func WithServerLogger 

func WithServerLogger(
	logger zerolog.Logger,
) Option

WithServerLogger sets the logger

func WithServicePrivateKey 

func WithServicePrivateKey(
	privateKey sdkcrypto.PrivateKey,
	sigAlgo sdkcrypto.SignatureAlgorithm,
	hashAlgo sdkcrypto.HashAlgorithm,
) Option

WithServicePrivateKey sets the service key from private key.

func WithServicePublicKey 

func WithServicePublicKey(
	servicePublicKey sdkcrypto.PublicKey,
	sigAlgo sdkcrypto.SignatureAlgorithm,
	hashAlgo sdkcrypto.HashAlgorithm,
) Option

WithServicePublicKey sets the service key from a public key.

func WithSimpleAddresses 

func WithSimpleAddresses() Option

WithSimpleAddresses enables simple addresses, which are sequential starting with 0x01.

func WithStorageLimitEnabled 

func WithStorageLimitEnabled(enabled bool) Option

WithStorageLimitEnabled enables/disables limiting account storage used to their storage capacity.

If set to false, accounts can store any amount of data, otherwise they can only store as much as their storage capacity. The default is true.

func WithStorageMBPerFLOW 

func WithStorageMBPerFLOW(storageMBPerFLOW cadence.UFix64) Option

WithStorageMBPerFLOW sets the cost of a megabyte of storage in FLOW

the default is taken from fvm.DefaultStorageMBPerFLOW

func WithStore 

func WithStore(store storage.Store) Option

WithStore sets the persistent storage provider.

func WithTransactionExpiry 

func WithTransactionExpiry(expiry uint) Option

WithTransactionExpiry sets the transaction expiry measured in blocks.

If set to zero, transaction expiry is disabled and the reference block ID field is not required.

func WithTransactionFeesEnabled 

func WithTransactionFeesEnabled(enabled bool) Option

WithTransactionFeesEnabled enables/disables transaction fees.

If set to false transactions don't cost any flow. The default is false.

func WithTransactionMaxGasLimit 

func WithTransactionMaxGasLimit(maxLimit uint64) Option

WithTransactionMaxGasLimit sets the maximum gas limit for transactions.

Individual transactions will still be bounded by the limit they declare. This function sets the maximum limit that any transaction can declare.

This limit does not affect script executions. Use WithScriptGasLimit to set the gas limit for script executions.

func WithTransactionValidationEnabled 

func WithTransactionValidationEnabled(enabled bool) Option

WithTransactionValidationEnabled enables/disables transaction validation.

If set to false, the emulator will not verify transaction signatures or validate sequence numbers.

The default is true.

type RollbackCapable 

type RollbackCapable interface {
	RollbackToBlockHeight(height uint64) error
}

type ServiceKey 

type ServiceKey struct {
	Index          int
	Address        flowgosdk.Address
	SequenceNumber uint64
	PrivateKey     sdkcrypto.PrivateKey
	PublicKey      sdkcrypto.PublicKey
	HashAlgo       sdkcrypto.HashAlgorithm
	SigAlgo        sdkcrypto.SignatureAlgorithm
	Weight         int
}

func DefaultServiceKey 

func DefaultServiceKey() ServiceKey

func GenerateDefaultServiceKey 

func GenerateDefaultServiceKey(
	sigAlgo sdkcrypto.SignatureAlgorithm,
	hashAlgo sdkcrypto.HashAlgorithm,
) ServiceKey

func (ServiceKey) AccountKey 

func (s ServiceKey) AccountKey() *flowgosdk.AccountKey

func (ServiceKey) Signer 

func (s ServiceKey) Signer() (sdkcrypto.Signer, error)

type SnapshotCapable 

type SnapshotCapable interface {
	Snapshots() ([]string, error)
	CreateSnapshot(name string) error
	LoadSnapshot(name string) error
}

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

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.