faucet

package
v0.39.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 5, 2026 License: MIT Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrClaimRejected = errors.New("faucet rejected claim")

ErrClaimRejected distinguishes an explicit rejection from an uncertain transport failure.

Functions

This section is empty.

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 requests the faucet's minimum drop for address.

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.

func (*Client) ClaimAmount added in v0.39.1

func (c *Client) ClaimAmount(ctx context.Context, address string, amountWei *big.Int) (result *Result, err error)

ClaimAmount mines enough shares for amountWei and asks the faucet to pay exactly that amount. A nil amount requests the faucet's minimum drop.

func (*Client) ClaimAmountWithProgress added in v0.39.1

func (c *Client) ClaimAmountWithProgress(ctx context.Context, address string, amountWei *big.Int, progress func(Progress)) (result *Result, err error)

ClaimAmountWithProgress is ClaimAmount with progress notifications for server jobs.

func (*Client) PollClaim added in v0.39.1

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

PollClaim reads a session once. A nil result with no error means still pending.

type HTTPError added in v0.39.1

type HTTPError struct {
	Status int
	Body   string
}

HTTPError preserves an upstream status so callers can distinguish faucet throttling from transport failures.

func (*HTTPError) Error added in v0.39.1

func (e *HTTPError) Error() string

type Progress added in v0.39.1

type Progress struct {
	Session   string
	Submitted bool
	Rejected  bool
	Result    *Result
}

Progress exposes the session and submission boundary without treating broadcast as inclusion.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL