Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

faucet/v0 package

Overview

Package faucet hands a small amount of GNOT to someone who has none, on the record, in two calls that are meant to travel in one transaction.

The chain's own faucet is gated and the people who most need a first coin are exactly the people who cannot ask for one: an empty account cannot pay the gas to call anything. So somebody else files the request on their behalf, an approver releases it, and both halves are on chain with a reason attached.

Why two calls and not one bank send

Request is permissionless and Approve is not. Splitting them puts the ask, its reason and who made it on chain even when the answer is no, and makes every payout name the request it settles. A plain send would leave a transfer with no why, and no way to refuse one in public.

They are meant to be sent together. A tm2 transaction carries a LIST of messages, runs them in order and stops at the first failure, and a failed transaction writes none of their state: only the fee and the sequence survive (tm2/pkg/sdk/baseapp.go, runMsgs and WriteCheckpoint). So a request and its approval in one transaction either both happen or neither does.

The id the second message cannot know yet

Approve names a request by id, and message 2 of a transaction cannot read what message 1 returned. A caller therefore reads NextID first and writes that number into the approval, which is a race: another Request landing in between shifts the id under it, and the approval would pay a stranger.

That is why Approve also takes the recipient and the amount it believes it is approving, and refuses when the stored request disagrees. The race then costs a failed transaction instead of the wrong person's rent.

What bounds the damage

The faucet spends only what has been sent to its own address, never the approver's balance, so the float is the ceiling and topping it up is a deliberate act. MaxPerRequest caps any single payout under that, and Withdraw takes the float back.

Functions

AddApprover

func AddApprover(cur realm, addr string)

AddApprover lets addr approve and deny. Owner only.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "AddApprover" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "AddApprover" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Approve

func Approve(cur realm, id int64, wantTo string, wantAmount int64)

Approve pays request id out of the float. Approvers only.

wantTo and wantAmount are not redundant: they are what makes it safe to put Approve in the same transaction as the Request it settles. The id has to be guessed from NextID before either message is signed, and this call refuses when the request sitting at that id is not the one the caller described.

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Approve" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Balance

func Balance() int64

Balance is what the faucet can actually pay out right now.

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.Balance()"

Result

DeniedCount

func DeniedCount() int64

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.DeniedCount()"

Result

Deny

func Deny(cur realm, id int64, why string)

Deny closes a request unpaid, with a reason that goes on the page. The reason is the whole value of denying in public rather than ignoring it.

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Deny" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Deny" -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Fund

func Fund(cur realm)

Fund credits the ugnot sent with the call to the float. Coins sent straight to [Address] land there too; they just do not emit an event.

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Fund" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Fund" -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

IsApprover

func IsApprover(addr string) bool

IsApprover reports whether addr may approve or deny.

Param

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.IsApprover()"

Result

MaxPerRequest

func MaxPerRequest() int64

MaxPerRequest is the current cap on a single payout, in ugnot.

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.MaxPerRequest()"

Result

NextID

func NextID() int64

NextID is the id the next Request will be given.

Read it to build the Approve half of a two-message transaction, and pass the recipient and amount to Approve so that a request landing in between fails the transaction instead of being paid by it.

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.NextID()"

Result

Pending

func Pending() int64

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.Pending()"

Result

ReceivedBy

func ReceivedBy(addr string) int64

ReceivedBy is everything this faucet has ever paid to addr.

Param

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.ReceivedBy()"

Result

RemoveApprover

func RemoveApprover(cur realm, addr string)

RemoveApprover revokes addr. Owner only, and the Owner cannot be removed: a faucet with no approver is a faucet with a locked float.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "RemoveApprover" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "RemoveApprover" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Render

func Render(path string) string

Render shows the float, the open asks and everything already decided.

Two paths: "" is the whole board, "req/<id>" is one request.

Every string on this page that a caller typed goes through sanitize before it is concatenated. A reason is arbitrary text from an arbitrary account and Render output is markdown that gnoweb parses, so an unescaped one can plant a link, an image beacon or gnoweb chrome on a page the realm is signing for. This realm's path is permanent, so that bug could only ever be fixed at a new path.

Param

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.Render()"

Result

Request

func Request(cur realm, to string, amount int64, reason string) int64

Request files an ask for amount ugnot to be paid to `to`, and returns its id. Anyone may file, for anyone, which is the point: the account that needs the coins is the one that cannot pay to ask for them.

Filing costs the filer gas and nothing else, and moves no money.

Params

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Request" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Request" -args $'' -args $'' -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Requests

func Requests() int

Requests is how many requests have ever been filed.

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.Requests()"

Result

SentCount

func SentCount() int64

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.SentCount()"

Result

SetMaxPerRequest

func SetMaxPerRequest(cur realm, amount int64)

SetMaxPerRequest changes the per-request cap, in ugnot. Owner only.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "SetMaxPerRequest" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "SetMaxPerRequest" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx
  

Status

func Status(id int64) string

Status is the state of request id: "pending", "sent", "denied", or "" when no such request exists.

Param

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.Status()"

Result

TotalSent

func TotalSent() int64

TotalSent, SentCount, DeniedCount and Pending are the running tallies.

Command

gnokey query vm/qeval -remote "https://rpc.gno.land" -data "gno.land/r/moul/faucet/v0.TotalSent()"

Result

Withdraw

func Withdraw(cur realm, amount int64)

Withdraw returns amount ugnot of the float to the Owner. Owner only.

This is what makes funding the faucet reversible, and it is deliberately not payable to an arbitrary address: an approver who wanted to move money somewhere has to file a request for it like everyone else.

Param

Command

# WARNING: This command is running in an INSECURE mode.
# It is strongly recommended to use a hardware device for signing
# and avoid trusting any computer connected to the internet,
# as your private keys could be exposed.

gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Withdraw" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -chainid "gnoland-1" -remote "https://rpc.gno.land" ADDRESSgnokey query -remote "https://rpc.gno.land" auth/accounts/ADDRESS
gnokey maketx call -pkgpath "gno.land/r/moul/faucet/v0" -func "Withdraw" -args $'' -gas-fee 1000000ugnot -gas-wanted 1_000_000_000 -send "" -broadcast=false ADDRESS > call.tx
gnokey sign -tx-path call.tx -chainid "gnoland-1" -account-number ACCOUNTNUMBER -account-sequence SEQUENCENUMBER ADDRESS
gnokey broadcast -remote "https://rpc.gno.land" call.tx