flowkit

package module
v1.13.0 Latest Latest
Warning

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

 Go to latest Published: Feb 1, 2024 License: Apache-2.0 Imports: 28 Imported by: 1

README

Flowkit Package Design

Flowkit is a core package used by the CLI commands. It features APIs for interacting with the Flow network in the context of flow.json configuration values. Flowkit is defined by the interface here.

Flowkit contains multiple subpackages, the most important ones are:

  • config: parsing and storing of flow.json values, as well as validation,
  • gateway: implementation of Flow AN methods, uses emulator as well as Go SDK to communicate with ANs,
  • project: stateful operations on top of flow.json, which allows resolving imports in contracts used in deployments

It is important we define clear boundaries between flowkit and other CLI packages. If we are in doubt where certain methods should be implemented we must ask ourselves if the method provides value for any other consumers of the pacakge or only provides utility for CLI usage, if it's only providing utility for CLI then it should be added inside the internal package, instead of flowkit. If in doubt better to add things to internal package and then move to flowkit if such need is identified.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var LatestBlockQuery = BlockQuery{Latest: true}

LatestBlockQuery specifies the latest block.

View Source 
var LatestScriptQuery = ScriptQuery{Latest: true}

LatestScriptQuery specifies the latest block at which query is executed.

Functions

This section is empty.

Types

type BlockQuery 

type BlockQuery struct {
	ID     *flow.Identifier
	Height uint64
	Latest bool
}

BlockQuery defines possible queries for block.

func NewBlockQuery 

func NewBlockQuery(query string) (BlockQuery, error)

NewBlockQuery creates block query based on the passed query value.

Query string options: - "latest" : return the latest block - height (e.g. 123456789) : return block at this height - ID : return block with this ID if none of the valid values are passed an error is returned.

type Event 

type Event struct {
	Type   string
	Values map[string]cadence.Value
}

func NewEvent 

func NewEvent(event flow.Event) Event

func (*Event) GetAddress 

func (e *Event) GetAddress() *flow.Address

type EventWorker 

type EventWorker struct {
	Count           int
	BlocksPerWorker uint64
}

EventWorker defines how many workers do we want to start, each in its own subroutine, and how many blocks each worker fetches from the network. This is used to process the event requests concurrently.

type Events 

type Events []Event

func EventsFromTransaction 

func EventsFromTransaction(tx *flow.TransactionResult) Events

func (*Events) GetCreatedAddresses 

func (e *Events) GetCreatedAddresses() []*flow.Address

type Flowkit 

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

func NewFlowkit 

func NewFlowkit(
	state *State,
	network config.Network,
	gateway gateway.Gateway,
	logger output.Logger,
) *Flowkit

func (*Flowkit) AddContract 

func (f *Flowkit) AddContract(
	ctx context.Context,
	account *accounts.Account,
	contract Script,
	update UpdateContract,
) (flow.Identifier, bool, error)

AddContract to the Flow account provided and return the transaction ID.

If the contract already exists on the account the operation will fail and error will be returned. Use UpdateExistingContract(bool) to define whether a contract should be updated or not, or you can also define a custom UpdateContract function which returns bool indicating whether a contract should be updated or not.

func (*Flowkit) BuildTransaction 

func (f *Flowkit) BuildTransaction(
	_ context.Context,
	addresses transactions.AddressesRoles,
	proposerKeyIndex int,
	script Script,
	gasLimit uint64,
) (*transactions.Transaction, error)

BuildTransaction builds a new transaction type for later signing and submitting to the network.

AddressesRoles type defines the address for each role (payer, proposer, authorizers) and the script defines the transaction content.

func (*Flowkit) CreateAccount 

func (f *Flowkit) CreateAccount(
	_ context.Context,
	signer *accounts.Account,
	keys []accounts.PublicKey,
) (*flow.Account, flow.Identifier, error)

CreateAccount on the Flow network with the provided keys and using the signer for creation transaction. Returns the newly created account as well as the ID of the transaction that created the account.

Keys is a slice but only one can be passed as well. If the transaction fails or there are other issues an error is returned.

func (*Flowkit) DeployProject 

func (f *Flowkit) DeployProject(ctx context.Context, update UpdateContract) ([]*project.Contract, error)

DeployProject contracts to the Flow network or update if already exists and UpdateContracts returns true.

Retrieve all the contracts for specified network, sort them for deployment deploy one by one and replace the imports in the contract source, so it corresponds to the account name the contract was deployed to. If contracts already exist use UpdateExistingContract(bool) to define whether a contract should be updated or not.

func (*Flowkit) DerivePrivateKeyFromMnemonic 

func (f *Flowkit) DerivePrivateKeyFromMnemonic(
	_ context.Context,
	mnemonic string,
	sigAlgo crypto.SignatureAlgorithm,
	derivationPath string,
) (crypto.PrivateKey, error)

func (*Flowkit) ExecuteScript 

func (f *Flowkit) ExecuteScript(_ context.Context, script Script, query ScriptQuery) (cadence.Value, error)

ExecuteScript on the Flow network and return the Cadence value as a result. The script is executed at the block provided as part of the ScriptQuery value.

func (*Flowkit) Gateway 

func (f *Flowkit) Gateway() gateway.Gateway

func (*Flowkit) GenerateKey 

func (f *Flowkit) GenerateKey(
	_ context.Context,
	sigAlgo crypto.SignatureAlgorithm,
	inputSeed string,
) (crypto.PrivateKey, error)

GenerateKey using the signature algorithm and optional seed. If seed is not provided a random safe seed will be generated.

func (*Flowkit) GenerateMnemonicKey 

func (f *Flowkit) GenerateMnemonicKey(
	_ context.Context,
	sigAlgo crypto.SignatureAlgorithm,
	derivationPath string,
) (crypto.PrivateKey, string, error)

GenerateMnemonicKey will generate a new key with the signature algorithm and optional derivation path.

If the derivation path is not provided a default "m/44'/539'/0'/0/0" will be used.

func (*Flowkit) GetAccount 

func (f *Flowkit) GetAccount(_ context.Context, address flow.Address) (*flow.Account, error)

GetAccount fetches account on the Flow network.

func (*Flowkit) GetBlock 

func (f *Flowkit) GetBlock(_ context.Context, query BlockQuery) (*flow.Block, error)

GetBlock by the query from Flow blockchain. Query can define a block by ID, block by height or require the latest block.

func (*Flowkit) GetCollection 

func (f *Flowkit) GetCollection(_ context.Context, ID flow.Identifier) (*flow.Collection, error)

GetCollection by the ID from Flow network.

func (*Flowkit) GetEvents 

func (f *Flowkit) GetEvents(
	_ context.Context,
	names []string,
	startHeight uint64,
	endHeight uint64,
	worker *EventWorker,
) ([]flow.BlockEvents, error)

GetEvents from Flow network by their event name in the specified height interval defined by start and end inclusive. Optional worker defines parameters for how many concurrent workers do we want to fetch our events, and how many blocks between the provided interval each worker fetches.

Providing worker value will produce faster response as the interval will be scanned concurrently. This parameter is optional, if not provided only a single worker will be used.

func (*Flowkit) GetTransactionByID 

func (f *Flowkit) GetTransactionByID(
	_ context.Context,
	ID flow.Identifier,
	waitSeal bool,
) (*flow.Transaction, *flow.TransactionResult, error)

GetTransactionByID from the Flow network including the transaction result. Using the waitSeal we can wait for the transaction to be sealed.

func (*Flowkit) GetTransactionsByBlockID 

func (f *Flowkit) GetTransactionsByBlockID(
	_ context.Context,
	blockID flow.Identifier,
) ([]*flow.Transaction, []*flow.TransactionResult, error)

func (*Flowkit) Network 

func (f *Flowkit) Network() config.Network

func (*Flowkit) Ping 

func (f *Flowkit) Ping() error

func (*Flowkit) RemoveContract 

func (f *Flowkit) RemoveContract(
	_ context.Context,
	account *accounts.Account,
	contractName string,
) (flow.Identifier, error)

RemoveContract from the provided account by its name.

If removal is successful transaction ID is returned.

func (*Flowkit) SendSignedTransaction 

func (f *Flowkit) SendSignedTransaction(
	_ context.Context,
	tx *transactions.Transaction,
) (*flow.Transaction, *flow.TransactionResult, error)

SendSignedTransaction will send a prebuilt and signed transaction to the Flow network.

You can build the transaction using the BuildTransaction method and then sign it using the SignTranscation method.

func (*Flowkit) SendTransaction 

func (f *Flowkit) SendTransaction(
	ctx context.Context,
	accounts transactions.AccountRoles,
	script Script,
	gasLimit uint64,
) (*flow.Transaction, *flow.TransactionResult, error)

SendTransaction will build and send a transaction to the Flow network, using the accounts provided for each role and contain the script. Transaction as well as transaction result will be returned in case the transaction is successfully submitted.

func (*Flowkit) SetLogger 

func (f *Flowkit) SetLogger(logger output.Logger)

func (*Flowkit) SignTransactionPayload 

func (f *Flowkit) SignTransactionPayload(
	_ context.Context,
	signer *accounts.Account,
	payload []byte,
) (*transactions.Transaction, error)

SignTransactionPayload will use the signer account provided and the payload raw byte content to sign it.

The payload should be RLP encoded transaction payload and is suggested to be used in pair with BuildTransaction function.

func (*Flowkit) State 

func (f *Flowkit) State() (*State, error)

type ProjectDeploymentError 

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

func (*ProjectDeploymentError) Contracts 

func (d *ProjectDeploymentError) Contracts() map[string]error

func (*ProjectDeploymentError) Error 

func (d *ProjectDeploymentError) Error() string

type ReaderWriter 

type ReaderWriter interface {
	ReadFile(source string) ([]byte, error)
	WriteFile(filename string, data []byte, perm os.FileMode) error
	MkdirAll(path string, perm os.FileMode) error
	Stat(path string) (os.FileInfo, error)
}

ReaderWriter defines read file and write file methods.

type Script 

type Script struct {
	Code     []byte
	Args     []cadence.Value
	Location string
}

Script includes Cadence code and optional arguments and filename.

Filename is only required to be passed if the code has imports you want to resolve.

type ScriptQuery 

type ScriptQuery struct {
	Latest bool
	ID     flow.Identifier
	Height uint64
}

ScriptQuery defines block ID or height at which we should execute the script.

type Services 

type Services interface {
	Network() config.Network
	Ping() error
	Gateway() gateway.Gateway
	SetLogger(output.Logger)

	// GetAccount fetches account on the Flow network.
	GetAccount(context.Context, flow.Address) (*flow.Account, error)

	// CreateAccount on the Flow network with the provided keys and using the signer for creation transaction.
	// Returns the newly created account as well as the ID of the transaction that created the account.
	//
	// Keys is a slice but only one can be passed as well. If the transaction fails or there are other issues an error is returned.
	CreateAccount(context.Context, *accounts.Account, []accounts.PublicKey) (*flow.Account, flow.Identifier, error)

	// AddContract to the Flow account provided and return the transaction ID.
	//
	// If the contract already exists on the account the operation will fail and error will be returned.
	// Use UpdateExistingContract(bool) to define whether a contract should be updated or not, or you can also
	// define a custom UpdateContract function which returns bool indicating whether a contract should be updated or not.
	AddContract(context.Context, *accounts.Account, Script, UpdateContract) (flow.Identifier, bool, error)

	// RemoveContract from the provided account by its name.
	//
	// If removal is successful transaction ID is returned.
	RemoveContract(context.Context, *accounts.Account, string) (flow.Identifier, error)

	// GetBlock by the query from Flow blockchain. Query can define a block by ID, block by height or require the latest block.
	GetBlock(context.Context, BlockQuery) (*flow.Block, error)

	// GetCollection by the ID from Flow network.
	GetCollection(context.Context, flow.Identifier) (*flow.Collection, error)

	// GetEvents from Flow network by their event name in the specified height interval defined by start and end inclusive.
	// Optional worker defines parameters for how many concurrent workers do we want to fetch our events,
	// and how many blocks between the provided interval each worker fetches.
	//
	// Providing worker value will produce faster response as the interval will be scanned concurrently. This parameter is optional,
	// if not provided only a single worker will be used.
	GetEvents(context.Context, []string, uint64, uint64, *EventWorker) ([]flow.BlockEvents, error)

	// GenerateKey using the signature algorithm and optional seed. If seed is not provided a random safe seed will be generated.
	GenerateKey(context.Context, crypto.SignatureAlgorithm, string) (crypto.PrivateKey, error)

	// GenerateMnemonicKey will generate a new key with the signature algorithm and optional derivation path.
	//
	// If the derivation path is not provided a default "m/44'/539'/0'/0/0" will be used.
	GenerateMnemonicKey(context.Context, crypto.SignatureAlgorithm, string) (crypto.PrivateKey, string, error)

	DerivePrivateKeyFromMnemonic(context.Context, string, crypto.SignatureAlgorithm, string) (crypto.PrivateKey, error)

	// DeployProject contracts to the Flow network or update if already exists and UpdateContracts returns true.
	//
	// Retrieve all the contracts for specified network, sort them for deployment deploy one by one and replace
	// the imports in the contract source, so it corresponds to the account name the contract was deployed to.
	// If contracts already exist use UpdateExistingContract(bool) to define whether a contract should be updated or not.
	DeployProject(context.Context, UpdateContract) ([]*project.Contract, error)

	// ExecuteScript on the Flow network and return the Cadence value as a result. The script is executed at the
	// block provided as part of the ScriptQuery value.
	ExecuteScript(context.Context, Script, ScriptQuery) (cadence.Value, error)

	// GetTransactionByID from the Flow network including the transaction result. Using the waitSeal we can wait for the transaction to be sealed.
	GetTransactionByID(context.Context, flow.Identifier, bool) (*flow.Transaction, *flow.TransactionResult, error)

	GetTransactionsByBlockID(context.Context, flow.Identifier) ([]*flow.Transaction, []*flow.TransactionResult, error)

	// BuildTransaction builds a new transaction type for later signing and submitting to the network.
	//
	// AddressesRoles type defines the address for each role (payer, proposer, authorizers) and the script defines the transaction content.
	BuildTransaction(context.Context, transactions.AddressesRoles, int, Script, uint64) (*transactions.Transaction, error)

	// SignTransactionPayload will use the signer account provided and the payload raw byte content to sign it.
	//
	// The payload should be RLP encoded transaction payload and is suggested to be used in pair with BuildTransaction function.
	SignTransactionPayload(context.Context, *accounts.Account, []byte) (*transactions.Transaction, error)

	// SendSignedTransaction will send a prebuilt and signed transaction to the Flow network.
	//
	// You can build the transaction using the BuildTransaction method and then sign it using the SignTranscation method.
	SendSignedTransaction(context.Context, *transactions.Transaction) (*flow.Transaction, *flow.TransactionResult, error)

	// SendTransaction will build and send a transaction to the Flow network, using the accounts provided for each role and
	// contain the script. Transaction as well as transaction result will be returned in case the transaction is successfully submitted.
	SendTransaction(context.Context, transactions.AccountRoles, Script, uint64) (*flow.Transaction, *flow.TransactionResult, error)
}

type State 

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

State manages the state for a Flow project.

func Init 

func Init(
	rw ReaderWriter,
	sigAlgo crypto.SignatureAlgorithm,
	hashAlgo crypto.HashAlgorithm,
) (*State, error)

Init initializes a new Flow project.

func Load 

func Load(configFilePaths []string, readerWriter ReaderWriter) (*State, error)

Load loads a project configuration and returns the resulting project.

func (*State) Accounts 

func (p *State) Accounts() *accounts.Accounts

Accounts get accounts.

func (*State) AccountsForNetwork 

func (p *State) AccountsForNetwork(network config.Network) *accounts.Accounts

AccountsForNetwork returns all accounts used on a network defined by deployments.

func (*State) AliasesForNetwork 

func (p *State) AliasesForNetwork(network config.Network) project.LocationAliases

AliasesForNetwork returns all deployment aliases for a network.

func (*State) Config 

func (p *State) Config() *config.Config

Config get underlying configuration for advanced usage.

func (*State) Contracts 

func (p *State) Contracts() *config.Contracts

Contracts get contracts configuration.

func (*State) CreateCoverageReport added in v1.12.0 

func (p *State) CreateCoverageReport(network string) *runtime.CoverageReport

func (*State) Dependencies added in v1.12.0 

func (p *State) Dependencies() *config.Dependencies

func (*State) DeploymentContractsByNetwork 

func (p *State) DeploymentContractsByNetwork(network config.Network) ([]*project.Contract, error)

DeploymentContractsByNetwork returns all contracts for a network.

Build contract slice based on the network provided, check the deployment section for that network and retrieve the account by name, then add the accounts address on the contract as a destination.

func (*State) Deployments 

func (p *State) Deployments() *config.Deployments

Deployments get deployments configuration.

func (*State) EmulatorServiceAccount 

func (p *State) EmulatorServiceAccount() (*accounts.Account, error)

EmulatorServiceAccount returns the service account for the default emulator profile.

func (*State) Networks 

func (p *State) Networks() *config.Networks

Networks get network configuration.

func (*State) ReadFile 

func (p *State) ReadFile(source string) ([]byte, error)

ReadFile exposes an injected file loader.

func (*State) ReaderWriter 

func (p *State) ReaderWriter() ReaderWriter

ReaderWriter retrieve current file reader writer.

func (*State) Save 

func (p *State) Save(path string) error

Save saves the project configuration to the given path.

func (*State) SaveDefault 

func (p *State) SaveDefault() error

SaveDefault saves to default path.

func (*State) SaveEdited 

func (p *State) SaveEdited(paths []string) error

SaveEdited saves configuration to valid path.

func (*State) SetEmulatorKey 

func (p *State) SetEmulatorKey(privateKey crypto.PrivateKey)

SetEmulatorKey sets the default emulator service account private key.

type UpdateContract 

type UpdateContract func(existing []byte, new []byte) bool

func UpdateExistingContract 

func UpdateExistingContract(updateExisting bool) UpdateContract

Source Files

View all Source files

Directories

Path Synopsis
cmd
flow-schema
json
mocks

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.