faucet

README

Faucet

The faucet provides a way to deposit/mint new funds for zeta builtin assets (for now, maybe more will be supported later on). The faucet takes the form of an http server exposing a REST API which triggers new chain events on the Zeta.

In order to control exactly who is allowed to broadcast events to the network, the node configuration contains a list of public keys allowed to broadcast chain events. The faucet's keypairs must be on this list before it can start allocating assets.

Request rate limiting

To prevent the users to request unlimited amount of funds, the CoolDown field in the configuration allow operator to specify a minimum amount of time between 2 request for funds.

Spam prevention

In order to prevent spam from non-validator node, the faucet needs to be connected to a validator node.

Initialisation

The faucet exists as its own entity next to the zeta node, with its own configuration file. It can be initialised by running the following:

zeta faucet init -f --update-in-place

this will create a new config file that can be found at ZETA_HOME/faucet/config.toml. Providing the --update-in-place flag will cause the command to automatically update the Event Forward section in the main zeta config with the public key of the faucet:

[EvtForward]
  Level = "Info"
  RetryRate = "10s"
  BlockchainQueueAllowlist = ["c65af95865b4e970c48860f5c854c5ca8f340416372f9e72a98ff09e365aa0cf"]

Run the faucet

The faucet can be started using the core zeta command line:

zeta faucet run

You can run the help for more details explanation on the available flags:

zeta faucet run -h

API

Get new funds

Request

POST /api/v1/mint

{
	"party": "party_pub_key",
	"amount": "amount_to_be_deposited",
	"asset": "asset_id"
}

Response

{
	"success": true
}

Note: the response does not indicate that the deposit succeeded, but that the request was send to the Zeta network. It may take a few blocks before your the assets are deposited.

Documentation

Index

• Variables
• type Config
  • func NewDefaultConfig() Config
• type ConfigLoader
  • func InitialiseConfigLoader(zetaPaths paths.Paths) (*ConfigLoader, error)
  • func (l *ConfigLoader) ConfigExists() (bool, error)
  • func (l *ConfigLoader) ConfigFilePath() string
  • func (l *ConfigLoader) GetConfig() (*Config, error)
  • func (l *ConfigLoader) RemoveConfig()
  • func (l *ConfigLoader) SaveConfig(cfg *Config) error
• type Faucet
  • func NewService(log *logging.Logger, zetaPaths paths.Paths, cfg Config, passphrase string) (*Faucet, error)
  • func (f *Faucet) Health(w http.ResponseWriter, r *http.Request, _ httprouter.Params)
  • func (f *Faucet) Mint(w http.ResponseWriter, r *http.Request, _ httprouter.Params)
  • func (f *Faucet) Start() error
  • func (f *Faucet) Stop() error
• type HTTPError
  • func (e HTTPError) Error() string
• type InitialisationResult
  • func Initialise(zetaPaths paths.Paths, passphrase string, rewrite bool) (*InitialisationResult, error)
• type MintRequest
• type MintResponse
• type NodeConfig
• type WalletGenerationResult
• type WalletLoader
  • func InitialiseWalletLoader(zetaPaths paths.Paths) (*WalletLoader, error)
  • func (l *WalletLoader) GenerateWallet(passphrase string) (*WalletGenerationResult, error)

Variables

var (
	// ErrNotABuiltinAsset is raised when a party try to top up for a non builtin asset.
	ErrNotABuiltinAsset = errors.New("asset is not a builtin asset")

	// ErrAssetNotFound is raised when an asset id is not found.
	ErrAssetNotFound = errors.New("asset was not found")

	// ErrInvalidMintAmount is raised when the mint amount is too high.
	ErrInvalidMintAmount = errors.New("mint amount is invalid")

	HealthCheckResponse = struct {
		Success bool `json:"success"`
	}{true}
)

var ErrFaucetConfigAlreadyExists = errors.New("faucet configuration already exists")

var ErrFaucetHasNoKeyInItsWallet = errors.New("faucet has no key in its wallet")

ErrFaucetHasNoKeyInItsWallet is returned when trying to get the wallet key of the faucet whereas no key has been generated or added to the faucet's wallet.

var ErrInvalidRequest = newError("invalid request")

Types

type Config

type Config struct {
	Level      encoding.LogLevel      `long:"level" description:"Log level"`
	RateLimit  vghttp.RateLimitConfig `group:"RateLimit" namespace:"rateLimit"`
	WalletName string                 `long:"wallet-name" description:"Name of the wallet to use to sign events"`
	Port       int                    `long:"port" description:"Listen for connections on port <port>"`
	IP         string                 `long:"ip" description:"Bind to address <ip>"`
	Node       NodeConfig             `group:"Node" namespace:"node"`
}

func NewDefaultConfig

func NewDefaultConfig() Config

type ConfigLoader

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

func InitialiseConfigLoader

func InitialiseConfigLoader(zetaPaths paths.Paths) (*ConfigLoader, error)

func (*ConfigLoader) ConfigExists

func (l *ConfigLoader) ConfigExists() (bool, error)

func (*ConfigLoader) ConfigFilePath

func (l *ConfigLoader) ConfigFilePath() string

func (*ConfigLoader) GetConfig

func (l *ConfigLoader) GetConfig() (*Config, error)

func (*ConfigLoader) RemoveConfig

func (l *ConfigLoader) RemoveConfig()

func (*ConfigLoader) SaveConfig

func (l *ConfigLoader) SaveConfig(cfg *Config) error

type Faucet

type Faucet struct {
	*httprouter.Router
	// contains filtered or unexported fields
}

func NewService

func NewService(log *logging.Logger, zetaPaths paths.Paths, cfg Config, passphrase string) (*Faucet, error)

func (*Faucet) Health

func (f *Faucet) Health(w http.ResponseWriter, r *http.Request, _ httprouter.Params)

func (*Faucet) Mint

func (f *Faucet) Mint(w http.ResponseWriter, r *http.Request, _ httprouter.Params)

func (*Faucet) Start

func (f *Faucet) Start() error

func (*Faucet) Stop

func (f *Faucet) Stop() error

type HTTPError

type HTTPError struct {
	ErrorStr string `json:"error"`
}

func (HTTPError) Error

func (e HTTPError) Error() string

type InitialisationResult

type InitialisationResult struct {
	Wallet         *WalletGenerationResult
	ConfigFilePath string
}

func Initialise

func Initialise(zetaPaths paths.Paths, passphrase string, rewrite bool) (*InitialisationResult, error)

type MintRequest

type MintRequest struct {
	Party  string `json:"party"`
	Amount string `json:"amount"`
	Asset  string `json:"asset"`
}

type MintResponse

type MintResponse struct {
	Success bool `json:"success"`
}

type NodeConfig

type NodeConfig struct {
	Port    int    `long:"port" description:"Connect to Node on port <port>"`
	IP      string `long:"ip" description:"Connect to Node on address <ip>"`
	Retries uint64 `long:"retries" description:"Connection retries before fail"`
}

type WalletGenerationResult

type WalletGenerationResult struct {
	Mnemonic  string
	FilePath  string
	Name      string
	PublicKey string
}

type WalletLoader

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

func InitialiseWalletLoader

func InitialiseWalletLoader(zetaPaths paths.Paths) (*WalletLoader, error)

func (*WalletLoader) GenerateWallet

func (l *WalletLoader) GenerateWallet(passphrase string) (*WalletGenerationResult, error)