faucet

Documentation

Index

• Constants
• Variables
• func IsAddressBlackListed(address ledgerstate.Address) bool
• func RemoveAddressFromBlacklist(address ledgerstate.Address)
• type FaucetOutput
• type ParametersDefinition
• type StateManager
  • func NewStateManager(tokensPerRequest uint64, seed *walletseed.Seed, supplyOutputsCount uint64, ...) *StateManager
  • func (s *StateManager) DeriveStateFromTangle(ctx context.Context) (err error)
  • func (s *StateManager) FulFillFundingRequest(requestMsg *tangle.Message) (*tangle.Message, string, error)

Constants

const (
	// RemainderAddressIndex is the RemainderAddressIndex.
	RemainderAddressIndex = 0

	// MinFundingOutputsPercentage defines the min percentage of prepared funding outputs left that triggers a replenishment.
	MinFundingOutputsPercentage = 0.3

	// MaxFaucetOutputsCount defines the max outputs count for the Faucet as the ledgerstate.MaxOutputCount -1 remainder output.
	MaxFaucetOutputsCount = ledgerstate.MaxOutputCount - 1

	// WaitForConfirmation defines the wait time before considering a transaction confirmed.
	WaitForConfirmation = 10 * time.Second

	// MaxWaitAttempts defines the number of attempts taken while waiting for confirmation during funds preparation.
	MaxWaitAttempts = 50
)

const (
	// PluginName is the name of the faucet plugin.
	PluginName = "Faucet"
)

Variables

var (
	// ErrNotEnoughFundingOutputs if there are not enough funding outputs in the faucet.
	ErrNotEnoughFundingOutputs = errors.New("not enough funding outputs to complete the request")
	// ErrMissingRemainderOutput is returned if the remainder output can not be found.
	ErrMissingRemainderOutput = errors.New("can't find faucet remainder output")
	// ErrNotEnoughFunds is returned when not enough funds are left in the faucet.
	ErrNotEnoughFunds = errors.New("not enough funds in the faucet")
	// ErrConfirmationTimeoutExpired is returned when a faucet transaction was not confirmed in expected time.
	ErrConfirmationTimeoutExpired = errors.New("tx confirmation time expired")
	// ErrFundingCanceled is returned when a faucet funding is canceled.
	ErrFundingCanceled = errors.New("tx funding canceled")
	// ErrSupplyPreparationFailed is returned when a supply transaction preparation failed.
	ErrSupplyPreparationFailed = errors.New("supply transaction preparation failed")
	// ErrSplittingFundsFailed is returned when none of funding outputs has been confirmed during funds preparation.
	ErrSplittingFundsFailed = errors.New("none of funding outputs has been confirmed during funds preparation")
	// ErrNotEnoughSupplyOutputs if there are not enough supply outputs in the faucet.
	ErrNotEnoughSupplyOutputs = errors.New("not enough supply outputs to prepare more funds in the faucet")
)

var Parameters = &ParametersDefinition{}

Parameters contains the configuration parameters of the faucet plugin.

var (
	// Plugin is the "plugin" instance of the faucet application.
	Plugin *node.Plugin
)

Functions

func IsAddressBlackListed

func IsAddressBlackListed(address ledgerstate.Address) bool

IsAddressBlackListed returns if an address is blacklisted. adds the given address to the blacklist and removes the oldest blacklist entry if it would go over capacity.

func RemoveAddressFromBlacklist

func RemoveAddressFromBlacklist(address ledgerstate.Address)

RemoveAddressFromBlacklist removes an address from the blacklist.

Types

type FaucetOutput

type FaucetOutput struct {
	ID           ledgerstate.OutputID
	Balance      uint64
	Address      ledgerstate.Address
	AddressIndex uint64
}

FaucetOutput represents an output controlled by the faucet.

type ParametersDefinition

type ParametersDefinition struct {
	// Seed defines the base58 encoded seed the faucet uses.
	Seed string `usage:"the base58 encoded seed of the faucet, must be defined if this faucet is enabled"`

	// TokensPerRequest defines the amount of tokens the faucet should send for each request.
	TokensPerRequest int `default:"1000000" usage:"the amount of tokens the faucet should send for each request"`

	// MaxTransactionBookedAwaitTime defines the time to await for the transaction fulfilling a funding request
	// to become booked in the value layer.
	MaxTransactionBookedAwaitTime time.Duration `default:"5s" usage:"the max amount of time for a funding transaction to become booked in the value layer"`

	// PowDifficulty defines the PoW difficulty for faucet payloads.
	PowDifficulty int `default:"22" usage:"defines the PoW difficulty for faucet payloads"`

	// BlacklistCapacity holds the maximum amount the address blacklist holds.
	// An address for which a funding was done in the past is added to the blacklist and eventually is removed from it.
	BlacklistCapacity int `default:"10000" usage:"holds the maximum amount the address blacklist holds"`

	// SupplyOutputsCount is the number of supply outputs, and splitting transactions accordingly, the faucet prepares.
	SupplyOutputsCount int `default:"20" usage:"the number of supply outputs, and splitting transactions accordingly, the faucet prepares."`

	// SplittingMultiplier defines how many outputs each splitting transaction will have.
	// SplittingMultiplier * SupplyOutputsCount indicates how many funding outputs during funds replenishment.
	SplittingMultiplier int `default:"25" usage:"SplittingMultiplier defines how many outputs each supply transaction will have."`

	// GenesisTokenAmount is the total supply.
	GenesisTokenAmount uint64 `default:"1000000000000000" usage:"GenesisTokenAmount is the total supply."`
}

ParametersDefinition contains the definition of configuration parameters used by the faucet plugin.

type StateManager

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

StateManager manages the funds and outputs of the faucet. Can derive its state from a synchronized Tangle, can carry out funding requests, and prepares more funding outputs when needed.

func NewStateManager

func NewStateManager(
	tokensPerRequest uint64,
	seed *walletseed.Seed,
	supplyOutputsCount uint64,
	splittingMultiplier uint64,
	maxTxBookedTime time.Duration,
) *StateManager

NewStateManager creates a new state manager for the faucet.

func (*StateManager) DeriveStateFromTangle

func (s *StateManager) DeriveStateFromTangle(ctx context.Context) (err error)

DeriveStateFromTangle derives the faucet state from a synchronized Tangle.

• remainder output should always sit on address 0.
• supply outputs should be held on address indices 1-126
• funding outputs start from address index 127
• if no funding outputs are found, the faucet creates them from the remainder output.

func (*StateManager) FulFillFundingRequest

func (s *StateManager) FulFillFundingRequest(requestMsg *tangle.Message) (*tangle.Message, string, error)

FulFillFundingRequest fulfills a faucet request by spending the next funding output to the requested address. Mana of the transaction is pledged to the requesting node.