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.

Default endpoint (root)

The faucet adopts the JSON-RPC 2.0 standard for requests / responses.

By default, the / endpoint is the home of the drip method, to handle faucet drips. The first parameter is the beneficiary address, and the second one is the string representation of the drip amount (std.Coins).

This can of course be overwritten with custom handling logic by the faucet creator (see below).

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "drip",
  "params": [
    "g1e6gxg5tvc55mwsn7t7dymmlasratv7mkv0rap2",
    "1000ugnot"
  ]
}

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 '{ "jsonrpc": "2.0", "id": 0, "method": "drip", "params": [ "g1e6gxg5tvc55mwsn7t7dymmlasratv7mkv0rap2", "1000ugnot" ] }'

1. To ensure the faucet is listening to requests, you can ping the health endpoint (returns a simple status 200):

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

• Constants
• 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 HandlerFunc
• type Middleware
• type Option
  • func WithConfig(c *config.Config) Option
  • func WithHTTPMiddlewares(middlewares []func(http.Handler) http.Handler) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithMiddlewares(middlewares []Middleware) Option
  • func WithPrepareTxMessageFn(prepareTxMsgFn PrepareTxMessageFn) Option
  • func WithRPCHandlers(handlers []Handler) Option
• type PrepareCfg
• type PrepareTxMessageFn

Constants

const DefaultDripMethod = "drip" // the default JSON-RPC method for a faucet drip

const JSONMimeType = "application/json"

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 HandlerFunc
	Pattern     string
}

Handler defines a faucet pattern handler

type HandlerFunc

type HandlerFunc func(ctx context.Context, req *spec.BaseJSONRequest) *spec.BaseJSONResponse

HandlerFunc is the custom faucet request handler

type Middleware

type Middleware func(next HandlerFunc) HandlerFunc

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 WithHTTPMiddlewares

func WithHTTPMiddlewares(middlewares []func(http.Handler) http.Handler) Option

WithHTTPMiddlewares specifies the http request middlewares for the faucet. Middlewares are applied for each endpoint

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 rpc request middlewares for the faucet. Middlewares are applied for each endpoint

func WithPrepareTxMessageFn

func WithPrepareTxMessageFn(prepareTxMsgFn PrepareTxMessageFn) Option

WithPrepareTxMessageFn specifies the faucet transaction message constructor

func WithRPCHandlers

func WithRPCHandlers(handlers []Handler) Option

WithRPCHandlers specifies the HTTP handlers for the faucet

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