faucet

Documentation

Overview

Package faucet mines a PoWFaucet agent-REST challenge and claims the reward for a target address, with no browser, WebSocket, or captcha.

It requires the faucet's PoW to be Argon2id (type 2) at version 19 — the standard variant implemented by golang.org/x/crypto/argon2 — so mining runs natively with no cgo and no external dependency.

Index

• type Client
  • func New(baseURL string, httpClient *http.Client) *Client
  • func NewWithTransport(t Transport) *Client
  • func (c *Client) Claim(ctx context.Context, address string) (*Result, error)
• type Result
• type Transport

Types

type Client

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

Client drives the PoWFaucet agent-REST flow over a Transport.

func New

func New(baseURL string, httpClient *http.Client) *Client

New returns a Client that talks directly to a faucet base URL, e.g. https://faucet-agents.<network>.ethpandaops.io. Used by tests and direct use.

func NewWithTransport

func NewWithTransport(t Transport) *Client

NewWithTransport returns a Client that issues requests through t (e.g. the proxy-routed transport used by the evm.faucet server operation).

func (*Client) Claim

func (c *Client) Claim(ctx context.Context, address string) (*Result, error)

Claim runs the full agent flow for address: start a session, mine PoW shares until the balance covers the minimum drop, close the session, submit the claim, and poll until the faucet reports the claim transaction submitted. It returns the claim transaction hash.

The faucet flips claimStatus to "confirmed" once it has broadcast the transaction, which can precede inclusion — so Result.Confirmed is left false here. Callers with chain access should wait for the receipt themselves.

type Result

type Result struct {
	Session     string `json:"session"`
	Target      string `json:"target"`
	ClaimHash   string `json:"claim_hash"`
	AmountWei   string `json:"amount_wei"`
	Confirmed   bool   `json:"confirmed"`
	BlockNumber uint64 `json:"block_number,omitempty"`
}

Result is the outcome of a successful claim. Confirmed and BlockNumber are filled in by the caller once the claim transaction has an on-chain receipt; the faucet flow itself only learns that the faucet broadcast it.

type Transport

type Transport interface {
	Do(ctx context.Context, method, path string, body []byte) (respBody []byte, status int, err error)
}

Transport issues one faucet HTTP request and returns the response body and status code. It lets the mining flow run either against a faucet URL directly (tests, CLI) or through the panda proxy — the only authenticated network path in production, so the faucet needs no public surface.