tokens

Documentation

Index

• Constants
• type Callbacks
• type Capabilities
• type Plugin
• type TokenApproval
• type TokenPool
• type TokenTransfer

Constants

const (
	// TokensConfigName is the user-supplied name for this token type
	TokensConfigName = "name"
	// TokensConfigConnector is the connector plugin used for this token type (deprecated)
	TokensConfigConnector = "connector" // TODO: remove
	// TokensConfigPlugin is the connector plugin used for this token type
	TokensConfigPlugin = "plugin"
)

Types

type Callbacks

type Callbacks interface {
	// TokenOpUpdate notifies firefly of an update to this plugin's operation within a transaction.
	// Only success/failure and errorMessage (for errors) are modeled.
	// opOutput can be used to add opaque protocol specific JSON from the plugin (protocol transaction ID etc.)
	// Note this is an optional hook information, and stored separately to the confirmation of the actual event that was being submitted/sequenced.
	// Only the party submitting the transaction will see this data.
	//
	// Error should only be returned in shutdown scenarios
	TokenOpUpdate(plugin Plugin, operationID *fftypes.UUID, txState fftypes.OpStatus, blockchainTXID, errorMessage string, opOutput fftypes.JSONObject)

	// TokenPoolCreated notifies on the creation of a new token pool, which might have been
	// submitted by us, or by any other authorized party in the network.
	//
	// Error should only be returned in shutdown scenarios
	TokenPoolCreated(plugin Plugin, pool *TokenPool) error

	// TokensTransferred notifies on a transfer between token accounts.
	//
	// Error should only be returned in shutdown scenarios
	TokensTransferred(plugin Plugin, transfer *TokenTransfer) error

	// TokensApproved notifies on a token approval
	//
	// Error should will only be returned in shutdown scenarios
	TokensApproved(plugin Plugin, approval *TokenApproval) error
}

Callbacks is the interface provided to the tokens plugin, to allow it to pass events back to firefly.

Events must be delivered sequentially, such that event 2 is not delivered until the callback invoked for event 1 has completed. However, it does not matter if these events are workload balance between the firefly core cluster instances of the node.

type Capabilities

type Capabilities struct {
}

Capabilities is the supported featureset of the tokens interface implemented by the plugin, with the specified config

type Plugin

type Plugin interface {
	fftypes.Named

	// InitPrefix initializes the set of configuration options that are valid, with defaults. Called on all plugins.
	InitPrefix(prefix config.PrefixArray)

	// Init initializes the plugin, with configuration
	// Returns the supported featureset of the interface
	Init(ctx context.Context, name string, prefix config.Prefix, callbacks Callbacks) error

	// Blockchain interface must not deliver any events until start is called
	Start() error

	// Capabilities returns capabilities - not called until after Init
	Capabilities() *Capabilities

	// CreateTokenPool creates a new (fungible or non-fungible) pool of tokens
	CreateTokenPool(ctx context.Context, opID *fftypes.UUID, pool *fftypes.TokenPool) (complete bool, err error)

	// ActivateTokenPool activates a pool in order to begin receiving events
	ActivateTokenPool(ctx context.Context, opID *fftypes.UUID, pool *fftypes.TokenPool) (complete bool, err error)

	// MintTokens mints new tokens in a pool and adds them to the recipient's account
	MintTokens(ctx context.Context, opID *fftypes.UUID, poolLocator string, mint *fftypes.TokenTransfer) error

	// BurnTokens burns tokens from an account
	BurnTokens(ctx context.Context, opID *fftypes.UUID, poolLocator string, burn *fftypes.TokenTransfer) error

	// TransferTokens transfers tokens within a pool from one account to another
	TransferTokens(ctx context.Context, opID *fftypes.UUID, poolLocator string, transfer *fftypes.TokenTransfer) error

	// TokenApproval approves an operator to transfer tokens on the owner's behalf
	TokensApproval(ctx context.Context, opID *fftypes.UUID, poolLocator string, approval *fftypes.TokenApproval) error
}

Plugin is the interface implemented by each tokens plugin

type TokenApproval

type TokenApproval struct {
	fftypes.TokenApproval

	// PoolLocator is the ID assigned to the token pool by the connector
	PoolLocator string

	// Event contains info on the underlying blockchain event for this transfer
	Event blockchain.Event
}

type TokenPool

type TokenPool struct {
	// Type is the type of tokens (fungible, non-fungible, etc) in this pool
	Type fftypes.TokenType

	// PoolLocator is the ID assigned to this pool by the connector (must be unique for this connector)
	PoolLocator string

	// TX is the FireFly-assigned information to correlate this to a transaction (optional)
	TX fftypes.TransactionRef

	// Connector is the configured name of this connector
	Connector string

	// Standard is the well-defined token standard that this pool conforms to (optional)
	Standard string

	// Decimals is the number of decimal places that this token has
	Decimals int

	// Symbol is the short token symbol, if the connector uses one (optional)
	Symbol string

	// Info is any other connector-specific info on the pool that may be worth saving (optional)
	Info fftypes.JSONObject

	// Event contains info on the underlying blockchain event for this pool creation
	Event blockchain.Event
}

TokenPool is the set of data returned from the connector when a token pool is created.

type TokenTransfer

type TokenTransfer struct {
	// Although not every field will be filled in, embed fftypes.TokenTransfer to avoid duplicating lots of fields
	// Notable fields NOT expected to be populated by plugins: Namespace, LocalID, Pool
	fftypes.TokenTransfer

	// PoolLocator is the ID assigned to the token pool by the connector
	PoolLocator string

	// Event contains info on the underlying blockchain event for this transfer
	Event blockchain.Event
}