faucet

README

Faucet

The faucet provides a way to deposit/mint new funds for vega 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 Vega.

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 vega node, with its own configuration file. It can be initialised by running the following:

vega faucet init -f --update-in-place

this will create a new config file that can be found at VEGA_HOME/faucet/config.toml. Providing the --update-in-place flag will cause the command to automatically update the Event Forward section in the main vega 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 vega command line:

vega faucet run

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

vega 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 Vega 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(vegaPaths 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, vegaPaths 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(vegaPaths paths.Paths, passphrase string, rewrite bool) (*InitialisationResult, error)
• type MintRequest
• type MintResponse
• type NodeConfig
• type WalletGenerationResult
  • func GenerateWallet(vegaPaths paths.Paths, 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      `description:"Log level"                                long:"level"`
	RateLimit  vghttp.RateLimitConfig `group:"RateLimit"                                      namespace:"rateLimit"`
	WalletName string                 `description:"Name of the wallet to use to sign events" long:"wallet-name"`
	Port       int                    `description:"Listen for connections on port <port>"    long:"port"`
	IP         string                 `description:"Bind to address <ip>"                     long:"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(vegaPaths 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, vegaPaths 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(vegaPaths 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    `description:"Connect to Node on port <port>"  long:"port"`
	IP      string `description:"Connect to Node on address <ip>" long:"ip"`
	Retries uint64 `description:"Connection retries before fail"  long:"retries"`
}

type WalletGenerationResult

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

func GenerateWallet

func GenerateWallet(vegaPaths paths.Paths, passphrase string) (*WalletGenerationResult, error)