job

package
v0.6.65 Latest Latest
Warning

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

 Go to latest Published: Nov 23, 2020 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MethodGet  = http.MethodGet
	MethodPost = http.MethodPost
)

Supported HTTP Methods

View Source 
const (
	// ReservedWorkflowConcurrency is the expected concurrency
	// of the create account and request funds scenario.
	ReservedWorkflowConcurrency = 1
)

Variables

View Source 
var (
	// ErrNoBroadcastToConfirm is returned when there is no broadcast
	// to confirm in a job.
	ErrNoBroadcastToConfirm = errors.New("no broadcast to confirm")

	// ErrVariableNotFound is returned when a variable is not
	// present in a Job's state.
	ErrVariableNotFound = errors.New("variable not found")

	// ErrVariableIncorrectFormat is returned when a variable
	// is in the incorrect format (i.e. when we find an int
	// instead of a string).
	ErrVariableIncorrectFormat = errors.New("variable in incorrect format")

	// ErrUnableToHandleBroadcast is returned if a Job cannot handle a
	// broadcast completion (usually because there is no broadcast to confirm).
	ErrUnableToHandleBroadcast = errors.New("unable to handle broadcast")

	// ErrUnableToHandleDryRun is returned if a Job cannot handle a
	// dry run completion.
	ErrUnableToHandleDryRun = errors.New("unable to handle dry run")

	// ErrUnableToCreateBroadcast is returned when it is not possible
	// to create a broadcast or check if a broadcast should be created
	// from a job.
	ErrUnableToCreateBroadcast = errors.New("unable to create broadcast")

	// ErrOperationFormat is returned when []*types.Operation cannot be unmarshaled
	// from <scenario_name>.operations.
	ErrOperationFormat = errors.New("operation format")

	// ErrConfirmationDepthInvalid is returned when <scenario_name>.operations
	// are populated, but confirmation depth is missing or invalid.
	ErrConfirmationDepthInvalid = errors.New("invalid confirmation depth")

	// ErrNetworkInvalid is returned when <scenario_name>.operations
	// are populated, but network is missing or invalid.
	ErrNetworkInvalid = errors.New("network invalid")

	// ErrMetadataInvalid is returned when <scenario_name>.operations
	// are populated, but construction preprocess metadata is
	// invalid (ok to be missing).
	ErrMetadataInvalid = errors.New("metadata invalid")
)

Functions

func UnmarshalInput 

func UnmarshalInput(input []byte, output interface{}) error

UnmarshalInput attempts to strictly unmarshal some input into output.

Types

type Action 

type Action struct {
	Input      string     `json:"input"`
	Type       ActionType `json:"type"`
	OutputPath string     `json:"output_path,omitempty"`
}

Action is a step of computation that where the result is saved to OutputPath.

type ActionType 

type ActionType string

ActionType is a type of Action that can be processed. 

const (
	// GenerateKey creates a new *keys.KeyPair.
	GenerateKey ActionType = "generate_key"

	// SaveAccount saves a generated *keys.KeyPair
	// and *types.AccountIdentifier to key storage.
	SaveAccount ActionType = "save_account"

	// Derive calls `/construction/derive` with a *keys.PublicKey.
	Derive ActionType = "derive"

	// SetVariable allows for setting the value of any
	// variable (as opposed to calculating it using
	// other actions).
	SetVariable ActionType = "set_variable"

	// FindBalance finds some unlocked account that optionally
	// has a minimum balance of funds.
	// FindCoin finds some coin above a certain amount. It is
	// possible to specify coins which should not be considered (by identifier).
	FindBalance ActionType = "find_balance"

	// PrintMessage can be used to print any message
	// to the terminal. This is usually used to indicate
	// to the caller that they should deposit money to an
	// address. It is left generic to allow the user to
	// include whatever content they would like in the
	// message (especially useful in on-chain origination).
	// This can also be used to log information during
	// execution.
	PrintMessage ActionType = "print_message"

	// Math is used to perform addition or subtraction of variables. It is
	// most commonly used to determine how much to send to a change output
	// on UTXO blockchains.
	Math ActionType = "math"

	// RandomString generates a string according to some provided regex.
	// It is used to generate account names for blockchains that require
	// on-chain origination.
	RandomString ActionType = "random_string"

	// RandomNumber generates a random number in some range [min, max).
	// It is used to generate random transaction amounts.
	RandomNumber ActionType = "random_number"

	// FindCurrencyAmount finds a *types.Amount for a certain currency
	// in an array of []*types.Amount. This is typically used when parsing
	// the suggested fee response from /construction/metadata.
	FindCurrencyAmount ActionType = "find_currency_amount"

	// Assert ensures that a provided number is >= 0 and causes
	// execution to exit if this is not true. This is useful when
	// ensuring that an account has sufficient balance to pay the
	// suggested fee to broadcast a transaction.
	Assert ActionType = "assert"

	// LoadEnv loads some value from an environment variable. This
	// is very useful injecting an API token for algorithmic fauceting
	// when running CI.
	LoadEnv ActionType = "load_env"

	// HTTPRequest makes an HTTP request at some URL. This is useful
	// for making a request to a faucet to automate Construction API
	// testing.
	HTTPRequest ActionType = "http_request"
)

type Broadcast 

type Broadcast struct {
	Network           *types.NetworkIdentifier
	Intent            []*types.Operation
	Metadata          map[string]interface{}
	ConfirmationDepth int64
	DryRun            bool
}

Broadcast contains information needed to create and broadcast a transaction. Broadcast is returned from Job processing only IF a broadcast is required.

type FindBalanceInput 

type FindBalanceInput struct {
	// AccountIdentifier can be optionally provided to ensure the balance returned
	// is for a particular address (this is used when fetching the balance
	// of the same account in multiple currencies, when requesting funds,
	// or when constructing a multi-input UTXO transfer with the
	// same address).
	AccountIdentifier *types.AccountIdentifier `json:"account_identifier,omitempty"`

	// SubAccountIdentifier can be used to find addresses with particular
	// SubAccount balances. This is particularly useful for
	// orchestrating staking transactions.
	SubAccountIdentifier *types.SubAccountIdentifier `json:"sub_account_identifier,omitempty"`

	// NotAddress can be populated to ensure a different
	// address is found. This is useful when avoiding a
	// self-transfer.
	NotAddress []string `json:"not_address,omitempty"`

	// NotAccountIdentifier can be used to avoid entire
	// *types.AccountIdentifiers and is used when only
	// certain SubAccountIdentifiers of an Address are
	// desired.
	NotAccountIdentifier []*types.AccountIdentifier `json:"not_account_identifier,omitempty"`

	// MinimumBalance is the minimum required balance that must be found.
	MinimumBalance *types.Amount `json:"minimum_balance,omitempty"`

	// RequireCoin indicates if a coin must be found with the minimum balance.
	// This is useful for orchestrating transfers on UTXO-based blockchains.
	RequireCoin bool `json:"require_coin,omitempty"`

	// NotCoins indicates that certain coins should not be considered. This is useful
	// for avoiding using the same Coin twice.
	NotCoins []*types.CoinIdentifier `json:"not_coins,omitempty"`

	// CreateLimit is used to determine if we should create a new address using
	// the CreateAccount Workflow. This will only occur if the
	// total number of addresses is under some pre-defined limit.
	// If the value is <= 0, we will not attempt to create.
	CreateLimit int `json:"create_limit,omitempty"`

	// CreateProbability is used to determine if a new account should be
	// created with some probability [0, 100). This will override the search
	// for any valid accounts and instead return ErrCreateAccount.
	CreateProbability int `json:"create_probability,omitempty"`
}

FindBalanceInput is the input to FindBalance.

type FindBalanceOutput 

type FindBalanceOutput struct {
	// AccountIdentifier is the account associated with the balance
	// (and coin).
	AccountIdentifier *types.AccountIdentifier `json:"account_identifier"`

	// Balance found at a particular currency.
	Balance *types.Amount `json:"balance"`

	// Coin is populated if RequireCoin is true.
	Coin *types.CoinIdentifier `json:"coin,omitempty"`
}

FindBalanceOutput is returned by FindBalance.

type FindCurrencyAmountInput 

type FindCurrencyAmountInput struct {
	Currency *types.Currency `json:"currency"`
	Amounts  []*types.Amount `json:"amounts"`
}

FindCurrencyAmountInput is the input to FindCurrencyAmount.

type GenerateKeyInput 

type GenerateKeyInput struct {
	CurveType types.CurveType `json:"curve_type"`
}

GenerateKeyInput is the input for GenerateKey.

type HTTPMethod 

type HTTPMethod string

HTTPMethod is a type representing allowed HTTP methods.

type HTTPRequestInput 

type HTTPRequestInput struct {
	Method  string `json:"method"`
	URL     string `json:"url"`
	Timeout int    `json:"timeout"`

	// If the Method is POST, the Body
	// can be populated with JSON.
	Body string `json:"body"`
}

HTTPRequestInput is the input to HTTP Request.

type Job 

type Job struct {
	// Identifier is a UUID that is generated
	// when a Job is stored in JobStorage for the
	// first time. When executing the first scenario
	// in a Job, this will be empty.
	Identifier string `json:"identifier"`
	State      string `json:"state"`
	Index      int    `json:"index"`
	Status     Status `json:"status"`

	// Workflow is the name of the workflow being executed.
	Workflow string `json:"workflow"`

	// Scenarios are copied into each context in case
	// a configuration file changes that could corrupt
	// in-process flows.
	Scenarios []*Scenario `json:"scenarios"`
}

Job is an instantion of a Workflow.

func New 

func New(workflow *Workflow) *Job

New creates a new *Job.

func (*Job) BroadcastComplete 

func (j *Job) BroadcastComplete(
	ctx context.Context,
	transaction *types.Transaction,
) error

BroadcastComplete is called either after a broadcast has been confirmed at the provided confirmation depth or if it has failed for some reason.

func (*Job) CheckComplete 

func (j *Job) CheckComplete() bool

CheckComplete returns a boolean indicating if a job is complete.

func (*Job) CreateBroadcast 

func (j *Job) CreateBroadcast() (*Broadcast, error)

CreateBroadcast returns a *Broadcast for a given job or nil if none is required.

func (*Job) DryRunComplete 

func (j *Job) DryRunComplete(
	ctx context.Context,
	suggestedFee []*types.Amount,
) error

DryRunComplete is invoked after a transaction dry run has been performed.

type MathInput 

type MathInput struct {
	Operation  MathOperation `json:"operation"`
	LeftValue  string        `json:"left_value"`
	RightValue string        `json:"right_value"`
}

MathInput is the input to Math.

type MathOperation 

type MathOperation string

MathOperation is some mathematical operation that can be performed on 2 numbers. 

const (
	// Addition is adding LeftValue + RightValue.
	Addition MathOperation = "addition"

	// Subtraction is LeftValue - RightValue.
	Subtraction MathOperation = "subtraction"
)

type RandomNumberInput 

type RandomNumberInput struct {
	Minimum string `json:"minimum"`
	Maximum string `json:"maximum"`
}

RandomNumberInput is used to generate a random number in the range [minimum, maximum).

type RandomStringInput 

type RandomStringInput struct {
	Regex string `json:"regex"`

	// Limit is the maximum number of times each star, range, or
	// plus character could be repeated.
	Limit int `json:"limit"`
}

RandomStringInput is the input to RandomString.

type ReservedVariable 

type ReservedVariable string

ReservedVariable is a reserved variable field in a Job's state. 

const (
	// Network is the *types.NetworkIdentifier to use
	// for broadcast.
	Network ReservedVariable = "network"

	// Operations are the []*types.Operation to use
	// as intent.
	Operations ReservedVariable = "operations"

	// PreprocessMetadata is the metadata to provide to /construction/preprocess.
	PreprocessMetadata ReservedVariable = "preprocess_metadata"

	// Transaction is the *types.Transaction confirmed
	// on-chain.
	Transaction ReservedVariable = "transaction"

	// ConfirmationDepth is the amount of blocks we wait to confirm
	// a transaction. We allow setting this on a per scenario basis because
	// certain transactions may only be considered complete
	// after some time (ex: staking transaction).
	ConfirmationDepth ReservedVariable = "confirmation_depth"

	// DryRun is a boolean that indicates whether we should perform the
	// entire transaction construction process or just /construction/preprocess
	// and /construction/metadata to determine the suggested transaction
	// fee. If this variable is not populated, we assume that it is NOT
	// a dry run.
	DryRun ReservedVariable = "dry_run"

	// SuggestedFee is the []*types.Amount returned from
	// an implementation's /construction/metadata endpoint (if implemented).
	SuggestedFee ReservedVariable = "suggested_fee"
)

type ReservedWorkflow 

type ReservedWorkflow string

ReservedWorkflow is a Workflow reserved for special circumstances. All ReservedWorkflows must exist when running the constructor. 

const (
	// CreateAccount is where another account (already with funds)
	// creates a new account. It is possible to configure how many
	// accounts should be created. CreateAccount must be executed
	// with a concurrency of 1.
	CreateAccount ReservedWorkflow = "create_account"

	// RequestFunds is where the user funds an account. This flow
	// is invoked when there are no pending broadcasts and it is not possible
	// to make progress on any Flows or start new ones. RequestFunds
	// must be executed with a concurrency of 1.
	RequestFunds ReservedWorkflow = "request_funds"

	// ReturnFunds is invoked on shutdown so funds can be
	// returned to a single address (like a faucet). This
	// is useful for CI testing.
	ReturnFunds ReservedWorkflow = "return_funds"
)

type SaveAccountInput 

type SaveAccountInput struct {
	AccountIdentifier *types.AccountIdentifier `json:"account_identifier"`
	KeyPair           *keys.KeyPair            `json:"keypair"`
}

SaveAccountInput is the input for SaveAccount.

type Scenario 

type Scenario struct {
	Name    string    `json:"name"`
	Actions []*Action `json:"actions"`
}

Scenario is a collection of Actions with a specific confirmation depth.

There is a special variable you can set at the end of a scenario called "<scenario_name>.operations" to indicate that a transaction should be broadcast. It is also possible to specify the network where the transaction should be broadcast and the metadata to provide in a call to /construction/preprocess.

Once a scenario is broadcasted and confirmed, the transaction details are placed in a special variable called "transaction". This can be used in scenarios following the execution of this one.

type Status 

type Status string

Status is status of a Job. 

const (
	// Ready means that a Job is ready to process.
	Ready Status = "ready"

	// Broadcasting means that the intent of the last
	// scenario is broadcasting.
	Broadcasting Status = "broadcasting"

	// Failed means that Broadcasting failed.
	Failed Status = "failed"

	// Completed means that all scenarios were
	// completed successfully.
	Completed Status = "completed"
)

type Workflow 

type Workflow struct {
	Name string `json:"name"`

	// Concurrency is the number of workflows of a particular
	// kind to execute at once. For example, you may not want
	// to process concurrent workflows of some staking operations
	// that take days to play out.
	Concurrency int         `json:"concurrency"`
	Scenarios   []*Scenario `json:"scenarios"`
}

Workflow is a collection of scenarios to run (i.e. transactions to broadcast) with some shared state.

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.