Playground
gnomod.toml
module = "gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlgov" gno = "0.9" [addpkg] creator = "g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp" height = 791569 max_deposit = "100000000ugnot"
hlgov.gno
// Package hlgov carries GovDAO's decisions to Solana (bridge/PLAN.md §5.3, §6.5, §13): a proposal made with one of
// the builders below, when it executes, dispatches a message through r/hlmailbox to the admin program — the
// decision's kind, its parameters and its sequence number (this realm's own counter, taken at execution) — and the
// admin program records it by that number and executes it after its clock. Anyone may re-dispatch an executed
// decision (the same number and parameters) until the admin program has recorded it. The builders check the
// parameters with the admin program's own rules, so a proposal that would fail on Solana is refused when it is made.
// Kind 4 is reserved and its builder refuses every call (§13); a cancel's body starts with an 8-byte salt drawn in
// the executing transaction, so two cancels of one list differ; kind 12 names a token's mint limits on the pausable
// ISM (the per-message maximum and the day cap, in base units), one of the 7-day group.
//
// Two decisions change this realm alone: `set decision recipient` (the program id decisions go to, a 7-day change,
// how a successor admin program ever receives one) and `sync sequence` (at once: the counter is raised — never
// lowered — to the number the admin program expects next, when a foreign decision has taken one, §6.5). The counter
// starts at a compiled number (launchSequence: 0 for a chain's first r/hlgov, the predecessor's last number for a
// successor), so no number the admin program recorded is ever reused. Before the Launch decision every builder
// but the cancel of a queued change here is refused. Who decides is the governor's (M1k): the compiled
// launchGovernor through Govern until it yields on r/hlmailbox, GovDAO's proposals after. Every launch value is
// compiled in below.
package hlgov
import (
"chain"
"chain/runtime"
"crypto/sha256"
"encoding/binary"
"encoding/hex"
"strconv"
"strings"
"time"
"gno.land/p/nt/avl/v0"
"gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/decisions/v0"
hl "gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hyperlane/v0"
"gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlbubble"
"gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlgnot"
"gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlmailbox"
"gno.land/r/gov/dao"
)
const (
namespace = "gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/"
pkgPath = namespace + "hlgov" // must match gnomod.toml
// The kinds (§13).
KindCancel = uint8(1)
KindUnpause = uint8(2)
KindTokenISM = uint8(3)
KindReserved = uint8(4) // reserved (§13): the client's state layout is fixed for the deployment's life; refused
KindGuardians = uint8(5)
KindRouter = uint8(6)
KindProtocolFee = uint8(7)
KindUpgrade = uint8(8)
KindSuccessor = uint8(9)
KindMintLimits = uint8(12) // set mint limits (§13): a token's per-message maximum and day cap on the pausable ISM; the 7-day group
maxCancel = 16 // numbers one cancel names
maxProtocolFee = 50_000_000 // lamports: the mailbox's max_protocol_fee, 0.05 SOL, fixed at its init (§5.5)
// MaxDecisionBody bounds a decision's body (kind ‖ number ‖ params) at what Solana can ever deliver (the
// assumptions audit's F18, M1g part 2): a legacy delivery of a decision carries at most 538 bytes of body — 529
// of parameters, what 14 account keys and 127 bytes of fixed instruction data leave of the 1,232-byte packet —
// and Hyperlane's mainnet mailbox dies on its own 32 KB heap past about 2,250 parameter bytes anyway (M2-NOTES
// M2f), so a body no one can deliver would stick this realm's sequence with its number untaken, in a form no
// program of ours cures. Every builder's body is far below (a cancel at most 163 bytes with its salt, kind 5 at
// most 4 entries); the bound stands where this realm dispatches, checked when a proposal is made and in its
// closure.
MaxDecisionBody = 512
syncReach = uint64(1) << 32 // a sync sequence raises the counter by at most this (the realm's own bound, §13; kind 10 is reserved since v35)
seatCount = 6
guardianSeats = 4
maxSeatChanges = 4 // kind 5: two guardian seats plus either watch slot
// The launch values (§5.3, §6.5): the admin program (the first decision recipient), the pausable ISM (the only
// id kind 3 may name), the light client (the pausable ISM's target, whose state layout is fixed for the
// deployment's life — kind 4 is reserved — shown on the page for a member's check), and the four guardians' and
// two watch keys' Solana pubkeys as the admin program's init data carries them. PLACEHOLDERS until the Solana
// programs are deployed and the people have keys; bridge/local/e2e.sh swaps the program ids for its run's.
launchRecipient = "38885bd746ab9dc9b6175331a61842d0ad8e0c4c2532f72e286ef7dac82b0358" // the admin program 4ogRnw9iPGa4dY8qqCs1aBWxHQvKSzHh5ttz53sLFTM9
launchPausableISM = "564eab462a321148f88d548996d0fd5e84c66ab630f0f4da63331592d7dce221" // the pausable ISM 6oudxto59ktYrpvqEVXTb5Tuo7vzBpkgnsPWoPXVF5Fv
launchClient = "1a572d156787a62750999f343e5af6f7394f91c11f75a2949e9aefd8914e07ad" // the light client 2mphYtLZ7HnCfrFhGH2c4Do9C9UoysevkmkDb8UkbAu2
launchSolSeat1 = "05a1af200cfddc3b3ace76353505098855c9994913f7282f2e45ce6e473dcd6e" // Nz2u3N3RAMwq9pjw1Vv7ktN7nX4rNe4Uw5rdL9o9c3o
launchSolSeat2 = "028b184c1fe43ac501409db4eb45a47bc2cd280226cca57345b802d27175e5b4" // AvqEe2hdx3HH87NU9CR5GSarCD1sR6PQ2H5AjwSnC4b
launchSolSeat3 = "95b3b44e5adc9a0e849285e59cf6e7b0dab53e3a8772f680990f73a6111f494c" // B5NgM4oD1vYKTEGSe33RaSsHbyGzxKvoaycGqhjbyEV1
launchSolSeat4 = "05ec99dd32dbee307eb064892f68581b9da9ee928df5a00d7f491f0f1b4fc3d2" // Q8HoML8efSufEhvYsSffmHAGJ6YnYb2QwyMVwQYt9Ds
launchSolSeat5 = "195a00fb58ce0d7f762cc2b3d72017100724768fa2ae828c055d57530b34077a" // 2hxnxGiPf6cuuYXjThehyDnkXpUKjQai8fp14zkcgzjB
launchSolSeat6 = "24551f378d8bbdc915fd4497aa9bf73a5eb5f99447755eb9f7c751aed3d558e2" // 3SpxeQf1JTfErvkpd3Kq33Q72H4yhLynKPVECdj9ckmf
// launchSequence is the number of the last decision this realm's predecessor dispatched — 0 for a chain's
// first r/hlgov. A successor r/hlgov for a new chain is deployed with its predecessor's last number here
// (§5.3), so its counter starts where the admin program's stands and never restarts below a recorded number.
// Written by init; the page shows it beside the counter.
launchSequence = uint64(0)
)
// 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 (
destination = hlmailbox.LaunchOrigin()
recipient = mustKey(launchRecipient)
former [][32]byte // every decision recipient a swap replaced (R29): retired admin programs, which kind 9 and a swap refuse for good
client = mustKey(launchClient) // the light client: shown on the page; no kind names it (kind 4 is reserved)
solSeats [seatCount + 1][32]byte // Solana's seats as this realm last set them: a mirror kind 5 warns against, shown on the page
last uint64 // the number of the last decision dispatched; the next is last + 1
sent avl.Tree // seqKey(number) → *decision
ledger decisions.Ledger
)
// decision is one dispatched decision: its body (kind ‖ number ‖ params) and its dispatches; a kind 6 for a route
// of this chain also keeps the route it enrolled and the height it noted with the mailbox (R37: a cancel of it
// clears that note while it is the latest).
type decision struct {
kind uint8
body []byte
at int64 // first dispatched
id string // the latest message id
count int // dispatches so far
text string
route string // a kind 6 for this chain's domain: the route realm it enrolled; "" otherwise
height int64 // … and the block height NoteEnrolled recorded for it
}
type (
recipientParams struct{ to [32]byte }
sequenceParams struct{ n uint64 }
cancelParams struct{ id int64 }
kindParams struct {
kind uint8
params []byte
seats []int
keys [][32]byte
}
)
func init() {
// a deploy whose compiled governor is not the mailbox's is refused (M1k): the bridge's realms are governed by
// one key until it yields, or by GovDAO from the first block, never a mix
if launchGovernor != hlmailbox.Governor() {
panic("hlgov: the compiled governor " + string(launchGovernor) + " is not the mailbox's " + string(hlmailbox.Governor()))
}
solSeats[1], solSeats[2], solSeats[3] = mustKey(launchSolSeat1), mustKey(launchSolSeat2), mustKey(launchSolSeat3)
solSeats[4], solSeats[5], solSeats[6] = mustKey(launchSolSeat4), mustKey(launchSolSeat5), mustKey(launchSolSeat6)
last = launchSequence
}
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 itoa(n int64) string { return strconv.FormatInt(n, 10) }
func u64s(n uint64) string { return strconv.FormatUint(n, 10) }
func hx(b []byte) string { return hex.EncodeToString(b) }
func seqKey(n uint64) string { return strings.Repeat("0", 20-len(u64s(n))) + u64s(n) }
func caller(cur realm) address {
if !cur.IsCurrent() {
panic("hlgov: that realm value is not live; pass your own cur")
}
return cur.Previous().Address()
}
func mustBeLive() {
if !hlmailbox.Live() {
panic("hlgov: not launched: before the Launch decision only the cancel of a queued change 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); see hlgnot's.
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: the governor's own
// call until it yields on r/hlmailbox, gno.land/r/gov/dao's proxy exactly after (or from the first block, when no
// governor was compiled); see hlgnot's.
func mustBeGovernor(cur realm) {
prev := cur.Previous()
if decisions.DAOGoverns(launchGovernor, hlmailbox.Yielded()) {
if p := prev.PkgPath(); p != decisions.DAOPath {
panic("hlgov: only " + decisions.DAOPath + " executes a decision, not " + who(prev.PkgPath(), prev.Address()))
}
return
}
if !prev.IsUser() || prev.Address() != launchGovernor {
panic("hlgov: 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)")
}
}
// Govern is the governor's way in before the yield (M1k): the same closure GovDAO's proxy runs after it, called
// non-crossing in this frame so it reads the governor from cur.Previous() — and dispatches through the mailbox
// under this realm's own authority, as the proxy's execution does; refused for anyone else and for everyone once
// the governor yielded on r/hlmailbox (or when none was compiled); see hlgnot's.
func Govern(cur realm, r Request) {
if !cur.IsCurrent() {
panic("hlgov: that realm value is not live; pass your own cur")
}
if r.decide == nil {
panic("hlgov: not a builder's request")
}
if yielded := hlmailbox.Yielded(); decisions.DAOGoverns(launchGovernor, yielded) {
if launchGovernor == "" {
panic("hlgov: no governor was compiled, " + decisions.DAOPath + " governs from the first block: a decision is a GovDAO proposal, never Govern")
}
panic("hlgov: 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("hlgov: " + err.Error())
}
}
// ------------------------------------------------------------- reading --
// Address is this realm's address: the sender the admin program accepts.
func Address() address { return chain.PackageAddress(pkgPath) }
// Recipient is the program decisions are addressed to, in hex.
func Recipient() string { return hx(recipient[:]) }
// Former lists every decision recipient a swap replaced, in hex, oldest first (R29): retired admin programs.
func Former() []string {
out := make([]string, len(former))
for i, k := range former {
out[i] = hx(k[:])
}
return out
}
func isFormer(k [32]byte) bool {
for _, f := range former {
if f == k {
return true
}
}
return false
}
// mustNotBeFormer refuses a retired admin program as a kind 9's successor or as the decision recipient (R29): a
// program whose authorities went to a successor answers Retired to every decision, and a kind 9 naming it dies on
// its successor_init (NotInherited), so the decision would pend until a cancel — a wasted vote and a standing line
// on hlwatch. Checked when a proposal is made, in its closure, and when a queued swap would apply.
func mustNotBeFormer(k [32]byte, what string) {
if isFormer(k) {
panic("hlgov: never a former " + what + " (" + hx(k[:]) + "): it is retired, every authority handed to a successor by kind 9 — a kind 9 to it would die on its successor_init (NotInherited) and a swap to it would send every decision to a program that answers Retired")
}
}
// Destination is the Solana domain decisions go to.
func Destination() uint32 { return destination }
// Last is the number of the last decision dispatched; Next the number the next one takes; Start the compiled
// number the counter began at (the predecessor's last number; 0 for a chain's first r/hlgov).
func Last() uint64 { return last }
func Next() uint64 { return last + 1 }
func Start() uint64 { return launchSequence }
// SolSeat is the Solana pubkey this realm last set for a seat (1–4 guardians, 5–6 watch keys), in hex.
func SolSeat(n int) string {
if n < 1 || n > seatCount {
return ""
}
return hx(solSeats[n][:])
}
// Body is a dispatched decision's body in hex, by number ("" if none).
func Body(n uint64) string {
v := sent.Get(seqKey(n))
if v == nil {
return ""
}
return hx(v.(*decision).body)
}
// -------------------------------------------------------------- encoding --
func be32(n uint32) []byte { return binary.BigEndian.AppendUint32(nil, n) }
func be64(n uint64) []byte { return binary.BigEndian.AppendUint64(nil, n) }
// body is kind u8 ‖ seq u64 BE ‖ params (§13).
func body(kind uint8, n uint64, params []byte) []byte {
b := make([]byte, 0, 9+len(params))
b = append(b, kind)
b = append(b, be64(n)...)
return append(b, params...)
}
// mustFit refuses a body above MaxDecisionBody: the one check every dispatch makes, so no builder can author a
// decision the mailbox cannot deliver.
func mustFit(raw []byte) {
if len(raw) > MaxDecisionBody {
panic("hlgov: the decision body is " + strconv.Itoa(len(raw)) + " bytes, above the " + strconv.Itoa(MaxDecisionBody) + " the mailbox delivers (MaxDecisionBody): it would stick the sequence with its number untaken")
}
}
// dispatch sends a decision with the next number and records it; a body above MaxDecisionBody is refused first.
func dispatch(cur realm, kind uint8, params []byte, text string, t int64) uint64 {
n := last + 1
raw := body(kind, n, params)
mustFit(raw)
id := hlmailbox.Dispatch(cross(cur), destination, recipient, raw)
last = n
sent.Set(seqKey(n), &decision{kind: kind, body: raw, at: t, id: hx(id[:]), count: 1, text: text})
chain.Emit("DecisionSent", "number", u64s(n), "kind", strconv.Itoa(int(kind)), "id", hx(id[:]))
return n
}
// Redispatch sends an executed decision again — the same number and parameters, a new message — by anyone, until
// the admin program has recorded it (a copy it has recorded is accepted and ignored there).
func Redispatch(cur realm, n uint64) {
caller(cur)
v := sent.Get(seqKey(n))
if v == nil {
panic("hlgov: no decision " + u64s(n))
}
d := v.(*decision)
id := hlmailbox.Dispatch(cross(cur), destination, recipient, d.body)
d.id = hx(id[:])
d.count++
chain.Emit("DecisionSent", "number", u64s(n), "kind", strconv.Itoa(int(d.kind)), "id", hx(id[:]))
}
// ------------------------------------------------------------- builders --
func propose(cur realm, kind, text string, apply func(cur realm, made, t int64)) Request {
if !cur.IsCurrent() {
panic("hlgov: 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
}
apply(cur, made, t)
return nil
}
return Request{proposal: dao.NewProposalRequest("hlgov: "+kind, text, dao.NewSimpleExecutor(0, cur, cb, text)), text: text, decide: cb}
}
// proposeKind is a Solana decision's builder: at execution it dispatches the message and records the decision as
// applied; the parameters were checked at creation and are checked again then, the body's size with them.
func proposeKind(cur realm, kind uint8, name, text string, params []byte, check func()) Request {
mustBeLive()
mustFit(body(kind, 0, params))
check()
return propose(cur, name, text, func(cur realm, made, t int64) {
mustBeLive()
check()
n := dispatch(cur, kind, params, text, t)
d := ledger.Record(name, text, kindParams{kind: kind, params: params}, made, t, t)
ledger.Apply(d, t, "dispatched as decision "+u64s(n))
})
}
func parseNumber(p string) uint64 {
n, err := strconv.ParseUint(strings.TrimSpace(p), 10, 64)
if err != nil || n == 0 {
panic("hlgov: not a decision number: " + p)
}
return n
}
// salt is the 8 bytes a cancel body starts with (§13: random, ignored by the program,
// so no body is predictable and two cancels of one list differ). gno.land gives a realm no block
// hash, so it is sha256 over what the block and the decision give — the chain id, the height, the block time, the
// mailbox's nonce, the decision number and the ledger's next id — drawn in the executing transaction; the decision
// number alone makes two cancels of one list differ, the rest make it as unpredictable as the block it lands in.
func salt(t int64) []byte {
b := []byte(runtime.ChainID())
b = append(b, be64(uint64(runtime.ChainHeight()))...)
b = append(b, be64(uint64(t))...)
b = append(b, be32(hlmailbox.Count())...)
b = append(b, be64(last+1)...)
b = append(b, be64(uint64(ledger.Last()+1))...)
h := sha256.Sum256(b)
return h[:8]
}
// NewCancelRequest is kind 1: cancel pending decisions of the mailbox channel on Solana (channel 0, the only one
// this realm writes), by a list of numbers (comma separated, at most 16: form 0) or by a range "from-to",
// inclusive (form 1); each number one this realm dispatched. It executes at once there. The body is
// `salt u64 ‖ form u8 ‖ …` (§13), the salt drawn when the proposal executes, so the description names the numbers
// and the ledger's note and the decision's page carry the salt.
func NewCancelRequest(cur realm, numbers string) Request {
mustBeLive()
var params []byte
var top uint64
if i := strings.Index(numbers, "-"); i >= 0 {
from, to := parseNumber(numbers[:i]), parseNumber(numbers[i+1:])
if to < from {
panic("hlgov: the range runs from the lower number to the higher")
}
params = append([]byte{1, 0}, be64(from)...)
params = append(params, be64(to)...)
top = to
} else {
var ns []uint64
for _, p := range strings.Split(numbers, ",") {
if strings.TrimSpace(p) == "" {
continue
}
n := parseNumber(p)
for _, x := range ns {
if x == n {
panic("hlgov: number " + strings.TrimSpace(p) + " named twice")
}
}
ns = append(ns, n)
if n > top {
top = n
}
}
if len(ns) == 0 || len(ns) > maxCancel {
panic("hlgov: a cancel names 1 to " + strconv.Itoa(maxCancel) + " numbers, or a range")
}
params = []byte{0, byte(len(ns))}
for _, n := range ns {
params = append(params, 0)
params = append(params, be64(n)...)
}
}
text := "cancel decisions " + numbers
mustFit(body(KindCancel, 0, append(make([]byte, 8), params...))) // with the salt's 8 bytes; dispatch checks it again
check := func() {
if top > last {
panic("hlgov: decision " + u64s(top) + " was never dispatched")
}
}
check()
return propose(cur, "cancel", text, func(cur realm, made, t int64) {
mustBeLive()
check()
p := append(salt(t), params...)
n := dispatch(cur, KindCancel, p, text, t)
note := "dispatched as decision " + u64s(n) + ", salt " + hx(p[:8])
// a cancelled kind 6 for a route of this chain clears the enrolment note it left, while that note is the
// latest (R37, AS2): the route's refund clock restarts with a re-proposal, instead of opening on a kind 6
// Solana never executed
eachCancelled(numbers, func(num uint64, d *decision) {
if d.kind != KindRouter || d.route == "" {
return
}
if h, _ := hlmailbox.Enrolled(d.route); h != d.height {
return
}
hlmailbox.ClearEnrolled(cross(cur), d.route)
note += "; the enrolment note of " + d.route + " cleared (kind 6 #" + u64s(num) + " cancelled): its refund clock restarts with a re-proposal"
})
d := ledger.Record("cancel", text, kindParams{kind: KindCancel, params: p}, made, t, t)
ledger.Apply(d, t, note)
})
}
// eachCancelled walks the decisions a cancel's numbers name — the list, or every dispatched number of the range —
// in number order.
func eachCancelled(numbers string, fn func(n uint64, d *decision)) {
if i := strings.Index(numbers, "-"); i >= 0 {
from, to := parseNumber(numbers[:i]), parseNumber(numbers[i+1:])
sent.Iterate(seqKey(from), seqKey(to+1), func(k string, v any) bool {
n, _ := strconv.ParseUint(strings.TrimLeft(k, "0"), 10, 64)
fn(n, v.(*decision))
return false
})
return
}
for _, p := range strings.Split(numbers, ",") {
if strings.TrimSpace(p) == "" {
continue
}
n := parseNumber(p)
if v := sent.Get(seqKey(n)); v != nil {
fn(n, v.(*decision))
}
}
}
// NewUnpauseRequest is kind 2: clear the flags set before its delivery on the pausable ISM (object 0) or the admin
// program (object 1), 24 hours after it arrives, unless two guardians' flags hold.
func NewUnpauseRequest(cur realm, object uint8) Request {
if object > 1 {
panic("hlgov: the object is 0 (the pausable ISM) or 1 (the admin program)")
}
name := "the pausable ISM"
if object == 1 {
name = "the admin program"
}
return proposeKind(cur, KindUnpause, "unpause", "unpause "+name, []byte{object}, func() {})
}
func parseToken(token uint8) string {
switch token {
case 0:
return "GNOT"
case 1:
return "BUBBLE"
}
panic("hlgov: the token is 0 (GNOT) or 1 (BUBBLE)")
}
// NewSetTokenISMRequest is kind 3: point a token (0 GNOT, 1 BUBBLE) at the pausable ISM, or at none (all zeros).
func NewSetTokenISMRequest(cur realm, token uint8, ism string) Request {
name := parseToken(token)
k := mustKey(ism)
if k != mustKey(launchPausableISM) && k != ([32]byte{}) {
panic("hlgov: the ISM must be the pausable ISM " + launchPausableISM + " or all zeros")
}
params := append([]byte{token}, k[:]...)
return proposeKind(cur, KindTokenISM, "set token ISM", "set "+name+"'s ISM to "+hx(k[:]), params, func() {})
}
// NewSetClientLayoutRequest is kind 4, which §13 reserves (v27, AM7): the client's state layout the pausable ISM
// and the immutable admin program read is fixed for the deployment's life (version 1), a client upgrade keeps it,
// and a new layout is a successor admin program and pausable ISM by kind 9. The builder refuses every call, so no
// kind-4 message ever leaves here; the admin program refuses one at execution too.
func NewSetClientLayoutRequest(cur realm, target string, version uint8) Request {
panic("hlgov: kind 4 is reserved: the client's state layout is fixed for the deployment's life (version 1); a new layout is a successor by kind 9")
}
// parseSeatChanges reads "seat:pubkey" pairs (comma separated; the pubkey in base58 or hex): seats 1–6, two
// guardian seats at most, four entries at most, no seat or key twice.
func parseSeatChanges(changes string) ([]int, [][32]byte) {
var ns []int
var ks [][32]byte
g := 0
for _, p := range strings.Split(changes, ",") {
i := strings.Index(p, ":")
if i < 0 {
panic("hlgov: a change is seat:pubkey, not " + p)
}
n, err := strconv.Atoi(strings.TrimSpace(p[:i]))
if err != nil || n < 1 || n > seatCount {
panic("hlgov: the seat must be 1 to 6, not " + p[:i])
}
for _, x := range ns {
if x == n {
panic("hlgov: seat " + strconv.Itoa(n) + " named twice")
}
}
k := mustKey(p[i+1:])
if k == ([32]byte{}) {
panic("hlgov: a pubkey of zeros")
}
for _, x := range ks {
if x == k {
panic("hlgov: a pubkey named twice")
}
}
if n <= guardianSeats {
g++
}
ns = append(ns, n)
ks = append(ks, k)
}
if len(ns) == 0 || len(ns) > maxSeatChanges {
panic("hlgov: 1 to " + strconv.Itoa(maxSeatChanges) + " seats per decision")
}
if g > 2 {
panic("hlgov: two guardian seats at most per decision")
}
return ns, ks
}
// seatWarnings names the keys that hold a seat as this realm last set it. The real seats are Solana's, and the
// admin program refuses a seat's current key itself (§6.5), spending the decision: a true no-op. The mirror here
// can sit ahead of the truth (a kind 5 the admin program spent) or behind it (a kind 5 of another decision moved a seat),
// so it is no ground to refuse a proposal — the builder warns in the description and the member reads
// `hlwatch`'s list of the seats as they stand.
func seatWarnings(ns []int, ks [][32]byte) string {
var parts []string
for i := range ns {
for s := 1; s <= seatCount; s++ {
if solSeats[s] == ks[i] {
parts = append(parts, hx(ks[i][:])+" holds seat "+strconv.Itoa(s)+" as last set here")
}
}
}
if len(parts) == 0 {
return ""
}
return " (warning: " + strings.Join(parts, "; ") + " — the admin program spends a decision naming a seat's current key, so check the seats as they stand on Solana before voting)"
}
// NewSetGuardiansRequest is kind 5: replace guardian seats (1–4, two at most) and watch slots (5–6) on Solana,
// four entries at most. A key that holds a seat as this realm last set it is warned about in the description,
// not refused: the admin program's own check spends a decision naming a seat's current key, and this realm's
// mirror of the seats can drift from the truth. It lands 7 days after delivery through any flag or hold.
func NewSetGuardiansRequest(cur realm, changes string) Request {
mustBeLive()
ns, ks := parseSeatChanges(changes)
params := []byte{byte(len(ns))}
parts := make([]string, len(ns))
for i, n := range ns {
params = append(params, byte(n))
params = append(params, ks[i][:]...)
parts[i] = "seat " + strconv.Itoa(n) + " to " + hx(ks[i][:])
}
text := "set guardians and watch keys: " + strings.Join(parts, ", ") + seatWarnings(ns, ks)
return propose(cur, "set guardians", text, func(cur realm, made, t int64) {
mustBeLive()
n := dispatch(cur, KindGuardians, params, text, t)
for i, s := range ns {
solSeats[s] = ks[i]
}
d := ledger.Record("set guardians", text, kindParams{kind: KindGuardians, params: params, seats: ns, keys: ks}, made, t, t)
ledger.Apply(d, t, "dispatched as decision "+u64s(n))
})
}
// NewEnrollRouterRequest is kind 6: enroll a token's remote router for a domain. For gno.land's own domain the
// router must be a route realm registered with hlmailbox — the launch routes, and the successors their migrations
// named — as 32 bytes: the synthetic program takes every Dispatch from the router it enrolls as a mint order, and
// hlmailbox's Dispatch is open to any realm, so any other address would mint synthetic that no lock backs; the
// token's own route (R36), unmigrated, and — a successor — one that pulled page 0 (R35). The rules are checked
// when the proposal is made and again when it executes. The closure then notes with the mailbox the route it
// enrolled and the height (hlmailbox.NoteEnrolled, AR1): that route's refund builder waits 14 days after the note
// (R37: a week for the delivery, a week for Solana's clock), since a refunded send stays deliverable on Solana
// until the predecessor's router is replaced; a cancel of the kind 6 clears the note (NewCancelRequest).
func NewEnrollRouterRequest(cur realm, token uint8, domain uint32, router string) Request {
mustBeLive()
name := parseToken(token)
k := mustKey(router)
if k == ([32]byte{}) || domain == 0 {
panic("hlgov: the router and the domain must be set")
}
local := domain == hlmailbox.LocalDomain()
check := func() string {
if !local {
return ""
}
path := routePathOf(k)
if path == "" {
panic("hlgov: for this chain's domain the router must be a route realm registered with hlmailbox, not " + hx(k[:]))
}
// the token's own route, and a live one (R36): the other token's route — or its successor — as this
// token's router strands this token's burns behind per-id votes until a corrective kind 6 lands, refuses
// its sends on Solana meanwhile, and writes the enrolment note on the other route, opening its refunds
// while the other token's router still delivers (AR1's double mint again); a migrated route's successor
// is the token's router, never the route itself
if sym := hlmailbox.RouteSymbol(path); sym == "" {
panic("hlgov: " + path + " is registered for no token (it never announced the route it succeeds): a kind 6 names the token's own route")
} else if sym != name {
panic("hlgov: " + path + " is the " + sym + " route's, not " + name + "'s: a kind 6 names the token's own route")
}
if s := hlmailbox.Successor(path); s != "" {
panic("hlgov: " + path + " migrated to " + s + ": never a migrated route, since its successor is the token's router")
}
// a successor that pulled nothing is never enrolled (R35): before page 0 its migration may still be
// re-pointed (AR2) and the route dropped — a realm in nobody's chain that Solana would then name the
// router for the deployment's life, every burn's recipient, flaggable by nobody
if pred := hlmailbox.Predecessor(path); pred != "" && !hlmailbox.Pulled(path) {
panic("hlgov: " + path + " succeeds " + pred + " and has pulled nothing yet (page 0 is not in): a kind 6 enrolling it waits for its first page, since a migrate that pulled nothing may be re-pointed and Solana must never name a dropped route")
}
return path
}
params := append(append([]byte{token}, be32(domain)...), k[:]...)
text := "enroll " + name + "'s router for domain " + strconv.FormatUint(uint64(domain), 10) + ": " + hx(k[:])
mustFit(body(KindRouter, 0, params))
check()
return propose(cur, "enroll router", text, func(cur realm, made, t int64) {
mustBeLive()
path := check()
n := dispatch(cur, KindRouter, params, text, t)
note := "dispatched as decision " + u64s(n)
if path != "" {
h := runtime.ChainHeight()
hlmailbox.NoteEnrolled(cross(cur), path, h)
sd := sent.Get(seqKey(n)).(*decision)
sd.route, sd.height = path, h
note += "; " + path + " noted enrolled on Solana at height " + itoa(h)
}
d := ledger.Record("enroll router", text, kindParams{kind: KindRouter, params: params}, made, t, t)
ledger.Apply(d, t, note)
})
}
// routePathOf is the pkgpath of the route realm hlmailbox registers whose address, as 32 bytes, is k; "" if none.
func routePathOf(k [32]byte) string {
for _, path := range hlmailbox.Routes() {
if b, err := hl.AddressToBytes32(chain.PackageAddress(path)); err == nil && b == k {
return path
}
}
return ""
}
// NewSetProtocolFeeRequest is kind 7: the mailbox's protocol fee (lamports, at most its 0.05 SOL maximum) and its
// beneficiary (the treasurer's Solana key).
func NewSetProtocolFeeRequest(cur realm, lamports uint64, beneficiary string) Request {
if lamports > maxProtocolFee {
panic("hlgov: the fee is at most " + u64s(maxProtocolFee) + " lamports, the mailbox's maximum")
}
k := mustKey(beneficiary)
if k == ([32]byte{}) {
panic("hlgov: a beneficiary of zeros")
}
params := append(be64(lamports), k[:]...)
return proposeKind(cur, KindProtocolFee, "set protocol fee", "set the protocol fee to "+u64s(lamports)+" lamports for "+hx(k[:]), params, func() {})
}
// NewUpgradeRequest is kind 8: upgrade a program from a staged buffer whose ELF hashes to elfHash (sha256, hex) —
// never the admin program's own id (§13: its upgrade authority is burned, so the decision could only be spent; a
// new admin program is a successor by kind 9), checked when the proposal is made and when it executes.
func NewUpgradeRequest(cur realm, program, buffer, elfHash string) Request {
p, b, h := mustKey(program), mustKey(buffer), mustKey(elfHash)
if p == ([32]byte{}) || b == ([32]byte{}) || h == ([32]byte{}) || p == b {
panic("hlgov: the program, the buffer and the hash must be set and distinct")
}
check := func() {
if p == recipient {
panic("hlgov: never the admin program's own id (" + hx(p[:]) + "): it is immutable, a new admin program is a successor by kind 9")
}
}
params := append(append(append([]byte{}, p[:]...), b[:]...), h[:]...)
return proposeKind(cur, KindUpgrade, "upgrade", "upgrade "+hx(p[:])+" from buffer "+hx(b[:])+" with ELF sha256 "+hx(h[:]), params, check)
}
// NewTransferToSuccessorRequest is kind 9: hand every authority to an immutable successor admin program — never
// the admin program itself, the decision recipient this realm knows, checked when the proposal is made and again
// when it executes (a recipient swap landing in between would otherwise turn a pre-armed transfer into one the
// admin program only spends: it re-points every authority to itself and dies on its own SuccessorInit, the
// programs lane's S-15), as kind 8 refuses its self-upgrade; and never a former recipient (R29), a retired program
// whose successor_init answers NotInherited. The admin program refuses a successor whose programdata shows an
// upgrade authority; the builder cannot read Solana, so a member checks that by RPC before proposing.
func NewTransferToSuccessorRequest(cur realm, program string) Request {
p := mustKey(program)
if p == ([32]byte{}) {
panic("hlgov: the successor must be set")
}
check := func() {
if p == recipient {
panic("hlgov: never the admin program itself (" + hx(p[:]) + "), not the current admin program as its own successor: the admin program would only spend the decision")
}
mustNotBeFormer(p, "admin program")
}
return proposeKind(cur, KindSuccessor, "transfer to successor", "transfer every authority to "+hx(p[:]), p[:], check)
}
// routeMaximum is a token's per-message maximum on its gno.land route now (base units): what a send may carry out.
func routeMaximum(token uint8) uint64 {
if token == 0 {
return uint64(hlgnot.Maximum())
}
return uint64(hlbubble.Maximum())
}
// NewSetMintLimitsRequest is kind 12: a token's (0 GNOT, 1 BUBBLE) per-message maximum and rolling day cap on the
// pausable ISM, in base units (§13: token u8 ‖ maximum u64 ‖ day cap u64; compiled there at launch as 25,000 a
// message and 100,000 a day of each token). A maximum of 0 (every mint refused) and a day cap below the maximum (a
// message at the maximum could never pass) are refused when the proposal is made: the admin program and the
// pausable ISM take any values, so the nonsense is caught here, as every builder catches it early. The maximum is
// never below the token's route's per-message maximum on gno.land (R15), checked when the proposal is made and
// when it executes: a send between the two would leave gno.land and be refused at delivery for good, stranded
// until a refund by id — so a raise is the Solana limit first (this), the route's maximum after, and a lowering
// the other way round. It lands 7 days after delivery.
func NewSetMintLimitsRequest(cur realm, token uint8, maximum, dayCap uint64) Request {
name := parseToken(token)
if maximum == 0 {
panic("hlgov: the per-message maximum is at least 1")
}
if dayCap < maximum {
panic("hlgov: the day cap is at least the per-message maximum")
}
check := func() {
if rm := routeMaximum(token); maximum < rm {
panic("hlgov: a per-message maximum of " + u64s(maximum) + " is below the " + name + " route's maximum of " + u64s(rm) + " (base units): a send between the two would strand on Solana — lower the route's maximum first, then this")
}
}
params := append([]byte{token}, be64(maximum)...)
params = append(params, be64(dayCap)...)
text := "set " + name + "'s mint limits: " + u64s(maximum) + " a message, " + u64s(dayCap) + " a day (base units)"
return proposeKind(cur, KindMintLimits, "set mint limits", text, params, check)
}
// mustRaise refuses a sync sequence that would not raise the counter (§5.3: it never lowers it): n is the number
// the next decision takes, so the counter becomes n-1, which must be above the counter now — and by at most 2^32,
// the realm's own bound (§13, R18; kind 10 is reserved since v35 and moves nothing on Solana), so a mistyped
// number can neither wrap the counter onto numbers the admin program recorded nor put every decision beyond the
// next number it expects.
func mustRaise(n uint64) {
if n == last+1 {
panic("hlgov: the next number is " + u64s(n) + " already")
}
if n <= last {
panic("hlgov: sync sequence only ever raises the counter: it stands at " + u64s(last) + " (the next number is " + u64s(last+1) + ") and " + u64s(n) + " is not above it")
}
if n > last+1+syncReach {
panic("hlgov: sync sequence reaches at most 2^32 above the next number (the realm's own bound): the next number is " + u64s(last+1) + " and " + u64s(n) + " is beyond " + u64s(last+1+syncReach))
}
}
// NewSyncSequenceRequest raises this realm's counter so that the next decision takes number n — the number the
// admin program expects next after a foreign decision took one — at once; nothing moves on Solana. It only ever
// raises: a number at or below the next one is refused when the proposal is made and again when it executes (the
// counter may have moved in between), so a number the admin program recorded is never reused.
func NewSyncSequenceRequest(cur realm, n uint64) Request {
mustBeLive()
if n == 0 {
panic("hlgov: the next number is at least 1")
}
mustRaise(n)
text := "sync sequence: the next decision takes number " + u64s(n) + " (it was " + u64s(last+1) + ")"
return propose(cur, "sync sequence", text, func(cur realm, made, t int64) {
mustBeLive()
mustRaise(n)
last = n - 1
d := ledger.Record("sync sequence", text, sequenceParams{n}, made, t, t)
ledger.Apply(d, t, "at once")
chain.Emit("SequenceSynced", "next", u64s(n))
})
}
// NewSetDecisionRecipientRequest changes the program decisions are addressed to, 7 days after the proposal
// executes: how a successor admin program receives them. Never the current recipient, and never a former one
// (R29: a retired program answers Retired to every decision) — checked when the proposal is made, in its closure
// and when the queued change would apply.
func NewSetDecisionRecipientRequest(cur realm, program string) Request {
mustBeLive()
p := mustKey(program)
if p == ([32]byte{}) {
panic("hlgov: the recipient must be set")
}
check := func() {
if p == recipient {
panic("hlgov: the recipient must differ from the current one (" + hx(p[:]) + ")")
}
mustNotBeFormer(p, "decision recipient")
}
check()
text := "set decision recipient to " + hx(p[:]) + " (now " + hx(recipient[:]) + ")"
return propose(cur, "set decision recipient", text, func(cur realm, made, t int64) {
mustBeLive()
check()
d := ledger.Record("set decision recipient", text, recipientParams{p}, made, t, t+decisions.Delay)
d.Note = "queued 7 days"
})
}
// NewCancelQueuedRequest cancels a queued change of this realm (a recipient swap), at once; it is proposed before
// Launch too.
func NewCancelQueuedRequest(cur realm, id int64) Request {
d := ledger.Get(id)
if d == nil || !d.Pending() {
panic("hlgov: decision " + itoa(id) + " is not pending")
}
text := "cancel queued change " + itoa(id) + " (" + d.Text + ")"
return propose(cur, "cancel queued", text, func(cur realm, made, t int64) {
if _, err := ledger.Cancel(id, t); err != nil {
panic("hlgov: " + err.Error())
}
c := ledger.Record("cancel queued", text, cancelParams{id}, made, t, t)
ledger.Apply(c, t, "at once: cancelled")
})
}
// Execute applies a queued change (a recipient swap) whose 7 days have passed; anyone may call it. A swap decided
// while its target was nobody applies only while that holds (R29): one that finds its target the recipient already
// (a second swap to the same program) or a former recipient (replaced since) is refused and stays pending for
// GovDAO's cancel; the recipient it replaces joins the former ones.
func Execute(cur realm, id int64) {
caller(cur)
mustBeLive()
t := now()
d, err := ledger.Due(id, t)
if err != nil {
panic("hlgov: " + err.Error())
}
p, ok := d.Params.(recipientParams)
if !ok {
panic("hlgov: decision " + itoa(id) + " has nothing to apply")
}
if p.to == recipient {
panic("hlgov: " + hx(p.to[:]) + " is the decision recipient already: cancel decision " + itoa(id))
}
mustNotBeFormer(p.to, "decision recipient")
former = append(former, recipient)
recipient = p.to
ledger.Apply(d, t, "applied after the delay")
chain.Emit("RecipientSet", "program", hx(recipient[:]))
}
// --------------------------------------------------------------- pages --
// Render: "" the page; "json"; "decisions" and "decisions.json" the ledger; "decision/<n>" one dispatched decision.
func Render(path string) string {
switch {
case path == "":
var b strings.Builder
b.WriteString("# GovDAO's decisions for Solana\n\n")
b.WriteString("A decision made with one of this realm's builders — the governor's own until it yields, a GovDAO proposal's execution after — sends it to the admin program on Solana with the next sequence number; the admin program records it by number and executes it after its clock. Anyone may re-dispatch an executed decision until it is recorded.\n\n")
if hlmailbox.Live() {
b.WriteString("- **live** since " + itoa(hlmailbox.LaunchedAt()) + "\n")
} else {
b.WriteString("- **not launched**: no decision is sent before the Launch decision\n")
}
b.WriteString("- " + decisions.GovernorLine(launchGovernor, hlmailbox.Yielded()) + "\n")
b.WriteString("- destination: domain " + strconv.FormatUint(uint64(destination), 10) + ", recipient `" + hx(recipient[:]) + "`\n")
if len(former) > 0 {
parts := make([]string, len(former))
for i, k := range former {
parts[i] = "`" + hx(k[:]) + "`"
}
b.WriteString("- former recipients (retired; never a successor, never the recipient again): " + strings.Join(parts, ", ") + "\n")
}
b.WriteString("- launch client: `" + hx(client[:]) + "` (the pausable ISM's target; its state layout is fixed for the deployment's life at version 1 — kind 4 is reserved and refused here)\n")
b.WriteString("- sequence: starts at " + u64s(launchSequence) + " (compiled: the predecessor's last number, 0 for a chain's first r/hlgov); last number " + u64s(last) + "; the next takes number " + u64s(last+1) + "; " + strconv.Itoa(sent.Size()) + " sent from here\n")
b.WriteString("- " + decisions.Clocks() + " (the recipient swap's delay and every builder's deadline; Solana's clocks are the admin program's)\n")
b.WriteString("- Solana seats as last set here:\n")
for i := 1; i <= seatCount; i++ {
kind := "guardian"
if i > guardianSeats {
kind = "watch key"
}
b.WriteString(" - seat " + strconv.Itoa(i) + " (" + kind + "): `" + hx(solSeats[i][:]) + "`\n")
}
if sent.Size() > 0 {
b.WriteString("\n## Sent\n\n")
sent.ReverseIterateByOffset(0, 20, func(k string, v any) bool {
d := v.(*decision)
b.WriteString("- #" + strings.TrimLeft(k, "0") + " kind " + strconv.Itoa(int(d.kind)) + ": " + d.text + " (sent " + strconv.Itoa(d.count) + "×, last id `" + d.id + "`)\n")
return false
})
}
b.WriteString("\n## Decisions\n\n" + ledger.Page())
return b.String()
case path == "json":
fs := Former()
for i := range fs {
fs[i] = strconv.Quote(fs[i])
}
return "{\"address\":" + strconv.Quote(string(Address())) + ",\"live\":" + strconv.FormatBool(hlmailbox.Live()) +
"," + decisions.GovernorJSON(launchGovernor, hlmailbox.Yielded()) +
",\"destination\":" + strconv.FormatUint(uint64(destination), 10) + ",\"recipient\":" + strconv.Quote(hx(recipient[:])) + ",\"former\":[" + strings.Join(fs, ",") + "]" +
",\"start\":" + u64s(launchSequence) + ",\"last\":" + u64s(last) + ",\"next\":" + u64s(last+1) + ",\"clocks\":" + decisions.ClocksJSON() + ",\"decisions\":" + itoa(ledger.Last()) + "}"
case path == "decisions":
return "# Decisions\n\n" + ledger.Page()
case path == "decisions.json":
return ledger.JSON()
case strings.HasPrefix(path, "decision/"):
n, err := strconv.ParseUint(path[len("decision/"):], 10, 64)
if err != nil {
return "null"
}
v := sent.Get(seqKey(n))
if v == nil {
return "null"
}
d := v.(*decision)
return "{\"number\":" + u64s(n) + ",\"kind\":" + strconv.Itoa(int(d.kind)) + ",\"body\":" + strconv.Quote(hx(d.body)) +
",\"id\":" + strconv.Quote(d.id) + ",\"count\":" + strconv.Itoa(d.count) + ",\"at\":" + itoa(d.at) + ",\"text\":" + strconv.Quote(d.text) + "}"
}
return "unknown path; see the page"
}