faucet

README

⚛️ Tendermint2 Faucet ⚛️

Overview

faucet is a versatile command-line interface (CLI) tool and library designed to effortlessly deploy a faucet server for Gno Tendermint 2 networks.

Key Features

Customizability

This faucet is highly customizable, allowing you to tailor it to the specific needs of your Tendermint 2 network. You can easily configure token types, distribution limits, and other parameters to suit your requirements.

Batch JSON Request Support

The faucet supports batch JSON requests, making it efficient for mass token distribution. You can submit multiple requests in a single batch, reducing the overhead of individual requests.

Extensibility

The faucet is designed with extensibility in mind. You can extend its functionality through middleware and custom handlers. This means you can integrate additional features or connect it to external systems seamlessly, like a rate limiting system.

Getting Started

As a binary

To get started with the Tendermint 2 Faucet, follow these steps:

1. Clone this repository to your local machine:

git clone github.com/gnolang/faucet

1. Build out the binary

To build out the binary, run the following command:

make build

1. Run the faucet

To run the faucet, start the built binary:

./build/faucet --mnemonic "<faucet_account_mnemonic>"

The provided mnemonic will be used to derive accounts which will be used to serve funds to users. Make sure that the accounts derived from it are well funded.

It should print something like the following. (Note the port number at the end.)

2024-01-11T12:47:27.826+0100	INFO	cmd/logger.go:17	faucet started at [::]:8545

1. To send coins to a single account, in a new terminal enter the following (change to the correct recipient address):

curl --location --request POST 'http://localhost:8545' --header 'Content-Type: application/json' --data '{"To": "g1juz2yxmdsa6audkp6ep9vfv80c8p5u76e03vvh"}'

1. To ensure the faucet is listening to requests, you can ping the health endpoint:

curl --location --request GET 'http://localhost:8545/health'

As a library

To add faucet to your Go project, simply run:

go get github.com/gnolang/faucet

To use the faucet, you can set it up as such:

package main

import (
	// ...
	"context"

	"github.com/gnolang/faucet/client/http"
	"github.com/gnolang/faucet/estimate/static"
)

func main() {
	// Create the faucet
	f, err := NewFaucet(
		static.New(...), // gas estimator
		http.NewClient(...), // remote address 
        )

	// The faucet is controlled through a top-level context
	ctx, cancelFn := context.WithCancel(context.Background())

	// Start the faucet
	go f.Serve(ctx)

	// Close the faucet
	cancelFn()
}

What kind of extensibility?

Middleware

Middleware functions can be added to extend the faucet's functionality. For example, you can add middleware to authenticate users, log requests, or implement rate limiting.

Custom Handlers

Custom request handlers can be created to handle specific actions or integrate with external systems. For instance, you can create a custom handler to trigger additional actions when tokens are distributed, such as sending notifications.

Documentation

Index

• type Faucet
  • func NewFaucet(estimator estimate.Estimator, client client.Client, opts ...Option) (*Faucet, error)
  • func (f *Faucet) Serve(ctx context.Context) error
• type Handler
• type Middleware
• type Option
  • func WithConfig(c *config.Config) Option
  • func WithHandlers(handlers []Handler) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMiddlewares(middlewares []Middleware) Option
  • func WithPrepareTxMessageFn(prepareTxMsgFn PrepareTxMessageFn) Option
• type PrepareCfg
• type PrepareTxMessageFn
• type Request
• type Requests
• type Response
• type Responses

Types

type Faucet

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

Faucet is a standard Gno faucet

func NewFaucet

func NewFaucet(
	estimator estimate.Estimator,
	client client.Client,
	opts ...Option,
) (*Faucet, error)

NewFaucet creates a new instance of the Gno faucet server

func (*Faucet) Serve

func (f *Faucet) Serve(ctx context.Context) error

Serve serves the Gno faucet [BLOCKING]

type Handler

type Handler struct {
	HandlerFunc http.HandlerFunc
	Pattern     string
}

Handler defines a faucet handler

type Middleware

type Middleware func(next http.Handler) http.Handler

Middleware is the faucet middleware func

type Option

type Option func(f *Faucet)

func WithConfig

func WithConfig(c *config.Config) Option

WithConfig specifies the config for the faucet

func WithHandlers

func WithHandlers(handlers []Handler) Option

WithHandlers specifies the HTTP handlers for the faucet

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger specifies the logger for the faucet

func WithMiddlewares

func WithMiddlewares(middlewares []Middleware) Option

WithMiddlewares specifies the request middlewares for the faucet

func WithPrepareTxMessageFn

func WithPrepareTxMessageFn(prepareTxMsgFn PrepareTxMessageFn) Option

WithPrepareTxMessageFn specifies the faucet transaction message constructor

type PrepareCfg

type PrepareCfg struct {
	SendAmount  std.Coins      // the amount to be sent
	FromAddress crypto.Address // the faucet address
	ToAddress   crypto.Address // the beneficiary address
}

PrepareCfg specifies the tx prepare configuration

type PrepareTxMessageFn

type PrepareTxMessageFn func(PrepareCfg) std.Msg

PrepareTxMessageFn is the callback method that constructs the faucet fund transaction message

type Request

type Request struct {
	To     string `json:"to"`
	Amount string `json:"amount"`
}

Request is a single Faucet transfer request

type Requests

type Requests []Request

type Response

type Response struct {
	Result string `json:"result"`
	Error  string `json:"error,omitempty"`
}

Response is a single Faucet transfer response

type Responses

type Responses []Response