gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hlmailbox⧉

1// Package hlmailbox is the gno.land end of the bridge's message layer (bridge/PLAN.md §5.1): realms send messages to2// other chains through it and take the messages other chains send them from it. Messages, ids and the merkle tree3// are Hyperlane's byte for byte (gno.land/p/…/hyperlane/v0), so the Solana side runs Hyperlane's own programs.4//5// Out. Dispatch takes a message from the realm that calls it, numbers it, puts its id in the merkle tree, keeps the6// message, and emits the Dispatch event the Solana light client proves from LastResultsHash (§13: id, nonce, origin,7// destination, sender, recipient, hash). Reemit emits it again from a fresh block, by anyone.8//9// In. A recipient realm pulls its own messages: it calls Process with the message and the verifier's metadata;10// Process checks the caller is the recipient, that the message is for this chain and was never delivered, marks it11// delivered, and only then asks the active verifier — a realm that registered itself here, chosen by GovDAO by12// pkgpath — whether the message is genuine; a verifier's error is a panic, so the transaction and the mark revert13// together and a refused message stays deliverable.14//15// Who may change what. Nobody holds an admin key: every setting moves by a decision made with this realm's16// builders (gov.gno), at once or after 7 days (§5.3), and nothing but Launch and cancel before the one-shot17// Launch. Who decides is the governor's (M1k): the compiled launchGovernor alone, by its own call through Govern,18// until it yields (Yield, once, for every bridge realm at once), and GovDAO's proposals from then on — or from the19// first block, when no governor was compiled. The guardians and watch keys (flags.gno) can only pause: three flags20// per key per route — sends, credits, payouts — which the routes ask about with Paused. Every launch value is21// compiled in below and written by init.22package hlmailbox2324import (25	"chain"26	"chain/runtime"27	"crypto/sha256"28	"encoding/hex"29	"strconv"30	"strings"3132	"gno.land/p/nt/avl/v0"33	"gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/decisions/v0"34	hl "gno.land/p/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/hyperlane/v0"35)3637const (38	namespace = "gno.land/r/g1zdaz6sypk5tdsjc2fzsqrrn4ttn8qzmnl4waqp/"39	pkgPath   = namespace + "hlmailbox" // must match gnomod.toml4041	// DomainMainnet and DomainTest are gno.land's Hyperlane domain ids, "GnoL" and "GnoT" in ASCII; nobody in the42	// Hyperlane registry holds either (2026-10-10). gnoland-1 is mainnet; every other chain is a test chain.43	DomainMainnet  = uint32(1198419788)44	DomainTest     = uint32(1198419796)45	mainnetChainID = "gnoland-1"4647	// SolanaMainnet and SolanaLocal are the destination's domains: Solana's own on mainnet; on any other gno chain48	// the one the local test validator and the e2e run use (Hyperlane's "solanatestnet"). Devnet is 1399811151.49	SolanaMainnet = uint32(1399811149)50	SolanaLocal   = uint32(1399811150)5152	// The launch values (§5.3): the active verifier, the signers and their rule, the routes. The signer keys below53	// are PLACEHOLDERS (the three test signers of the vectors) until the operator's three machines exist; the54	// launch vote reads the real ones in the deployed source. bridge/local/e2e.sh swaps them for its run's keys.55	launchVerifier  = namespace + "hlverifier"56	launchThreshold = 257	launchSigners   = "e2c2b621677535e5b2a0a92f37aec61e7ce0397cf1cf713f91a18227eafec2ef,d837b6369a315b6d26babddc0af241d8908a1809481b29e98365965cf8301689,c0b2dc0da05eb6ee67b68068611a72858f3093c79e8d90589ff2ac1f0ea4da26"58	launchRouteGNOT   = namespace + "hlgnot"59	launchRouteBUBBLE = namespace + "hlbubble"60	hlgovPath         = namespace + "hlgov" // r/hlgov: the one realm that notes a route's enrolment on Solana (NoteEnrolled, AR1)6162	maxSigners = 255 // a signature names its signer in one byte63)6465// launchGovernor is the governor (M1k, §5.3): the one address whose own direct call decides — through Govern, the66// same closures, checks, queues and delays a GovDAO proposal's execution runs — until it yields (Yield), from67// which block GovDAO's proposals decide and nothing else; "" means GovDAO from the first block. Every bridge68// realm compiles the same address and refuses to deploy with another (its init reads Governor here), and reads69// Yielded here, so no realm is ever governed apart from the rest. A PLACEHOLDER (testutils.TestAddress("hl-70// governor")) until the launch notice names the real key; bridge/local/e2e.sh swaps it for gnodev's test1 in all71// six realms. Its own line, so one sed on `^const launchGovernor = address(…)` finds it in every realm.72const launchGovernor = address("g1ecsuj0q572jr0dhu29q9njtnmw03hyu7tyyvv6")7374var (75	localDomain  = domainOf(runtime.ChainID())76	launchOrigin = solanaOf(runtime.ChainID())77	// hook is this realm's address as Hyperlane carries it: the merkle tree hook id inside every checkpoint signed78	// for a message from here.79	hook = mustBytes32(chain.PackageAddress(pkgPath))8081	tree hl.Tree82	sent avl.Tree // nonceKey(nonce) → *sentMsg83	done avl.Tree // message id in hex → the block height it was delivered at8485	verifiers avl.Tree // pkgpath → Verifier, every realm that registered86	active    avl.Tree // domainKey(origin) → the pkgpath of the verifier GovDAO chose for that origin8788	signerKeys []Key // the one signer set, in the order signatures name them89	signerRule Rule9091	live       bool  // after the Launch decision executed92	launchedAt int64 // unix time it did9394	yielded int64 // the block height the governor yielded at (Yield); 0 until then — every bridge realm reads it9596	ledger decisions.Ledger97)9899// sentMsg is one dispatched message and the checkpoint it made.100type sentMsg struct {101	raw    string   // the message as it went out102	root   [32]byte // the tree's root right after its id went in, at index = its nonce103	height int64104}105106// Key is a signer's ed25519 public key.107type Key [32]byte108109// Rule is how many signers must sign: Threshold of the set, or — when both groups are named (§11.13) — one key of110// GroupA and one of GroupB. The verifier applies it; Satisfiable says whether a set can still meet it.111type Rule struct {112	Threshold int113	GroupA    []Key114	GroupB    []Key115}116117// TwoGroups is whether the rule is "one of A and one of B" rather than a threshold.118func (r Rule) TwoGroups() bool { return len(r.GroupA) > 0 && len(r.GroupB) > 0 }119120// String says the rule in words.121func (r Rule) String() string {122	if r.TwoGroups() {123		return "one of group A (" + keysHex(r.GroupA) + ") and one of group B (" + keysHex(r.GroupB) + ")"124	}125	return strconv.Itoa(r.Threshold) + " of the set"126}127128func (r Rule) equal(o Rule) bool {129	return r.Threshold == o.Threshold && sameKeys(r.GroupA, o.GroupA) && sameKeys(r.GroupB, o.GroupB)130}131132// sameAs is whether two rules are the same rule, the groups compared as sets.133func (r Rule) sameAs(o Rule) bool {134	return r.Threshold == o.Threshold && sameSet(r.GroupA, o.GroupA) && sameSet(r.GroupB, o.GroupB)135}136137// Verifier decides whether an incoming message is genuine (§5.1). A verifier is a realm; it registers once with138// RegisterVerifier and GovDAO activates it by pkgpath. Both methods are non-crossing. An implementation is a type139// declared in the registering realm: its methods then run under that realm's authority (borrow rule #1) and can140// write nothing of this realm's. A type declared in /p/ with no object to anchor on (`type V int`) would run under141// this realm's own authority instead — the no-anchor case — which RegisterVerifier cannot tell apart, so GovDAO142// activates a verifier whose source it has read; what the mailbox hands a verifier is the recipient's bytes143// (Verify) or a copy of its own keys (Satisfiable), never a value it keeps.144type Verifier interface {145	Verify(origin uint32, metadata, message []byte) error146	Satisfiable(signers []Key) bool147}148149func domainOf(chainID string) uint32 {150	if chainID == mainnetChainID {151		return DomainMainnet152	}153	return DomainTest154}155156func solanaOf(chainID string) uint32 {157	if chainID == mainnetChainID {158		return SolanaMainnet159	}160	return SolanaLocal161}162163func mustBytes32(a address) [32]byte {164	b, err := hl.AddressToBytes32(a)165	if err != nil {166		panic(err.Error())167	}168	return b169}170171func caller(cur realm) address {172	if !cur.IsCurrent() {173		panic("hlmailbox: that realm value is not live; pass your own cur")174	}175	return cur.Previous().Address()176}177178func u32(n uint32) string { return strconv.FormatUint(uint64(n), 10) }179180func hx(b []byte) string { return hex.EncodeToString(b) }181182func keysHex(ks []Key) string {183	s := make([]string, len(ks))184	for i, k := range ks {185		s[i] = hx(k[:])186	}187	return strings.Join(s, ",")188}189190// nonceKey sorts nonces by number.191func nonceKey(n uint32) string {192	s := u32(n)193	return strings.Repeat("0", 10-len(s)) + s194}195196func domainKey(d uint32) string { return nonceKey(d) }197198func init() {199	signerKeys = parseKeys(launchSigners)200	signerRule = Rule{Threshold: launchThreshold}201	active.Set(domainKey(launchOrigin), launchVerifier)202	initSeats()203	routes.Set(launchRouteGNOT, &routeRec{})204	routes.Set(launchRouteBUBBLE, &routeRec{})205}206207// ------------------------------------------------------------- reading --208209// LocalDomain is this chain's Hyperlane domain id.210func LocalDomain() uint32 { return localDomain }211212// LaunchOrigin is the Solana domain the launch values name.213func LaunchOrigin() uint32 { return launchOrigin }214215// Address is this realm's address.216func Address() address { return chain.PackageAddress(pkgPath) }217218// Hook is this mailbox's merkle tree hook id in hex: the 32 bytes every checkpoint for a message from here names.219func Hook() string { return hx(hook[:]) }220221// Count is how many messages went out: the next message's nonce.222func Count() uint32 { return tree.Count }223224// Root is the merkle tree's root now, in hex.225func Root() string {226	r := tree.Root()227	return hx(r[:])228}229230// Live is whether the Launch decision has executed: before it the routes refuse sends and credits.231func Live() bool { return live }232233// LaunchedAt is the unix time the Launch decision executed, 0 before: the routes' meters start empty there.234func LaunchedAt() int64 { return launchedAt }235236// Governor is the compiled governor (M1k): the address whose own call decides until it yields; "" when GovDAO237// governs from the first block. Every other bridge realm compiles the same and checks it here at deploy.238func Governor() address { return launchGovernor }239240// Yielded is the block height the governor yielded at (Yield), 0 until then: what every bridge realm reads before241// it accepts a decision — the governor's own call before, GovDAO's proxy after (decisions.DAOGoverns).242func Yielded() int64 { return yielded }243244// Message is the message dispatched with this nonce, in hex, and the tree's root right after it ("", "" if none).245func Message(nonce uint32) (message, root string) {246	v := sent.Get(nonceKey(nonce))247	if v == nil {248		return "", ""249	}250	s := v.(*sentMsg)251	return hx([]byte(s.raw)), hx(s.root[:])252}253254// Delivered is the block height a message (by id, in hex) was delivered at here; 0 if it never was.255func Delivered(id string) int64 {256	v := done.Get(cleanID(id))257	if v == nil {258		return 0259	}260	return v.(int64)261}262263func cleanID(id string) string { return strings.TrimPrefix(strings.ToLower(strings.TrimSpace(id)), "0x") }264265// Signers is the signer set and its rule: copies, so a verifier can read them and nobody can change them.266func Signers() ([]Key, Rule) {267	ks := append([]Key(nil), signerKeys...)268	r := Rule{Threshold: signerRule.Threshold, GroupA: append([]Key(nil), signerRule.GroupA...), GroupB: append([]Key(nil), signerRule.GroupB...)}269	return ks, r270}271272// SignerKeys is the signer set in hex, comma separated, in the order signatures name them.273func SignerKeys() string { return keysHex(signerKeys) }274275// ActiveVerifier is the pkgpath of the verifier GovDAO chose for an origin ("" if none).276func ActiveVerifier(origin uint32) string {277	v := active.Get(domainKey(origin))278	if v == nil {279		return ""280	}281	return v.(string)282}283284// VerifierRegistered is whether a realm at this pkgpath registered as a verifier.285func VerifierRegistered(path string) bool { return verifiers.Has(path) }286287// --------------------------------------------------------------- keys --288289func parseKey(s string) Key {290	p := strings.TrimPrefix(strings.ToLower(strings.TrimSpace(s)), "0x")291	b, err := hex.DecodeString(p)292	if err != nil || len(b) != 32 {293		panic("hlmailbox: not a 32-byte ed25519 key in hex: " + p)294	}295	var k Key296	copy(k[:], b)297	return k298}299300// parseKeys reads comma-separated keys in hex, refusing a key named twice.301func parseKeys(s string) []Key {302	if strings.TrimSpace(s) == "" {303		return nil304	}305	parts := strings.Split(s, ",")306	if len(parts) > maxSigners {307		panic("hlmailbox: more than 255 keys")308	}309	ks := make([]Key, 0, len(parts))310	for _, p := range parts {311		k := parseKey(p)312		if indexOf(ks, k) >= 0 {313			panic("hlmailbox: a key named twice: " + hx(k[:]))314		}315		ks = append(ks, k)316	}317	return ks318}319320func indexOf(ks []Key, k Key) int {321	for i, x := range ks {322		if x == k {323			return i324		}325	}326	return -1327}328329// sameKeys is whether two lists hold the same keys in the same order.330func sameKeys(a, b []Key) bool {331	if len(a) != len(b) {332		return false333	}334	for i := range a {335		if a[i] != b[i] {336			return false337		}338	}339	return true340}341342// subset is whether every key of a is in b.343func subset(a, b []Key) bool {344	for _, k := range a {345		if indexOf(b, k) < 0 {346			return false347		}348	}349	return true350}351352// sameSet is whether two lists hold the same keys, in any order (a list never names a key twice).353func sameSet(a, b []Key) bool { return len(a) == len(b) && subset(a, b) && subset(b, a) }354355// ----------------------------------------------------------- verifiers --356357// RegisterVerifier is how a verifier realm offers itself: called once from that realm (its init, usually), it is358// kept under the caller's pkgpath, which GovDAO names to activate it. Only an /r/ realm may register, and once;359// a sub-realm identity (`cur.Sub(…)`, a token a realm mints for free, whose pkgpath `host#subpath` passes the360// prefix test) is refused, so every entry costs a package deployment and the listing (bounded; render.gno)361// cannot be flooded. Nothing is ever unregistered.362func RegisterVerifier(cur realm, v Verifier) {363	if !cur.IsCurrent() {364		panic("hlmailbox: that realm value is not live; pass your own cur")365	}366	path := cur.Previous().PkgPath()367	if !strings.HasPrefix(path, "gno.land/r/") {368		panic("hlmailbox: only a realm under gno.land/r/ registers a verifier, not " + path)369	}370	if cur.Previous().Subpath() != "" {371		panic("hlmailbox: a realm registers with its own cur, not a sub-identity (" + path + ")")372	}373	if v == nil {374		panic("hlmailbox: a nil verifier")375	}376	if verifiers.Has(path) {377		panic("hlmailbox: " + path + " registered already")378	}379	verifiers.Set(path, v)380	chain.Emit("VerifierRegistered", "pkgpath", path)381}382383// satisfiable asks every active verifier whether the signer set ks can still meet the rule; an active verifier384// that is not registered answers no. Each verifier is handed its own copy of ks: the builders store ks after385// asking, and a verifier that runs under this realm's authority (the no-anchor case, see Verifier) must find386// nothing of the mailbox's to write into.387func satisfiable(ks []Key) bool {388	ok := true389	active.Iterate("", "", func(_ string, v any) bool {390		path := v.(string)391		r := verifiers.Get(path)392		if r == nil || !r.(Verifier).Satisfiable(append([]Key(nil), ks...)) {393			ok = false394			return true395		}396		return false397	})398	return ok399}400401// ---------------------------------------------------------------- out --402403// Dispatch sends body to recipient on destination, from whoever calls it — a realm, usually — and returns the404// message's id. The sender is the caller's address as Hyperlane carries one; the nonce is the message's index in405// the merkle tree. The event is §13's: id, nonce, origin, destination, sender, recipient, hash.406func Dispatch(cur realm, destination uint32, recipient [32]byte, body []byte) [32]byte {407	sender := mustBytes32(caller(cur))408	// a successor a re-point dropped is a route no more (R35): Solana's token may still name it the router until409	// the next kind 6, so a message from it would mint against a lock no realm of the line holds410	if path := cur.Previous().PkgPath(); path != "" {411		if by := Dropped(path); by != "" {412			panic("hlmailbox: " + path + " is a route no more (its predecessor " + by + " re-pointed the migration to another successor): it sends nothing")413		}414	}415	m := hl.Message{416		Version:     hl.Version,417		Nonce:       tree.Count,418		Origin:      localDomain,419		Sender:      sender,420		Destination: destination,421		Recipient:   recipient,422		Body:        body,423	}424	raw := m.Bytes()425	id := hl.ID(raw)426	tree.Insert(id)427	root := tree.Root()428	sent.Set(nonceKey(m.Nonce), &sentMsg{raw: string(raw), root: root, height: runtime.ChainHeight()})429	emitDispatch(m, raw, id)430	return id431}432433func emitDispatch(m hl.Message, raw []byte, id [32]byte) {434	h := sha256.Sum256(raw)435	chain.Emit("Dispatch",436		"id", hx(id[:]),437		"nonce", u32(m.Nonce),438		"origin", u32(m.Origin),439		"destination", u32(m.Destination),440		"sender", hx(m.Sender[:]),441		"recipient", hx(m.Recipient[:]),442		"hash", hx(h[:]),443	)444}445446// Reemit emits the Dispatch event of a message dispatched earlier again, in this block, by anyone: a message447// dispatched before a validator-set change, or whose results leaf is bigger than the ISM accepts, is then delivered448// from a fresh header. The id is unchanged, so the other side's processed-message record still refuses a second449// delivery.450func Reemit(cur realm, nonce uint32) {451	caller(cur)452	v := sent.Get(nonceKey(nonce))453	if v == nil {454		panic("hlmailbox: no message with nonce " + u32(nonce))455	}456	raw := []byte(v.(*sentMsg).raw)457	m, err := hl.ParseMessage(raw)458	if err != nil {459		panic(err.Error())460	}461	emitDispatch(m, raw, hl.ID(raw))462}463464// ----------------------------------------------------------------- in --465466// Process takes a message from another chain for the caller, who must be its recipient — or a route that467// succeeds the recipient along the chain of migrations (AQ1: a burn addressed to a migrated route is the468// successor's to credit, once its last page is in; the route decides when), a successor a re-point dropped from469// that chain counted as a hop of its predecessor's (R35: the line's last realm takes what is addressed to it; the470// dropped realm itself, a route no more, is refused). metadata is whatever the origin's active verifier needs471// (the signers' checkpoint and signatures, for the ed25519 one). The message must be for this chain and never472// delivered; it is marked delivered, then the verifier is asked, and a verifier's error is a panic, so the whole473// transaction reverts with the mark and the message stays deliverable (§5.1). It is then handed back for the474// recipient to act on.475func Process(cur realm, metadata, message []byte) (origin uint32, sender [32]byte, body []byte) {476	who := caller(cur)477	callerPath := cur.Previous().PkgPath()478	if by := Dropped(callerPath); by != "" {479		panic("hlmailbox: " + callerPath + " is a route no more (its predecessor " + by + " re-pointed the migration to another successor): the line's last realm takes this message")480	}481	m, err := hl.ParseMessage(message)482	if err != nil {483		panic(err.Error())484	}485	if m.Version != hl.Version {486		panic("hlmailbox: message version " + strconv.Itoa(int(m.Version)) + ", not " + strconv.Itoa(hl.Version))487	}488	if m.Destination != localDomain {489		panic("hlmailbox: the message is for domain " + u32(m.Destination) + ", not this one (" + u32(localDomain) + ")")490	}491	if mustBytes32(who) != m.Recipient && !successorOf(callerPath, m.Recipient) {492		panic("hlmailbox: only the message's recipient, or a successor of it, can take it")493	}494	idb := hl.ID(message)495	id := hx(idb[:])496	if done.Has(id) {497		panic("hlmailbox: already delivered")498	}499	path := active.Get(domainKey(m.Origin))500	if path == nil {501		panic("hlmailbox: no verifier for domain " + u32(m.Origin))502	}503	v := verifiers.Get(path.(string))504	if v == nil {505		panic("hlmailbox: the active verifier " + path.(string) + " is not registered")506	}507	done.Set(id, runtime.ChainHeight())508	if err := v.(Verifier).Verify(m.Origin, metadata, message); err != nil {509		panic(err.Error())510	}511	chain.Emit("Process",512		"origin", u32(m.Origin),513		"nonce", u32(m.Nonce),514		"id", id,515		"sender", hx(m.Sender[:]),516		"recipient", hx(m.Recipient[:]),517	)518	return m.Origin, m.Sender, m.Body519}520521// MarkDone marks a message id delivered without a message: a route's credit-by-vote (§5.3) does it, so the id522// can never be credited twice. Only a registered route may call it, and only for an id not done.523func MarkDone(cur realm, id string) {524	mustBeRoute(cur)525	id = cleanID(id)526	if b, err := hex.DecodeString(id); err != nil || len(b) != 32 {527		panic("hlmailbox: not a 32-byte message id in hex: " + id)528	}529	if done.Has(id) {530		panic("hlmailbox: already delivered")531	}532	done.Set(id, runtime.ChainHeight())533}534