faucet

Documentation

Index

• Constants
• Variables
• func IsAddressBlackListed(address ledgerstate.Address) bool
• func IsFaucetReq(msg *tangle.Message) bool
• func PayloadUnmarshaler(data []byte) (payload payload.Payload, err error)
• func Plugin() *node.Plugin
• func RemoveAddressFromBlacklist(address ledgerstate.Address)
• type FaucetOutput
• type Request
  • func FromBytes(bytes []byte) (result *Request, consumedBytes int, err error)
  • func NewRequest(addr ledgerstate.Address, powTarget int, ...) (*Request, error)
  • func (p *Request) AccessManaPledgeID() identity.ID
  • func (p *Request) Address() ledgerstate.Address
  • func (p *Request) Bytes() []byte
  • func (p *Request) ConsensusManaPledgeID() identity.ID
  • func (p *Request) String() string
  • func (p *Request) Type() payload.Type
• type StateManager
  • func Faucet() *StateManager
  • func NewStateManager(tokensPerRequest uint64, seed *walletseed.Seed, preparedOutputsCount uint64, ...) *StateManager
  • func (s *StateManager) DeriveStateFromTangle(startIndex int) (err error)
  • func (s *StateManager) FulFillFundingRequest(requestMsg *tangle.Message) (m *tangle.Message, txID string, err error)
  • func (s *StateManager) FundingOutputsCount() int

Examples

• Request

Constants

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

	// WaitForSync defines the time to wait for being in sync.
	WaitForSync = 5 * time.Second

	// CfgFaucetSeed defines the base58 encoded seed the faucet uses.
	CfgFaucetSeed = "faucet.seed"
	// CfgFaucetTokensPerRequest defines the amount of tokens the faucet should send for each request.
	CfgFaucetTokensPerRequest = "faucet.tokensPerRequest"
	// CfgFaucetMaxTransactionBookedAwaitTimeSeconds defines the time to await for the transaction fulfilling a funding request
	// to become booked in the value layer.
	CfgFaucetMaxTransactionBookedAwaitTimeSeconds = "faucet.maxTransactionBookedAwaitTimeSeconds"
	// CfgFaucetPoWDifficulty defines the PoW difficulty for faucet payloads.
	CfgFaucetPoWDifficulty = "faucet.powDifficulty"
	// CfgFaucetBlacklistCapacity 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.
	CfgFaucetBlacklistCapacity = "faucet.blacklistCapacity"
	// CfgFaucetPreparedOutputsCount is the number of outputs the faucet prepares for requests.
	CfgFaucetPreparedOutputsCount = "faucet.preparedOutputsCounts"
	// CfgFaucetStartIndex defines from which address index the faucet should start gathering outputs.
	CfgFaucetStartIndex = "faucet.startIndex"
)

const (
	// GenesisTokenAmount is the total supply.
	GenesisTokenAmount = 1000000000000000

	// RemainderAddressIndex is the RemainderAddressIndex.
	RemainderAddressIndex = 0

	// MinimumFaucetBalance defines the minimum token amount required, before the faucet stops operating.
	MinimumFaucetBalance = 0.1 * GenesisTokenAmount

	// MaxFaucetOutputsCount defines the max outputs count for the Facuet 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
)

const (
	// ObjectName defines the name of the faucet object (payload).
	ObjectName = "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")
)

var (
	Type = payload.NewType(2, ObjectName, PayloadUnmarshaler)
)

Type represents the identifier for the faucet Request type.

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 IsFaucetReq

func IsFaucetReq(msg *tangle.Message) bool

IsFaucetReq checks if the message is faucet payload.

func PayloadUnmarshaler

func PayloadUnmarshaler(data []byte) (payload payload.Payload, err error)

PayloadUnmarshaler sets the generic unmarshaler.

func Plugin

func Plugin() *node.Plugin

Plugin returns the plugin instance of the faucet plugin.

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 Request

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

Request represents a faucet request which contains an address for the faucet to send funds to.

Example

keyPair := ed25519.GenerateKeyPair()
address := ledgerstate.NewED25519Address(keyPair.PublicKey)
local := identity.NewLocalIdentity(keyPair.PublicKey, keyPair.PrivateKey)
emptyID := identity.ID{}

// 1. create faucet payload
faucetRequest, err := NewRequest(address, 4, emptyID, emptyID)
if err != nil {
	panic(err)
}

// 2. build actual message
tx := tangle.NewMessage(
	[]tangle.MessageID{tangle.EmptyMessageID},
	[]tangle.MessageID{},
	time.Now(),
	local.PublicKey(),
	0,
	faucetRequest,
	0,
	ed25519.EmptySignature,
)
fmt.Println(tx.String())

func FromBytes

func FromBytes(bytes []byte) (result *Request, consumedBytes int, err error)

FromBytes parses the marshaled version of a Request into a request object.

func NewRequest

func NewRequest(addr ledgerstate.Address, powTarget int, accessManaPledgeID, consensusManaPledgeID identity.ID) (*Request, error)

NewRequest is the constructor of a Request and creates a new Request object from the given details.

func (*Request) AccessManaPledgeID

func (p *Request) AccessManaPledgeID() identity.ID

AccessManaPledgeID returns the access mana pledge ID of the faucet request.

func (*Request) Address

func (p *Request) Address() ledgerstate.Address

Address returns the address of the faucet Request.

func (*Request) Bytes

func (p *Request) Bytes() []byte

Bytes marshals the faucet Request payload into a sequence of bytes.

func (*Request) ConsensusManaPledgeID

func (p *Request) ConsensusManaPledgeID() identity.ID

ConsensusManaPledgeID returns the consensus mana pledge ID of the faucet request.

func (*Request) String

func (p *Request) String() string

String returns a human readable version of faucet Request payload (for debug purposes).

func (*Request) Type

func (p *Request) Type() payload.Type

Type returns the type of the faucet Request.

type StateManager

type StateManager struct {

	// ensures that only one goroutine can work on the stateManager at any time
	sync.RWMutex
	// 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 Faucet

func Faucet() *StateManager

Faucet gets the faucet component instance the faucet plugin has initialized.

func NewStateManager

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

NewStateManager creates a new state manager for the faucet.

func (*StateManager) DeriveStateFromTangle

func (s *StateManager) DeriveStateFromTangle(startIndex int) (err error)

DeriveStateFromTangle derives the faucet state from a synchronized Tangle.

• startIndex defines from which address index to start look for prepared outputs.
• remainder output should always sit on address 0.
• if no funding outputs are found, the faucet creates them from the remainder output.

func (*StateManager) FulFillFundingRequest

func (s *StateManager) FulFillFundingRequest(requestMsg *tangle.Message) (m *tangle.Message, txID string, err 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.

func (*StateManager) FundingOutputsCount

func (s *StateManager) FundingOutputsCount() int

FundingOutputsCount returns the number of available outputs that can be used to fund a request.