faucet

Documentation

Index

• Variables
• type BasicOutputsForAddressFunc
• type BlockMetadataFunc
• type EnqueueResponse
• type Events
• type Faucet
  • func New(daemon daemon.Daemon, blockMetadataFunc BlockMetadataFunc, ...) *Faucet
  • func (f *Faucet) ApplyNewLedgerUpdate(createdOutputs iotago.OutputIDs, consumedOutputs iotago.OutputIDs) error
  • func (f *Faucet) Enqueue(bech32Addr string) (*EnqueueResponse, error)
  • func (f *Faucet) FlushRequests()
  • func (f *Faucet) Info() (*InfoResponse, error)
  • func (f *Faucet) RunFaucetLoop(ctx context.Context, initDoneCallback func()) error
• type InfoResponse
• type IsNodeHealthyFunc
• type Metadata
• type Option
  • func WithAmount(amount uint64) Option
  • func WithBatchTimeout(timeout time.Duration) Option
  • func WithLogger(logger *logger.Logger) Option
  • func WithMaxAddressBalance(maxAddressBalance uint64) Option
  • func WithMaxOutputCount(maxOutputCount int) Option
  • func WithSmallAmount(smallAmount uint64) Option
  • func WithTagMessage(tagMessage string) Option
  • func WithTokenName(name string) Option
• type Options
• type ProtocolParamsFunc
• type SendBlockFunc
• type UTXOOutput

Variables

var (
	// ErrNothingToProcess is returned when there is no need to sweep or send funds.
	ErrNothingToProcess = errors.New("nothing to process")
)

Types

type BasicOutputsForAddressFunc

type BasicOutputsForAddressFunc = func(address iotago.Address) ([]UTXOOutput, error)

type BlockMetadataFunc

type BlockMetadataFunc = func(blockID iotago.BlockID) (*Metadata, error)

BlockMetadataFunc is a function to fetch the required metadata for a given block ID. This should return nil if the block is not found.

type EnqueueResponse

type EnqueueResponse struct {
	// The bech32 address.
	Address string `json:"address"`
	// The number of waiting requests in the queue.
	WaitingRequests int `json:"waitingRequests"`
}

EnqueueResponse defines the response of a POST RouteFaucetEnqueue REST API call.

type Events

type Events struct {
	// Fired when a faucet block is issued.
	IssuedBlock *event.Event1[iotago.BlockID]
	// SoftError is triggered when a soft error is encountered.
	SoftError *event.Event1[error]
}

Events are the events issued by the faucet.

type Faucet

type Faucet struct {
	// lock used to secure the state of the faucet.
	syncutils.Mutex
	// the logger used to log events.
	*logger.WrappedLogger

	// events of the faucet.
	Events *Events
	// contains filtered or unexported fields
}

Faucet is used to issue transaction to users that requested funds via a REST endpoint.

func New

func New(
	daemon daemon.Daemon,
	blockMetadataFunc BlockMetadataFunc,
	collectOutputsFunc BasicOutputsForAddressFunc,
	nodeHealthyFunc IsNodeHealthyFunc,
	protocolParamsFunc ProtocolParamsFunc,
	address iotago.Address,
	addressSigner iotago.AddressSigner,
	sendBlockFunc SendBlockFunc,
	opts ...Option) *Faucet

New creates a new faucet instance.

func (*Faucet) ApplyNewLedgerUpdate

func (f *Faucet) ApplyNewLedgerUpdate(createdOutputs iotago.OutputIDs, consumedOutputs iotago.OutputIDs) error

ApplyNewLedgerUpdate applies a new ledger update to the faucet. Pending transactions are checked for their current state and either removed, readded, or left pending. If a conflict is found, all remaining pending transactions are readded to the queue. no need to ReadLockLedger, because this function should be called from milestone confirmation event anyway.

func (*Faucet) Enqueue

func (f *Faucet) Enqueue(bech32Addr string) (*EnqueueResponse, error)

Enqueue adds a new faucet request to the queue.

func (*Faucet) FlushRequests

func (f *Faucet) FlushRequests()

FlushRequests stops current batching of faucet requests.

func (*Faucet) Info

func (f *Faucet) Info() (*InfoResponse, error)

Info returns the used faucet address and remaining balance.

func (*Faucet) RunFaucetLoop

func (f *Faucet) RunFaucetLoop(ctx context.Context, initDoneCallback func()) error

RunFaucetLoop collects unspent outputs on the faucet address and batches the requests from the queue.

type InfoResponse

type InfoResponse struct {
	// Whether the faucet is healthy.
	IsHealthy bool `json:"isHealthy"`
	// The bech32 address of the faucet.
	Address string `json:"address"`
	// The remaining balance of faucet.
	Balance uint64 `json:"balance"`
	// The name of the token of the faucet.
	TokenName string `json:"tokenName"`
	// The Bech32 human readable part of the the faucet.
	Bech32HRP iotago.NetworkPrefix `json:"bech32Hrp"`
}

InfoResponse defines the response of a GET RouteFaucetInfo REST API call.

type IsNodeHealthyFunc

type IsNodeHealthyFunc = func() bool

IsNodeHealthyFunc is a function to query if the used node is synced.

type Metadata

type Metadata struct {
	IsReferenced   bool
	IsConflicting  bool
	ShouldReattach bool
}

Metadata contains the basic block metadata required by the faucet.

type Option

type Option func(opts *Options)

Option is a function setting a faucet option.

func WithAmount

func WithAmount(amount uint64) Option

WithAmount defines the amount of funds the requester receives.

func WithBatchTimeout

func WithBatchTimeout(timeout time.Duration) Option

WithBatchTimeout sets the maximum duration for collecting faucet batches.

func WithLogger

func WithLogger(logger *logger.Logger) Option

WithLogger enables logging within the faucet.

func WithMaxAddressBalance

func WithMaxAddressBalance(maxAddressBalance uint64) Option

WithMaxAddressBalance defines the maximum allowed amount of funds on the target address. If there are more funds already, the faucet request is rejected.

func WithMaxOutputCount

func WithMaxOutputCount(maxOutputCount int) Option

WithMaxOutputCount defines the maximum output count per faucet block.

func WithSmallAmount

func WithSmallAmount(smallAmount uint64) Option

WithSmallAmount defines the amount of funds the requester receives if the target address has more funds than the faucet amount and less than maximum.

func WithTagMessage

func WithTagMessage(tagMessage string) Option

WithTagMessage defines the faucet transaction tag payload.

func WithTokenName

func WithTokenName(name string) Option

WithTokenName sets the name of the token.

type Options

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

Options define options for the faucet.

type ProtocolParamsFunc

type ProtocolParamsFunc = func() *iotago.ProtocolParameters

ProtocolParamsFunc is a function to query the node for the latest protocol parameters.

type SendBlockFunc

type SendBlockFunc = func(ctx context.Context, block *iotago.Block) (iotago.BlockID, error)

SendBlockFunc is a function which sends a block to the network.

type UTXOOutput

type UTXOOutput struct {
	OutputID iotago.OutputID
	Output   *iotago.BasicOutput
}