ucs03_zkgm source realm

1const (
2	SelectorUpdateImpl           manager.Selector = "update_impl"
3	SelectorSetBucketConfig      manager.Selector = "set_bucket_config"
4	SelectorSetRateLimitDisabled manager.Selector = "set_rate_limit_disabled"
5	SelectorPausable             manager.Selector = "pausable"
6)

source

 1const (
 2	ErrSpoofedRealm              = "rlm does not match the current crossing frame"
 3	ErrNotProxyRealm             = "rlm is not proxy realm"
 4	ErrNotCoreRealm              = "rlm is not core realm"
 5	ErrInvalidSaltLength         = "invalid salt length"
 6	ErrTokenBucketNotFound       = "token bucket not found"
 7	ErrChannelBalanceV2NotFound  = "channel balance v2 not found"
 8	ErrLockedTokenAmountOverflow = "locked token amount overflows uint256"
 9	ErrInterfaceConversion       = "interface conversion failed"
10)

source

ErrSpoofedRealm guards non-crossing (_ int, rlm realm, ...) entrypoints: the passed rlm must be the current crossing frame, not a forged or stale token replayed by a caller.

 1const (
 2	ZkgmImplUpdatedEvent               = "ZkgmImplUpdated"
 3	ZkgmPausedEvent                    = "ZkgmPaused"
 4	ZkgmUnpausedEvent                  = "ZkgmUnpaused"
 5	ZkgmRateLimitBucketConfiguredEvent = "ZkgmRateLimitBucketConfigured"
 6	ZkgmRateLimitDisabledSetEvent      = "ZkgmRateLimitDisabledSet"
 7	ZkgmReceiverRegisteredEvent        = "ZkgmReceiverRegistered"
 8	ZkgmNativeReleasedEvent            = "ZkgmNativeReleased"
 9	ZkgmForwardInFlightSetEvent        = "ZkgmForwardInFlightSet"
10	ZkgmForwardInFlightPoppedEvent     = "ZkgmForwardInFlightPopped"
11	ZkgmRecvErrorEvent                 = "ZkgmRecvError"
12)

source

1const Version = z.PROTOCOL_VERSION

source

1func EmitForwardInFlightPopped(_ int, rlm realm, packetHash types.H256, found bool)

source

1func EmitForwardInFlightSet(_ int, rlm realm, packetHash types.H256, parentPacketHash types.H256)

source

1func EmitNativeReleased(_ int, rlm realm, denom string, recipient address, amount int64)

source

1func EmitRecvError(_ int, rlm realm, sourceChannel types.ChannelId, destinationChannel types.ChannelId, reason string)

source

1func GetChannelBalanceV2(channelId types.ChannelId, path *u256.Uint, baseToken string, quoteToken []byte) (*u256.Uint, error)

source

GetChannelBalanceV2 returns the escrow balance for the v2 channel-balance key.

1func GetLockedTokenAmount(denom string) (*u256.Uint, error)

source

GetLockedTokenAmount returns the total terminally locked base-token amount for denom.

1func GetTokenBucket(denom string) (*tb.TokenBucket, error)

source

GetTokenBucket returns a snapshot of the rate-limit bucket configured for denom.

1func GetVoucherSize() (int, error)

source

GetVoucherSize returns the total number of registered vouchers, i.e. the key count callers need to drive GetVoucherList's offset/count pagination.

1func Pausable(cur realm, p bool)

source

Pausable toggles the global pause gate checked by every App receiver.

1func ProxyPkgPath() string

source

1func RegisterCoreApp(cur realm)

source

RegisterCoreApp registers the proxy App with core under the proxy pkgpath. core rejects re-registration, so the App identity is permanent once installed.

1func RegisterImpl(cur realm, constructor func(store IStore) IApp)

source

RegisterImpl records an impl constructor under the calling realm's package path. It is called from the impl realm's init, so the path is permanent once installed: re-registration is rejected. The caller must be a sub-realm of this proxy (its path must be prefixed by the proxy path), matching core's host registration rule.

1func RegisterReceiver(cur realm, receiver z.Zkgmable)

source

RegisterReceiver records the calling realm as an OP_CALL receiver target, keyed by its package path. The impl looks it up via store.GetReceiver during call dispatch.

1func Send(cur realm, channelId types.ChannelId, timeoutTimestamp types.Timestamp, salt [32]byte, instruction z.Instruction) types.Packet

source

1func SendRaw(cur realm, channelId uint32, timeoutTimestamp uint64, saltHex string, version uint8, opcode uint8, operandHex string) types.Packet

source

SendRaw sends a ZKGM packet from hex-encoded instruction fields. Use this entry point from gnokey maketx call (not maketx run) so OriginSend captures any native coins attached with -send for escrow-bearing instructions.

channelId: local source IBC channel id on this chain.
timeoutTimestamp: packet expiry in nanoseconds since the Unix epoch.
saltHex: 32-byte send salt as hex; an optional 0x prefix is accepted.
version: instruction version byte (e.g. 2 for TokenOrderV2).
opcode: instruction opcode (0=Forward, 1=Call, 2=Batch, 3=TokenOrder).
operandHex: ABI-encoded instruction operand as hex; 0x prefix optional.

1func SetBucketConfig(cur realm, denom string, capacity *u256.Uint, refillRate *u256.Uint)

source

SetBucketConfig creates or updates the per-denom send-side rate-limit bucket. The bucket is anchored to block time, so RefillRate is tokens per second.

1func SetRateLimitDisabled(cur realm, disabled bool)

source

SetRateLimitDisabled toggles the global rate-limit kill switch.

1func UpdateImpl(cur realm, path string)

source

UpdateImpl installs or re-points the implementation following the bootstrap and steady-state tiers of the trust model. It is admin-gated and injects the proxy-owned store into the registered constructor for path.

1func VoucherApprove(cur realm, ibcDenom string, spender address, amount int64)

source

VoucherApprove lets the caller grant spender an allowance on their own wrapped-voucher balance for ibcDenom, so the voucher can be used through GRC20-composable flows (e.g. Gnoswap) that rely on TransferFrom.

1func VoucherBalanceOf(ibcDenom string, addr address) int64

source

VoucherBalanceOf returns addr's wrapped-voucher balance for ibcDenom, or 0 if none. It reads the proxy-owned Store, so the balance survives impl upgrades and does not depend on grc20reg's key.

1func VoucherTransfer(cur realm, ibcDenom string, to address, amount int64)

source

VoucherTransfer lets the caller move their own wrapped-voucher balance for ibcDenom directly to another address.

1func NewStore() *Store

source

1func NewVoucher(token *grc20.Token, ledger *grc20.PrivateLedger, originDecimals uint8) *Voucher

source

NewVoucher is a crossing-safe constructor, so the impl realm can build one without tripping the foreign-composite-literal rule. originDecimals is the origin token's precision; the ledger token is created at min(originDecimals, ledger cap).

1func GetVoucherInfo(ibcDenom string) (VoucherInfo, error)

source

GetVoucherInfo returns a snapshot of the single wrapped voucher registered for ibcDenom.

1func GetVoucherList(offset, count int) ([]VoucherInfo, error)

source

GetVoucherList returns a page of up to count wrapped voucher tokens starting at offset, ordered by denom.

1func NewVoucherInfo(denom, name, symbol string, originDecimals, ledgerDecimals uint8, totalSupply int64) VoucherInfo

source

NewVoucherInfo is a crossing-safe constructor, so the impl realm (and test doubles) can build one without tripping the foreign-composite-literal rule.

1type App struct{}

source

app.gno is the App receiver surface: the core-driven half of the proxy. core holds this App reference permanently (its port is keyed by the proxy pkgpath and re-registration is rejected), so App is the stable IBC identity and must never carry business logic. Every receiver gates on assertIsCoreRealm and assertIsNotPaused before delegating to the installed impl or rejecting channel close. Logic lives in the impl realm; authority and funds live in the proxy. See assert.gno for the gates and upgrade.gno for the swap point.

1func (a *App) OnAcknowledgementPacket(cur realm, packet types.Packet, acknowledgement []byte, relayer address)

source

1func (a *App) OnChannelCloseConfirm(cur realm, channelId types.ChannelId, relayer address)

source

1func (a *App) OnChannelCloseInit(cur realm, channelId types.ChannelId, relayer address)

source

1func (a *App) OnChannelOpenAck(cur realm, channelId types.ChannelId, counterpartyChannelId types.ChannelId, counterpartyVersion string, relayer address)

source

1func (a *App) OnChannelOpenConfirm(cur realm, channelId types.ChannelId, relayer address)

source

1func (a *App) OnChannelOpenInit(cur realm, connectionId types.ConnectionId, channelId types.ChannelId, version string, relayer address)

source

1func (a *App) OnChannelOpenTry(cur realm, connectionId types.ConnectionId, channelId types.ChannelId, version string, counterpartyVersion string, relayer address)

source

1func (a *App) OnIntentRecvPacket(cur realm, packet types.Packet, marketMaker address, marketMakerMsg []byte) types.RecvPacketResult

source

1func (a *App) OnRecvPacket(cur realm, packet types.Packet, relayer address, relayerMsg []byte) types.RecvPacketResult

source

1func (a *App) OnTimeoutPacket(cur realm, packet types.Packet, relayer address)

source

 1type IApp interface {
 2	// IApp
 3	OnChannelOpenInit(_ int, rlm realm, connectionId types.ConnectionId, channelId types.ChannelId, version string, relayer address)
 4	OnChannelOpenTry(_ int, rlm realm, connectionId types.ConnectionId, channelId types.ChannelId, version string, counterpartyVersion string, relayer address)
 5	OnChannelOpenAck(_ int, rlm realm, channelId types.ChannelId, counterpartyChannelId types.ChannelId, counterpartyVersion string, relayer address)
 6	OnChannelOpenConfirm(_ int, rlm realm, channelId types.ChannelId, relayer address)
 7	OnChannelCloseInit(_ int, rlm realm, channelId types.ChannelId, relayer address)
 8	OnChannelCloseConfirm(_ int, rlm realm, channelId types.ChannelId, relayer address)
 9	OnRecvPacket(_ int, rlm realm, packet types.Packet, relayer address, relayerMsg []byte) types.RecvPacketResult
10	OnAcknowledgementPacket(_ int, rlm realm, packet types.Packet, acknowledgement []byte, relayer address)
11	OnTimeoutPacket(_ int, rlm realm, packet types.Packet, relayer address)
12
13	// IIntentApp
14	IAppIntent
15
16	IAppTransfer
17
18	IAppVoucher
19
20	// Read-only relayer/tooling query surface.
21	IAppGetter
22}

source

1type IAppGetter interface {
2	GetTokenBucket(denom string) (*tb.TokenBucket, error)
3	GetChannelBalanceV2(channelId types.ChannelId, path *u256.Uint, baseToken string, quoteToken []byte) (*u256.Uint, error)
4	GetLockedTokenAmount(denom string) (*u256.Uint, error)
5	GetVoucherList(offset, count int) ([]VoucherInfo, error)
6	GetVoucherSize() (int, error)
7	GetVoucherInfo(ibcDenom string) (VoucherInfo, error)
8}

source

IAppGetter is the read-only query surface implemented by the impl and exposed by the proxy's getters.gno.

1type IAppIntent interface {
2	OnIntentRecvPacket(_ int, rlm realm, packet types.Packet, marketMaker address, marketMakerMsg []byte) types.RecvPacketResult
3}

source

1type IAppTransfer interface {
2	Send(_ int, rlm realm, channelId types.ChannelId, timeoutTimestamp types.Timestamp, salt [32]byte, instruction z.Instruction) types.Packet
3}

source

IAppTransfer is the user-initiated send surface. zkgm is a general instruction protocol (token order / batch / call / forward), so Send takes a raw Instruction rather than a token-transfer shaped argument list.

1type IAppVoucher interface {
2	VoucherApprove(_ int, rlm realm, ibcDenom string, spender address, amount int64) error
3	VoucherTransfer(_ int, rlm realm, ibcDenom string, to address, amount int64) error
4}

source

IAppVoucher is the wrapped-voucher self-service surface: it lets a holder grant an allowance or move their own balance directly, without exposing the mint/burn capability that Store's Voucher.Ledger() carries.

 1type IStore interface {
 2	SetTokenOrigin(_ int, rlm realm, denom string, path *u256.Uint)
 3	GetTokenOrigin(denom string) (*u256.Uint, bool)
 4
 5	SetChannelBalanceV2(_ int, rlm realm, key string, amount *u256.Uint)
 6	RemoveChannelBalanceV2(_ int, rlm realm, key string)
 7	GetChannelBalanceV2(key string) (*u256.Uint, bool)
 8
 9	SetMetadataImageOf(_ int, rlm realm, denom string, image [32]byte)
10	GetMetadataImageOf(denom string) ([32]byte, bool)
11
12	SetForeignToken(_ int, rlm realm, denom string, token []byte)
13	GetForeignToken(denom string) ([]byte, bool)
14
15	SetInFlightPacket(_ int, rlm realm, packetHash string, parent types.Packet)
16	GetInFlightPacket(packetHash string) (types.Packet, bool)
17	RemoveInFlightPacket(_ int, rlm realm, packetHash string)
18
19	SetTokenBucket(_ int, rlm realm, denom string, bucket *tb.TokenBucket)
20	GetTokenBucket(denom string) (*tb.TokenBucket, bool)
21	RemoveTokenBucket(_ int, rlm realm, denom string)
22
23	SetVoucher(_ int, rlm realm, ibcDenom string, v *Voucher)
24	GetVoucher(ibcDenom string) (*Voucher, bool)
25	GetVoucherList(offset, count int) []VoucherInfo
26	GetVoucherSize() int
27	HasVoucher(ibcDenom string) bool
28
29	// AddLockedTokenAmount/GetLockedTokenAmount are managed alongside the
30	// voucher methods above: both cover non-escrow custody of a base token
31	// (native or grc20) that zkgm cannot supply-burn the way it burns vouchers.
32	AddLockedTokenAmount(_ int, rlm realm, denom string, amount *u256.Uint)
33	GetLockedTokenAmount(denom string) (*u256.Uint, bool)
34
35	SetReceiver(_ int, rlm realm, path string, receiver z.Zkgmable)
36	GetReceiver(path string) (z.Zkgmable, bool)
37
38	SetRateLimitDisabled(_ int, rlm realm, disabled bool)
39	RateLimitDisabled() bool
40}

source

 1type Store struct {
 2	tokenOrigin        *bptree.BPTree // denom -> *u256.Uint  (mint path)
 3	channelBalanceV2   *bptree.BPTree // key   -> *u256.Uint  (escrow balance)
 4	metadataImageOf    *bptree.BPTree // denom -> [32]byte
 5	hashToForeignToken *bptree.BPTree // denom -> []byte
 6	inFlightPacket     *bptree.BPTree // packetHash -> types.Packet (parent)
 7	tokenBucket        *bptree.BPTree // denom -> *tb.TokenBucket
 8	vouchers           *bptree.BPTree // ibcDenom -> *Voucher
 9	// lockedTokenAmounts is managed alongside vouchers: both track non-escrow
10	// custody of a base token (native or grc20) that zkgm cannot supply-burn,
11	// as opposed to vouchers, which zkgm mints/burns directly.
12	lockedTokenAmounts *bptree.BPTree // denom -> *u256.Uint (permanently locked base token)
13	receivers          *bptree.BPTree // pkgPath -> z.Zkgmable
14	rateLimitDisabled  bool
15}

source

1func (s *Store) AddLockedTokenAmount(_ int, rlm realm, denom string, amount *u256.Uint)

source

AddLockedTokenAmount tracks base-token escrow locked after burn-address settlement (native or a registered grc20; a voucher is supply-burned instead via burnVoucher). Locked base remains in proxy escrow but is excluded from channel balances. Invariant: proxy balance == sum(channelBalanceV2) + sum(lockedTokenAmounts).

1func (s *Store) GetChannelBalanceV2(key string) (*u256.Uint, bool)

source

GetChannelBalanceV2 returns the escrow balance for a key.

1func (s *Store) GetForeignToken(denom string) ([]byte, bool)

source

GetForeignToken returns the origin token bytes for a wrapped denom.

1func (s *Store) GetInFlightPacket(packetHash string) (types.Packet, bool)

source

GetInFlightPacket returns the parent packet for a forwarded-child hash.

1func (s *Store) GetLockedTokenAmount(denom string) (*u256.Uint, bool)

source

GetLockedTokenAmount returns the total base-token amount permanently locked for a denom.

1func (s *Store) GetMetadataImageOf(denom string) ([32]byte, bool)

source

GetMetadataImageOf returns a wrapped denom's metadata image.

1func (s *Store) GetReceiver(path string) (z.Zkgmable, bool)

source

GetReceiver returns the callback target registered at a package path.

1func (s *Store) GetTokenBucket(denom string) (*tb.TokenBucket, bool)

source

GetTokenBucket returns the rate-limit bucket for a denom.

1func (s *Store) GetTokenOrigin(denom string) (*u256.Uint, bool)

source

GetTokenOrigin returns the recorded mint path for a denom.

1func (s *Store) GetVoucher(ibcDenom string) (*Voucher, bool)

source

GetVoucher returns the wrapped voucher for an ibc denom.

1func (s *Store) GetVoucherList(offset, count int) []VoucherInfo

source

GetVoucherList returns a page of up to count vouchers starting at offset, ordered by denom. The vouchers tree only grows (there is no voucher deletion), so pagination keeps a single call's gas/response size bounded regardless of how many wrapped tokens have been registered over time.

1func (s *Store) GetVoucherSize() int

source

GetVoucherSize returns the total number of registered vouchers, i.e. the key count callers need to drive GetVoucherList's offset/count pagination.

1func (s *Store) HasVoucher(ibcDenom string) bool

source

HasVoucher reports whether a voucher exists for an ibc denom.

1func (s *Store) RateLimitDisabled() bool

source

RateLimitDisabled reports whether rate limiting is globally disabled.

1func (s *Store) RemoveChannelBalanceV2(_ int, rlm realm, key string)

source

RemoveChannelBalanceV2 clears a drained channel-balance entry.

1func (s *Store) RemoveInFlightPacket(_ int, rlm realm, packetHash string)

source

RemoveInFlightPacket clears a resolved forwarded-child entry.

1func (s *Store) RemoveTokenBucket(_ int, rlm realm, denom string)

source

RemoveTokenBucket clears a denom's rate-limit bucket.

1func (s *Store) SetChannelBalanceV2(_ int, rlm realm, key string, amount *u256.Uint)

source

SetChannelBalanceV2 stores the escrow balance for a channel-balance key.

1func (s *Store) SetForeignToken(_ int, rlm realm, denom string, token []byte)

source

SetForeignToken records the origin token bytes for a wrapped denom.

1func (s *Store) SetInFlightPacket(_ int, rlm realm, packetHash string, parent types.Packet)

source

SetInFlightPacket records the parent packet awaiting a forwarded child.

1func (s *Store) SetMetadataImageOf(_ int, rlm realm, denom string, image [32]byte)

source

SetMetadataImageOf records a wrapped denom's metadata image.

1func (s *Store) SetRateLimitDisabled(_ int, rlm realm, disabled bool)

source

SetRateLimitDisabled toggles the global rate-limit kill switch.

1func (s *Store) SetReceiver(_ int, rlm realm, path string, receiver z.Zkgmable)

source

SetReceiver registers a Zkgmable callback target at a package path.

1func (s *Store) SetTokenBucket(_ int, rlm realm, denom string, bucket *tb.TokenBucket)

source

SetTokenBucket stores the rate-limit bucket for a denom.

1func (s *Store) SetTokenOrigin(_ int, rlm realm, denom string, path *u256.Uint)

source

SetTokenOrigin records the mint path for a wrapped denom.

1func (s *Store) SetVoucher(_ int, rlm realm, ibcDenom string, v *Voucher)

source

SetVoucher stores the wrapped voucher for an ibc denom.

1type Voucher struct {
2	token          *grc20.Token
3	ledger         *grc20.PrivateLedger
4	originDecimals uint8
5}

source

Voucher bundles a wrapped grc20 token, its private mint/burn ledger, and the origin token's decimal precision. It is proxy-owned state held in the Store, so its mint/burn rights survive impl upgrades.

Packet amounts are in the origin token's decimals; the grc20 ledger holds them downscaled to the (possibly capped) ledger decimals, so they fit int64. MintScaled / BurnScaled / TransferScaled apply that downscale, so callers never combine the scale and the ledger by hand; the raw int64 ops stay reachable via Ledger().

SECURITY: those methods and Ledger() all hand out the mint/burn capability, so a *Voucher must stay impl-gated. The Store is injected and never publicly returned, so untrusted realms can only read balances via VoucherBalanceOf.

1func (v *Voucher) Approve(_ int, rlm realm, spender address, amount int64) error

source

Approve grants spender an allowance on holder's ledger-precision balance. Unlike MintScaled/BurnScaled/TransferScaled, the amount is not scaled from origin precision: it is a self-service action on the holder's own balance, matching the ledger units VoucherBalanceOf already reads. Carries the ledger's Approve capability; callers MUST be impl-gated.

1func (v *Voucher) BurnScaled(holder address, amount *u256.Uint) error

source

BurnScaled debits an origin-precision amount, downscaled to the ledger. Carries the burn capability; callers MUST be impl-gated.

1func (v *Voucher) Ledger() *grc20.PrivateLedger

source

Ledger returns the mint/burn capability. Callers MUST be impl-gated.

1func (v *Voucher) MintScaled(receiver address, amount *u256.Uint) error

source

MintScaled credits an origin-precision amount, downscaled to the ledger. Carries the mint capability; callers MUST be impl-gated.

1func (v *Voucher) OriginDecimals() uint8

source

OriginDecimals returns the origin token's precision. The scalar is copied across the realm boundary, so impl reads are safe.

1func (v *Voucher) ScaleExp() int

source

ScaleExp is the origin->ledger downscale exponent: the low-order digits dropped between origin precision and the ledger token's precision. Derived from both stored decimals, so it needs no global constant, and clamps to 0 for native/low-decimal tokens.

1func (v *Voucher) ToLedgerAmount(amount *u256.Uint) (int64, error)

source

ToLedgerAmount narrows an origin-precision amount to this voucher's int64 ledger amount, rejecting sub-precision dust and int64 overflow. MintScaled, BurnScaled, TransferScaled and the impl's pre-flight checks all route through it.

1func (v *Voucher) Token() *grc20.Token

source

Token returns the read-only token handle (safe: balances, metadata).

1func (v *Voucher) Transfer(_ int, rlm realm, to address, amount int64) error

source

Transfer moves amount of holder's ledger-precision balance to another address. Same scale as Approve: no origin-precision scaling. Carries the ledger's Transfer capability; callers MUST be impl-gated.

1func (v *Voucher) TransferScaled(from, to address, amount *u256.Uint) error

source

TransferScaled moves an origin-precision amount between holders, downscaled to the ledger. Carries the ledger capability; callers MUST be impl-gated.

1type VoucherInfo struct {
2	Denom          string
3	Name           string
4	Symbol         string
5	OriginDecimals uint8
6	LedgerDecimals uint8
7	TotalSupply    int64
8}

source

VoucherInfo is a read-only snapshot of a wrapped voucher's grc20 identity for the voucher-list getter. It carries only scalar fields copied out of Voucher/Token — no token/ledger handles — so listing vouchers never hands out the mint/burn capability that *Voucher.Ledger() exposes.

chain stdlib
encoding/hex stdlib
gno.land/p/demo/tokens/grc20 package
gno.land/p/nt/bptree/v0 package
gno.land/p/onbloc/access/manager package
gno.land/p/onbloc/ibc/union/app package
gno.land/p/onbloc/ibc/union/types package
gno.land/p/onbloc/ibc/union/zkgm package
gno.land/p/onbloc/ibc/union/zkgm/tokenbucket package
gno.land/p/onbloc/math/uint256 package
gno.land/r/onbloc/ibc/union/access realm
gno.land/r/onbloc/ibc/union/core realm
strconv stdlib
strings stdlib
time stdlib

Constants 4

Functions 26

Types 10

Methods on App

Methods on Store

Methods on Voucher

Imports 15

Source Files 15