Playground
gnomod.toml
module = "gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlgnot" gno = "0.9" [addpkg] creator = "g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp" height = 791564 max_deposit = "100000000ugnot"
hlgnot.gno
// Package hlgnot is the GNOT lock: the bridge's GNOT route on gno.land (bridge/PLAN.md §5.2, §5.4, §5.5).
//
// Out. TransferRemote takes the coins a direct user call sends — exactly amount + fee in ugnot — keeps the amount
// in the lock, pays the fee to r/hlfees, and sends a token message through r/hlmailbox to the synthetic GNOT
// program on Solana, which mints as much there.
//
// In. A burn on Solana comes back as a token message: Process takes it from the mailbox (which checks the active
// verifier and that it was never delivered), checks it came from the enrolled router, and writes a claim in the
// recipient's queue — never a payment on the spot. Claim pays claims in turns under the meters: a tenth of the
// lock a day (never below the floor), a quarter of that for any one recipient, the fee as the first installment,
// from a meter that starts empty at launch and after every unpause that clears a payouts flag. A burn below the
// fee, or to a realm address, is credited to the sweep queue, which only a GovDAO decision pays.
//
// Who may change what. Nobody: every setting moves by a decision made with the builders below (the fee and
// minimum, the fee floor, the cap floor, the per-message maximum, the router; a void, a restore or a credit by
// message id; a sweep payment; a refund by id; a migration to a successor), at once or after 7 days as §5.3 says —
// the governor's own decision through Govern until it yields on r/hlmailbox, a GovDAO proposal's after (M1k);
// the guardians and watch keys can only pause (sends, credits, payouts) through r/hlmailbox. Every launch value is
// compiled in below and written at deploy; nothing is sent or credited until the Launch decision executes.
//
// The state machine — claims, meters, counters, the identity of §5.9 — is gno.land/p/…/hlroute/v0; this realm
// holds the coins and makes the calls.
package hlgnot
import (
"chain"
"chain/banker"
"chain/runtime"
"chain/runtime/unsafe"
"encoding/hex"
"strconv"
"strings"
"time"
"gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/decisions/v0"
"gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlroute/v0"
hl "gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hyperlane/v0"
"gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlmailbox"
"gno.land/r/gov/dao"
)
const (
namespace = "gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/"
pkgPath = namespace + "hlgnot" // must match gnomod.toml
mailboxPath = namespace + "hlmailbox"
feesPath = namespace + "hlfees"
bubblePath = "gno.land/r/g1leu8d2vsplhehcfkjg50mwgdpxdkt8tztu95wr/bubble" // the live token realm, never redeployed
hlbubblePath = namespace + "hlbubble"
hlgovPath = namespace + "hlgov"
gnot = int64(1_000_000) // one GNOT in ugnot
// The launch values (§5.3, §5.5): the fee, the minimum, the fee floor, the cap floor, the per-message maximum,
// and the router — the synthetic GNOT program on Solana. The router is a PLACEHOLDER (the test route of the
// vectors) until the setup step (§5.8) gives the program id; bridge/local/e2e.sh swaps it for its run's.
launchFee = 5 * gnot
launchMinimum = 10 * gnot
launchFeeFloor = 2 * gnot
launchCapFloor = 10_000 * gnot
launchMaximum = 25_000 * gnot
launchRouter = "9c79e6474d5e4cb2e1bb479df49c8d7c0244af0bb1cf452aa573386632894895" // the GNOT token program BXpQkFcsHEsqVxvFQ2e4VSgfDSNBCKQsuKx9Qd2xtKj2
maxI64 = uint64(1<<63 - 1)
)
// launchGovernor is the governor (M1k): the mailbox's, compiled here too so a member reads it in this realm's
// served source; init refuses a deploy with another. bridge/local/e2e.sh swaps it for gnodev's test1.
const launchGovernor = address("g1ecsuj0q572jr0dhu29q9njtnmw03hyu7tyyvv6")
var (
st = hlroute.New(hlroute.Launch{Symbol: "GNOT", Fee: launchFee, Minimum: launchMinimum, FeeFloor: launchFeeFloor,
CapFloor: launchCapFloor, Maximum: launchMaximum, Domain: hlmailbox.LaunchOrigin(), Router: mustKey(launchRouter),
Now: time.Now().Unix()})
// realms are the addresses a transfer may not name as its recipient on either side (§5.2): a burn to one of
// them goes to the sweep queue, a send to one is refused.
realms = []address{chain.PackageAddress(pkgPath), chain.PackageAddress(mailboxPath), chain.PackageAddress(feesPath),
chain.PackageAddress(bubblePath), chain.PackageAddress(hlbubblePath), chain.PackageAddress(hlgovPath)}
)
// init refuses a deploy whose compiled governor is not the mailbox's (M1k): the bridge's realms are governed by
// one key until it yields, or by GovDAO from the first block, never a mix.
func init() {
if launchGovernor != hlmailbox.Governor() {
panic("hlgnot: the compiled governor " + string(launchGovernor) + " is not the mailbox's " + string(hlmailbox.Governor()))
}
}
func mustKey(s string) [32]byte {
k, err := hl.ParseKey32(s)
if err != nil {
panic(err.Error())
}
return k
}
func now() int64 { return time.Now().Unix() }
func u32(n uint32) string { return strconv.FormatUint(uint64(n), 10) }
func itoa(n int64) string { return strconv.FormatInt(n, 10) }
func caller(cur realm) address {
if !cur.IsCurrent() {
panic("hlgnot: that realm value is not live; pass your own cur")
}
return cur.Previous().Address()
}
func mustHex(s, what string) []byte {
b, err := hex.DecodeString(strings.TrimPrefix(strings.TrimSpace(s), "0x"))
if err != nil {
panic("hlgnot: the " + what + " is not hex")
}
return b
}
// isRealm is whether an address is a realm of the bridge: the six compiled here, every route realm the mailbox
// registers (R39) and every one it dropped (AT6: a re-pointed-away successor, a route no more that nothing of the
// line can move coins out of) — a successor's address, which its page prints as the lock's holder and a holder
// pastes as a deposit address, is refused as a recipient at send and swept at a credit, to be credited to its
// owner by id, never paid into a realm's account outside every counter. A handful of reads.
func isRealm(a address) bool {
for _, r := range realms {
if r == a {
return true
}
}
for _, p := range hlmailbox.Routes() {
if chain.PackageAddress(p) == a {
return true
}
}
for _, p := range hlmailbox.DroppedRoutes() {
if chain.PackageAddress(p) == a {
return true
}
}
return false
}
func mustBeLive() {
if !hlmailbox.Live() {
panic("hlgnot: not launched: nothing is sent, credited or paid before the Launch decision")
}
}
func mustNotBePaused(fn string) {
if hlmailbox.Paused(pkgPath, fn) {
panic("hlgnot: " + fn + " are paused by a guardian or a watch key")
}
}
// mustNotBeDropped refuses a realm the mailbox dropped from its line (R35): its predecessor re-pointed the migration
// to another successor while this realm had pulled nothing, so it is a route no more — Solana's token may still
// name it the router until the next kind 6, and a send or a credit here would be against a lock no realm of the
// line holds. The mailbox refuses its Dispatch and its Process too; the line's last realm takes every message
// addressed to it once its import has ended.
func mustNotBeDropped() {
if by := hlmailbox.Dropped(pkgPath); by != "" {
panic("hlgnot: a route no more: " + by + " re-pointed its migration to another successor; the line's last realm takes every message and send")
}
}
// syncLaunch empties the meters at the launch, once: they start empty there as at a deploy (§5.4).
func syncLaunch() {
if la := hlmailbox.LaunchedAt(); la != st.LaunchSeen {
st.ResetMeters(la)
st.LaunchSeen = la
}
}
// ------------------------------------------------------------- reading --
// Address is this realm's address: the holder of the lock, and (as 32 bytes) the router the Solana program enrolls.
func Address() address { return chain.PackageAddress(pkgPath) }
// Locked is the lock: what backs synthetic GNOT on Solana, by the counters (sent − paid).
func Locked() int64 { return st.Lock }
// Balance is the ugnot this realm's account holds; it is the lock unless someone sent coins here outside a transfer.
func Balance() int64 { return banker.NewReadonlyBanker().GetCoin(Address(), "ugnot") }
// Router is the enrolled router on Solana, in hex.
func Router() string { return hex.EncodeToString(st.Router[:]) }
// Domain is the Solana domain this route sends to and takes from.
func Domain() uint32 { return st.Domain }
func Fee() int64 { return st.Fee }
func Minimum() int64 { return st.Minimum }
func FeeFloor() int64 { return st.FeeFloor }
func CapFloor() int64 { return st.CapFloor }
func Maximum() int64 { return st.Maximum }
func Cap() int64 { return st.Cap() }
// Counters is the identity's five counters (§5.9): sentTotal, paidTotal, owed, voided, lost.
func Counters() (sentTotal, paidTotal, owed, voided, lost int64) {
return st.SentTotal, st.PaidTotal, st.Owed, st.Voided, st.Lost
}
// Migrated is the successor's pkgpath once a migration applied, "" before.
func Migrated() string { return st.MigratedTo }
// ---------------------------------------------------------------- out --
// TransferRemote sends amount of GNOT to recipient on destination (a Solana address in base58, or 32 bytes in
// hex) and returns the message id in hex. The call must be a direct user call sending exactly amount + fee in
// ugnot: the amount is locked here, the fee goes to r/hlfees. The amount is between the minimum and the
// per-message maximum; a realm's address as recipient is refused.
func TransferRemote(cur realm, destination uint32, recipient string, amount int64) string {
mustBeLive()
mustNotBePaused(hlmailbox.FnSends)
mustNotBeDropped()
st.MustSend(hlmailbox.Predecessor(pkgPath), env(cur)) // a successor takes no send before its last page is in (R35, F28) and before kind 6 names it (AT7)
if destination != st.Domain {
panic("hlgnot: no route to domain " + u32(destination))
}
st.CheckSend(amount)
to, err := hl.ParseKey32(recipient)
if err != nil {
panic(err.Error())
}
if to == ([32]byte{}) {
panic("hlgnot: the recipient is all zeros")
}
if a, err := hl.Bytes32ToAddress(to); err == nil && isRealm(a) {
panic("hlgnot: the recipient is a realm of the bridge")
}
prev := cur.Previous()
if !prev.IsUserCall() {
panic("hlgnot: a direct user call only")
}
want := amount + st.Fee
sent := unsafe.OriginSend()
if len(sent) != 1 || sent[0].Denom != "ugnot" || sent[0].Amount != want {
panic("hlgnot: send exactly " + itoa(want) + "ugnot (the amount plus the fee of " + itoa(st.Fee) + "), not " + sent.String())
}
runtime.AssertOriginCall() // a direct MsgCall, so the envelope landed here and nothing ran in between
who := prev.Address()
banker.NewBanker(banker.BankerTypeOriginSend, cur).SendCoins(Address(), chain.PackageAddress(feesPath), chain.Coins{{"ugnot", st.Fee}})
id := hlmailbox.Dispatch(cross(cur), destination, st.Router, hl.TokenMessage(to, uint64(amount), nil))
idHex := hex.EncodeToString(id[:])
st.Send(now(), idHex, who, amount)
chain.Emit("SentTransferRemote",
"destination", u32(destination),
"recipient", hex.EncodeToString(to[:]),
"amount", itoa(amount),
"fee", itoa(st.Fee),
"from", string(who),
"id", idHex,
)
return idHex
}
// ----------------------------------------------------------------- in --
// Process takes a token message from Solana and credits a claim to its recipient. Anyone may call it — a relayer,
// usually — with the verifier's metadata and the message, both in hex. The mailbox checks the verifier and that
// the message was never delivered; this checks it came from the enrolled router (the old one too, for 7 days after
// a swap). A refused message stays undelivered and can be brought again. A realm registered as a successor credits
// nothing before the last page of its predecessor's migration is in (R32) — a message addressed to itself as much
// as one addressed to the predecessor (AQ1: the mailbox hands a migrated route's messages to its successor) — and
// a migrated realm refuses before the mailbox is asked: the successor takes it.
func Process(cur realm, metadata, message string) {
caller(cur)
mustBeLive()
mustNotBePaused(hlmailbox.FnCredits)
mustNotBeDropped()
msg := mustHex(message, "message")
m, err := hl.ParseMessage(msg)
if err != nil {
panic(err.Error())
}
if st.Migrated() {
panic("hlgnot: migrated to " + st.MigratedTo + ": the successor takes this message")
}
if self, err := hl.AddressToBytes32(Address()); err != nil {
panic(err.Error())
} else {
st.MustTake(m.Recipient == self, hlmailbox.Predecessor(pkgPath))
}
t := now()
if m.Origin != st.Domain || !st.RouterAccepts(t, m.Sender) {
panic("hlgnot: the message is not from the router enrolled for domain " + u32(st.Domain))
}
rcpt, amount, _, err := hl.ParseTokenMessage(m.Body)
if err != nil {
panic(err.Error())
}
if amount > maxI64 {
panic("hlgnot: the amount is past what GNOT can hold")
}
origin, sender, body := hlmailbox.Process(cross(cur), mustHex(metadata, "metadata"), msg)
if origin != m.Origin || sender != m.Sender || string(body) != string(m.Body) {
panic("hlgnot: the mailbox read the message differently") // cannot happen: the same bytes, the same parser
}
// a recipient that is no gno address (its top twelve bytes not zero, §13) or a realm of the bridge is swept:
// owed, paying nobody until GovDAO credits it by id to its owner
to, err := hl.Bytes32ToAddress(rcpt)
recipient := string(to)
if err != nil {
recipient = hex.EncodeToString(rcpt[:])
}
idb := hl.ID(msg)
id := hex.EncodeToString(idb[:])
epoch, _ := hlmailbox.PayoutsEpoch(pkgPath)
swept := st.Credit(t, runtime.ChainHeight(), epoch, id, to, int64(amount), hlroute.BySigners, err != nil || isRealm(to))
chain.Emit("Credited",
"origin", u32(origin),
"recipient", recipient,
"amount", itoa(int64(amount)),
"id", id,
"swept", strconv.FormatBool(swept),
)
}
// Claim pays up to n claims (n ≤ 20) taking recipients in turns under the meters, the fee as each claim's first
// installment. Anyone may call it; the relayers do. It returns how many claims it paid something on.
func Claim(cur realm, n int) int {
caller(cur)
mustBeLive()
mustNotBePaused(hlmailbox.FnPayouts)
mustNotBeDropped()
syncLaunch()
epoch, at := hlmailbox.PayoutsEpoch(pkgPath)
paid := st.Claim(now(), n, epoch, at, env(cur))
chain.Emit("Claimed", "count", strconv.Itoa(paid))
return paid
}
func pay(cur realm, to address, amount int64) {
banker.NewBanker(banker.BankerTypeRealmSend, cur).SendCoins(Address(), to, chain.Coins{{"ugnot", amount}})
}
// env is what the state machine asks of this realm.
func env(cur realm) hlroute.Env {
return hlroute.Env{
Flagged: func(id string, height int64, verifier bool) bool { return hlmailbox.Flagged(pkgPath, id, height, verifier) },
ClearFlags: func(fn string) bool { return hlmailbox.ClearFlags(cross(cur), fn) },
RemoveSeat: func(seat int, holder address) bool { return hlmailbox.VacateSeat(cross(cur), seat, holder) },
Delivered: func(id string) bool { return hlmailbox.Delivered(id) != 0 },
MarkDone: func(id string) { hlmailbox.MarkDone(cross(cur), id) },
Epoch: func() int64 { e, _ := hlmailbox.PayoutsEpoch(pkgPath); return e },
Height: func() int64 { return runtime.ChainHeight() },
Pay: func(to address, amount int64) { pay(cur, to, amount) },
PayFee: func(amount int64) { pay(cur, chain.PackageAddress(feesPath), amount) },
AddRoute: func(path string) { hlmailbox.AddRoute(cross(cur), path) },
AnnouncedFor: func(path string) string { return hlmailbox.SuccessorFor(path) },
Predecessor: func() string { return hlmailbox.Predecessor(pkgPath) },
IsRoute: func(path string) bool { return hlmailbox.IsRoute(path) },
Enrolled: func() (int64, int64) { return hlmailbox.Enrolled(pkgPath) },
}
}
// ------------------------------------------------------------ builders --
// The builders (§5.3): a decision made with one of these is the only way a setting changes — the governor's own,
// through Govern, until it yields on r/hlmailbox (M1k):
//
// hlgnot.Govern(cross(cur), hlgnot.NewSetCapFloorRequest(cross(cur), 12_000_000_000))
//
// and a GovDAO proposal after:
//
// req := hlgnot.NewSetCapFloorRequest(cross(cur), 12_000_000_000)
// dao.MustCreateProposal(cross(cur), req.Proposal())
//
// Each checks its parameters, writes them as the proposal's description, and returns a Request whose closure —
// the one closure, run by the governor through Govern or by GovDAO's proxy when the proposal executes — records
// the decision and settles its at-once test against the live state: a lowering, a cancel, a restore of a withheld
// claim and the void of ids a guardian's standing payouts flag names apply at once; a raise, a swap, a credit, a
// sweep payment, a migration, a void of unnamed ids and a restore of a forged claim wait 7 days, and anyone
// applies them with Execute(id); a refund waits 7 days too and is then applied by the governor's (GovDAO's, after
// the yield) own at-once decision (NewApplyRefundRequest, AT2), never by Execute. Before the Launch decision only
// cancel is proposed.
// Request is what a builder returns (M1k): the proposal GovDAO's proxy executes after the yield (Proposal), and
// the same decision the governor runs directly before it (Govern). The closure is one; only who may run it
// changes with the yield. A Request comes from a builder alone — the type is this realm's and the closure
// unexported, so no other code can build one or change what it decides — and a stranger holding one can only
// hand it back to Govern, which refuses everyone but the governor.
type Request struct {
proposal dao.ProposalRequest
text string
decide func(cur realm) error
}
// Proposal is the request as a GovDAO proposal: `dao.MustCreateProposal(cross(cur), req.Proposal())`.
func (r Request) Proposal() dao.ProposalRequest { return r.proposal }
// Description is the proposal's: the parameters as the builder wrote them.
func (r Request) Description() string { return r.text }
// who names a previous realm in a refusal: its pkgpath, or a user's address.
func who(path string, a address) string {
if path != "" {
return path
}
return string(a)
}
// mustBeGovernor is a decision's identity check (M1k), read from the closure's own live cur: until the governor
// yields on r/hlmailbox, the governor's own call — the compiled address, by its own transaction (cur.Previous() a
// user realm: a MsgCall's, or a MsgRun script's ephemeral realm, whose address is the signer's; never another
// realm), which is Govern's non-crossing call of the closure — and gno.land/r/gov/dao's proposals refused; after
// it, or when no governor was compiled, the proxy's exact pkgpath, as before M1k, and the governor refused like
// anyone. A refusal is a panic: a proposal made before the yield survives for a retry after it, within its 14
// days.
func mustBeGovernor(cur realm) {
prev := cur.Previous()
if decisions.DAOGoverns(launchGovernor, hlmailbox.Yielded()) {
if p := prev.PkgPath(); p != decisions.DAOPath {
panic("hlgnot: only " + decisions.DAOPath + " executes a decision, not " + who(prev.PkgPath(), prev.Address()))
}
return
}
if !prev.IsUser() || prev.Address() != launchGovernor {
panic("hlgnot: until the governor yields, " + string(launchGovernor) + " alone decides, by Govern from its own key: not " + who(prev.PkgPath(), prev.Address()) + " (a GovDAO proposal is refused until the yield)")
}
}
func propose(cur realm, d hlroute.Draft) Request {
if !cur.IsCurrent() {
panic("hlgnot: that realm value is not live; pass your own cur")
}
made := now()
cb := func(cur realm) error {
mustBeGovernor(cur)
t := now()
if err := decisions.Expired(made, t); err != nil {
return err
}
if d.Kind != hlroute.KindCancel {
mustBeLive()
}
if d.Kind == hlroute.KindApplyRefund {
mustNotBePaused(hlmailbox.FnPayouts) // a refund moves coins out of the lock: under a standing payouts flag it waits like a claim (§5.9; the proposal survives for a retry)
}
dec := st.Decide(made, t, d, env(cur))
chain.Emit("Decision", "id", itoa(dec.ID), "kind", dec.Kind, "state", dec.State())
return nil
}
return Request{proposal: dao.NewProposalRequest("hlgnot: "+d.Kind, d.Text, dao.NewSimpleExecutor(0, cur, cb, d.Text)), text: d.Text, decide: cb}
}
// Govern is the governor's way in before the yield (M1k): the governor — the compiled launchGovernor, by its own
// transaction (the MsgRun script that makes the request in the same transaction; never through another realm) —
// makes a builder's decision directly, the same closure GovDAO's proxy runs after the yield: the same checks, the
// same at-once test, the same 7-day queue and 14-day deadline, the same record and events. The closure is called
// non-crossing, in this frame, so it reads the governor from cur.Previous() as it reads the proxy after the yield.
// Refused for anyone else, and for everyone once the governor yielded on r/hlmailbox (or when none was compiled):
// GovDAO's proposals decide then. A request past its 14 days is refused (the deadline error) and made afresh.
func Govern(cur realm, r Request) {
if !cur.IsCurrent() {
panic("hlgnot: that realm value is not live; pass your own cur")
}
if r.decide == nil {
panic("hlgnot: not a builder's request")
}
if yielded := hlmailbox.Yielded(); decisions.DAOGoverns(launchGovernor, yielded) {
if launchGovernor == "" {
panic("hlgnot: no governor was compiled, " + decisions.DAOPath + " governs from the first block: a decision is a GovDAO proposal, never Govern")
}
panic("hlgnot: the governor yielded at height " + itoa(yielded) + ", " + decisions.DAOPath + " governs since: a decision is a GovDAO proposal, never Govern")
}
mustBeGovernor(cur)
if err := r.decide(cur); err != nil {
panic("hlgnot: " + err.Error())
}
}
// NewSetCapFloorRequest sets the day cap's floor (in ugnot): a lowering at once, never below the launch floor; a
// raise after 7 days.
func NewSetCapFloorRequest(cur realm, n int64) Request {
mustBeLive()
return propose(cur, st.DraftCapFloor(n))
}
// NewSetMaximumRequest sets the per-message maximum (in ugnot), never below the minimum: a lowering at once, a
// raise after 7 days.
func NewSetMaximumRequest(cur realm, n int64) Request {
mustBeLive()
return propose(cur, st.DraftMaximum(n))
}
// NewSetFeeRequest sets the fee and the minimum together (in ugnot), the fee not below the fee floor: lowering
// both at once, raising either after 7 days.
func NewSetFeeRequest(cur realm, fee, minimum int64) Request {
mustBeLive()
return propose(cur, st.DraftFee(fee, minimum))
}
// NewSetFeeFloorRequest sets the fee floor (in ugnot), not above the fee: a lowering at once, a raise after 7 days.
func NewSetFeeFloorRequest(cur realm, n int64) Request {
mustBeLive()
return propose(cur, st.DraftFeeFloor(n))
}
// NewSetRouterRequest swaps the router (a Solana program id in base58, or 32 bytes in hex) after 7 days; the old
// router's messages stay accepted for 7 days more.
func NewSetRouterRequest(cur realm, router string) Request {
mustBeLive()
return propose(cur, st.DraftRouter(mustKey(router), router))
}
// NewVoidRequest voids credits by message id (comma separated, up to 256; a claim, or a sweep entry as forged) or
// by a range of credits ("heights:<from>-<to>", every credit at those block heights; "since:<from>", every credit
// the verifier made from that height on), closed at the height the proposal is made and covering at most 1,000
// credits (a bigger range is split by heights), as withheld (the remainder stays booked, restorable) or as forged
// (the remainder dropped, the paid part lost; a sweep entry's amount dropped from what is owed). A credit a
// guardian's standing payouts flag names — by id, or by a range covering it — is voided the moment the proposal
// executes; the rest wait 7 days. The unpause option takes the unpause builder's parameters — the functions whose
// flags to clear (sends, credits, payouts; comma separated, "" for none) and the seats to vacate (comma separated,
// "" for none; each seat's holder now is recorded, and a seat whose occupant changed by execution is skipped) —
// applied in the same closure, after the void.
func NewVoidRequest(cur realm, ids string, forged bool, unpauseFns, removeSeats string) Request {
mustBeLive()
return propose(cur, st.DraftVoid(ids, forged, unpauseFns, removeSeats, runtime.ChainHeight(), hlmailbox.Seat))
}
// NewRestoreRequest restores voided claims by message id: a withheld one at once, a forged one after 7 days.
func NewRestoreRequest(cur realm, ids string) Request {
mustBeLive()
return propose(cur, st.DraftRestore(ids))
}
// NewCreditRequest credits a claim by hand after 7 days: amount (in ugnot) to a recipient under a message id. It
// marks the id done and refuses an id already done, unless that id's claim stands voided, in which case the claim
// is restored and its remainder replaced by this recipient and amount at the back of the recipient's queue.
func NewCreditRequest(cur realm, id string, to address, amount int64) Request {
mustBeLive()
if !to.IsValid() || isRealm(to) {
panic("hlgnot: the recipient must be an address outside the bridge's realms")
}
return propose(cur, st.DraftCredit(id, to, amount, hlmailbox.Delivered(id) != 0))
}
// NewSweepRequest pays sweep entries, named by message id (comma separated, up to 256), to an address after 7
// days: their sum, at most the lock. The paid entries are dropped (R19), so none is ever paid, credited by id or
// voided twice; an entry voided or gone by then is skipped, the decision's note saying so.
func NewSweepRequest(cur realm, ids string, to address) Request {
mustBeLive()
if !to.IsValid() || isRealm(to) {
panic("hlgnot: the recipient must be an address outside the bridge's realms")
}
return propose(cur, st.DraftSweep(ids, to))
}
// NewRefundRequest queues a refund of sends by message id (comma separated) to their senders, 7 days: the cure for
// sends a migration stranded undelivered — the sends imported from the predecessor, once kind 6 has enrolled this
// realm on Solana for 14 days by r/hlgov's note with the mailbox (AR1, R37: a refunded send stays deliverable
// there until the predecessor's router is replaced), checked when the proposal is made and when it applies. After
// the 7 days GovDAO applies it by NewApplyRefundRequest (AT2), never anyone by Execute.
func NewRefundRequest(cur realm, ids string) Request {
mustBeLive()
return propose(cur, st.DraftRefund(ids, now(), env(cur)))
}
// NewApplyRefundRequest applies a queued refund decision whose 7 days have passed, at once (AT2): GovDAO's own act,
// the member having read hlwatch's gate first — the token's router on Solana is this realm and the kind 6 is
// executed there — since this realm cannot see Solana, and a refund applied while the predecessor is still the
// router lets the refunded sender deliver his send there after it (minted twice, AR1); Execute refuses a refund.
// The apply is the delay's own: the note's 14 days asked again, the sum at most the lock; under a standing
// payouts flag it waits for the unpause like a claim (the closure refuses, the proposal retried within its 14
// days). Refused for a decision that is no refund, not pending, or not yet due; the description names the refund
// decision and carries its text, the ids included.
func NewApplyRefundRequest(cur realm, id int64) Request {
mustBeLive()
return propose(cur, st.DraftApplyRefund(id, now(), env(cur)))
}
// NewWriteOffRequest books refunded sends, by message id (comma separated), as lost after 7 days (AR1): a refunded
// send delivered on Solana after all (a stranger's Reemit) minted a second time against nothing, and the write-off
// closes the identity by its amount; only a refunded send, once — the member reads hlwatch's DELIVERED line for the
// id first.
func NewWriteOffRequest(cur realm, ids string) Request {
mustBeLive()
return propose(cur, st.DraftWriteOff(ids))
}
// NewMigrateRequest hands the lock, the claims and the send records to a successor realm after 7 days: the
// successor then calls Pull from its own code and takes them over. The successor must have announced itself to
// the mailbox from its own code first, for the GNOT route (hlmailbox.AnnounceSuccessor(cur, "GNOT"), R25 and
// AQ5), and must not be a route the mailbox registers already (R31) — checked when the proposal is made and when
// it applies, so the lock never goes to a path with no realm behind it, nor to the BUBBLE route's successor by a
// slip. A realm that succeeds another (a successor registered by its predecessor's migrate) migrates on only once
// its own import has ended (R31): before page 0 nothing has moved and the lock would be stranded for good.
func NewMigrateRequest(cur realm, to string) Request {
mustBeLive()
return propose(cur, st.DraftMigrate(to, pkgPath, env(cur)))
}
// NewCancelRequest cancels a pending decision of this route, at once. It is proposed before Launch too.
func NewCancelRequest(cur realm, id int64) Request {
return propose(cur, st.DraftCancel(id))
}
// Execute applies a queued decision whose 7 days have passed. Anyone may call it; the relayers do. A sweep
// payment moves coins out of the lock, so under a standing payouts flag it waits for the unpause like a claim
// (§5.9: nothing paid under a suspect verifier). A refund is never Execute's (AT2): the state refuses the kind, and
// GovDAO applies it by NewApplyRefundRequest after hlwatch's Solana check.
func Execute(cur realm, id int64) {
caller(cur)
mustBeLive()
if d := st.Ledger.Get(id); d != nil && d.Kind == hlroute.KindSweep {
mustNotBePaused(hlmailbox.FnPayouts)
}
dec := st.Execute(now(), id, env(cur))
chain.Emit("Decision", "id", itoa(dec.ID), "kind", dec.Kind, "state", dec.State())
}
// Pull is the successor's: once a migrate decision names it, the realm at that pkgpath calls Pull from its own
// code, page by page from 0, and receives the lock (paid to its address, with page 0) and the records to import,
// up to 500 a page (the snapshot's More says whether a page follows); a page pulled already hands over nothing.
// Page 0 moves the lock, so under a standing payouts flag it waits for the unpause like a sweep payment (R27, R16:
// nothing paid under a suspect verifier); the flag follows the claims to the successor (hlmailbox.AddRoute).
func Pull(cur realm, page int) *hlroute.Snapshot {
if !cur.IsCurrent() {
panic("hlgnot: that realm value is not live; pass your own cur")
}
path := cur.Previous().PkgPath()
if st.MigratedTo == "" || path != st.MigratedTo {
panic("hlgnot: only the successor named by a migrate decision pulls")
}
if page == 0 {
mustNotBePaused(hlmailbox.FnPayouts)
}
snap := st.Export(page, hlroute.PullPage)
if page == 0 {
hlmailbox.NotePulled(cross(cur), path) // the lock moved: the mailbox answers Pulled (R35) — kind 6 may enrol the successor, and the migration is never re-pointed
}
if snap.Lock > 0 {
pay(cur, chain.PackageAddress(path), snap.Lock)
}
chain.Emit("Migrated", "to", path, "page", strconv.Itoa(page), "lock", itoa(snap.Lock), "claims", strconv.Itoa(len(snap.Claims)), "sweeps", strconv.Itoa(len(snap.Sweeps)), "sends", strconv.Itoa(len(snap.Sends)), "more", strconv.FormatBool(snap.More))
return snap
}
// --------------------------------------------------------------- pages --
func pausedText() string {
var fns []string
for _, fn := range []string{hlmailbox.FnSends, hlmailbox.FnCredits, hlmailbox.FnPayouts} {
if hlmailbox.Paused(pkgPath, fn) {
fns = append(fns, fn)
}
}
return strings.Join(fns, ", ")
}
// Render:
//
// "" the route's page (the first 100 waiting claims and sweep entries, the rest counted)
// "decisions" the decisions page: the last 100 pending and executed per kind
// "json" the figures for the agents
// "decisions.json" every decision
// "claim/<id>" one claim by message id, or the swept amount, or "null"
// "claims/<from>" up to 100 waiting claims from the <from>-th on, in the page's order, as a JSON array
// "sweeps/<from>" up to 100 sweep entries from the <from>-th on, by id, as a JSON array
// "send/<id>" one send by message id ({"id","from","amount","at","imported","refunded","writtenOff"}), or "null"
// "refunds/<from>" up to 100 sends refunded here from the <from>-th on, by id, as a JSON array (AQ2: what the
// monitors read to drop a refunded send from what is in flight)
func Render(path string) string {
epoch, at := hlmailbox.PayoutsEpoch(pkgPath)
switch {
case strings.HasPrefix(path, "claims/"):
return st.ClaimsPage(parseFrom(path[len("claims/"):]))
case strings.HasPrefix(path, "sweeps/"):
return st.SweepsPage(parseFrom(path[len("sweeps/"):]))
case strings.HasPrefix(path, "send/"):
return st.SendJSON(path[len("send/"):])
case strings.HasPrefix(path, "refunds/"):
return st.RefundsPage(parseFrom(path[len("refunds/"):]))
case path == "":
var b strings.Builder
b.WriteString("# GNOT across chains\n\n")
b.WriteString("The bridge's GNOT route on gno.land. GNOT sent to Solana is locked here, and the synthetic GNOT there is backed by it one to one; a burn there is credited here as a claim, paid under the meters. Every setting moves only by a decision made with this realm's builders — the governor's own until it yields, a GovDAO proposal after.\n\n")
if hlmailbox.Live() {
b.WriteString("- **live** since " + itoa(hlmailbox.LaunchedAt()) + "\n")
} else {
b.WriteString("- **not launched**: the values below are the compiled launch values, waiting for the Launch decision\n")
}
b.WriteString("- " + decisions.GovernorLine(launchGovernor, hlmailbox.Yielded()) + "\n")
b.WriteString("- balance: " + st.Amount(Balance()) + "\n")
b.WriteString(st.Figures(now(), epoch, at, hlmailbox.LaunchedAt(), pausedText()))
b.WriteString("\n## Decisions\n\n" + st.Ledger.Page())
return b.String()
case path == "decisions":
return "# Decisions\n\n" + st.Ledger.Page()
case path == "json":
return "{\"address\":" + strconv.Quote(string(Address())) + ",\"live\":" + strconv.FormatBool(hlmailbox.Live()) +
"," + decisions.GovernorJSON(launchGovernor, hlmailbox.Yielded()) +
",\"balance\":" + itoa(Balance()) + ",\"paused\":" + strconv.Quote(pausedText()) + "," + st.JSON(now(), epoch, at, hlmailbox.LaunchedAt()) + "}"
case path == "decisions.json":
return st.Ledger.JSON()
case strings.HasPrefix(path, "claim/"):
return st.ClaimJSON(path[len("claim/"):])
}
return "unknown path; see the route's page"
}
// parseFrom reads a page's offset; -1 (an empty page) for anything but a number.
func parseFrom(s string) int {
n, err := strconv.Atoi(s)
if err != nil || n < 0 {
return -1
}
return n
}