zkgm source pure

 1const (
 2	INSTR_VERSION_0 uint8 = 0x00
 3	INSTR_VERSION_1 uint8 = 0x01
 4	INSTR_VERSION_2 uint8 = 0x02
 5
 6	OP_FORWARD     uint8 = 0x00
 7	OP_CALL        uint8 = 0x01
 8	OP_BATCH       uint8 = 0x02
 9	OP_TOKEN_ORDER uint8 = 0x03
10
11	TOKEN_ORDER_KIND_INITIALIZE uint8 = 0x00
12	TOKEN_ORDER_KIND_ESCROW     uint8 = 0x01
13	TOKEN_ORDER_KIND_UNESCROW   uint8 = 0x02
14	TOKEN_ORDER_KIND_SOLVE      uint8 = 0x03
15
16	PROTOCOL_VERSION = "ucs03-zkgm-0"
17)

source

1const (
2	channelIDMask  = uint64(0xFFFFFFFF)
3	channelSlotBit = uint(32)
4	maxHopIndex    = 7
5	// MaxHops is the largest number of channel hops a path can encode.
6	// Mirrors the maxHopIndex+1 invariant enforced by UpdateChannelPath.
7	MaxHops = maxHopIndex + 1
8)

source

1const BURN_ADDRESS = "g1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqluuxe"

source

BURN_ADDRESS is the canonical zero burn address: bech32 of 20 zero bytes with the gno `g` HRP, matching union's get_burn_address = addr_humanize([0;20]). A market-maker ack naming this address burns the escrow instead of releasing it.

reference: https://github.com/unionlabs/union/blob/d91c5e94354e15801bd5f82dc658eae3b79f2dad/cosmwasm/app/ucs03-zkgm/src/contract.rs#L3211

 1var (
 2	ACK_ERR_ONLY_MAKER = []byte{0xDE, 0xAD, 0xC0, 0xDE}
 3
 4	TAG_ACK_FAILURE = [32]byte{}
 5	TAG_ACK_SUCCESS = [32]byte{
 6		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 7		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 8		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 9		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
10	}
11
12	FILL_TYPE_PROTOCOL = [32]byte{
13		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
14		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
15		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
16		0x00, 0x00, 0x00, 0x00, 0x00, 0xB0, 0xCA, 0xD0,
17	}
18	FILL_TYPE_MARKETMAKER = [32]byte{
19		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
20		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
21		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
22		0x00, 0x00, 0x00, 0x00, 0xD1, 0xCE, 0xC4, 0x5E,
23	}
24
25	FORWARD_SALT_MAGIC = [32]byte{
26		0xC0, 0xDE, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
27		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
28		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
29		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xBA, 0xBE,
30	}
31)

source

1var AckSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint256},
3	{Type: abi.TypeBytes},
4}}

source

1var BatchAckSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeArray, Elem: &abi.Field{Type: abi.TypeBytes}},
3}}

source

1var BatchSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeArray, Elem: &abi.Field{Type: abi.TypeStruct, Sub: &InstructionSchema}},
3}}

source

1var CallSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeBytes},
3	{Type: abi.TypeBool},
4	{Type: abi.TypeBytes},
5	{Type: abi.TypeBytes},
6}}

source

1var ErrAmountNotDivisible = errors.New("zkgm: amount not divisible by token scale factor")

source

ErrAmountNotDivisible is returned when a source-precision amount carries precision below the ledger's canonical scale, so dividing by the token's scale factor leaves a remainder. It is rejected so cross-chain value is conserved exactly.

1var ErrAmountOverflow = errors.New("zkgm: amount overflows int64")

source

ErrAmountOverflow is returned when a (downscaled) amount does not fit int64, the width of the grc20/banker ledger.

1var ErrChannelPathFull = errors.New("zkgm: channel path is full")

source

ErrChannelPathFull is returned by UpdateChannelPath when the path can no longer hold another hop.

1var ForwardSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint256},
3	{Type: abi.TypeUint64},
4	{Type: abi.TypeUint64},
5	{Type: abi.TypeStruct, Sub: &InstructionSchema},
6}}

source

1var InstructionSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint8},
3	{Type: abi.TypeUint8},
4	{Type: abi.TypeBytes},
5}}

source

1var PredictV2Schema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint256},
3	{Type: abi.TypeUint32},
4	{Type: abi.TypeBytes},
5	{Type: abi.TypeUint256},
6}}

source

PredictV2Schema mirrors abi.encode(path, channel, token, metadataImage) used by Union's _predictWrappedTokenFromMetadataImageV2 helper.

1var PredictWrappedTokenSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint256},
3	{Type: abi.TypeUint32},
4	{Type: abi.TypeBytes},
5}}

source

PredictWrappedTokenSchema mirrors abi.encode(path, channel, token) used by Union's _predictWrappedToken helper.

1var SolverMetadataSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeBytes},
3	{Type: abi.TypeBytes},
4}}

source

1var TokenInitializerSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeAddress},
3	{Type: abi.TypeAddress},
4	{Type: abi.TypeString},
5	{Type: abi.TypeString},
6	{Type: abi.TypeUint8},
7}}

source

TokenInitializerSchema mirrors the Solidity ABI params for ZkgmERC20's initialize(address authority, address minter, string name, string symbol, uint8 decimals), excluding the 4-byte selector. It is not a Union ZKGM top-level struct in com.rs or Types.sol.

1var TokenMetadataSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeBytes},
3	{Type: abi.TypeBytes},
4}}

source

1var TokenOrderAckSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeUint256},
3	{Type: abi.TypeBytes},
4}}

source

 1var TokenOrderV1Schema = abi.Schema{Fields: []abi.Field{
 2	{Type: abi.TypeBytes},
 3	{Type: abi.TypeBytes},
 4	{Type: abi.TypeBytes},
 5	{Type: abi.TypeUint256},
 6	{Type: abi.TypeString},
 7	{Type: abi.TypeString},
 8	{Type: abi.TypeUint8},
 9	{Type: abi.TypeUint256},
10	{Type: abi.TypeBytes},
11	{Type: abi.TypeUint256},
12}}

source

 1var TokenOrderV2Schema = abi.Schema{Fields: []abi.Field{
 2	{Type: abi.TypeBytes},
 3	{Type: abi.TypeBytes},
 4	{Type: abi.TypeBytes},
 5	{Type: abi.TypeUint256},
 6	{Type: abi.TypeBytes},
 7	{Type: abi.TypeUint256},
 8	{Type: abi.TypeUint8},
 9	{Type: abi.TypeBytes},
10}}

source

1var ZkgmPacketSchema = abi.Schema{Fields: []abi.Field{
2	{Type: abi.TypeBytes32},
3	{Type: abi.TypeUint256},
4	{Type: abi.TypeStruct, Sub: &InstructionSchema},
5}}

source

1func DequeueChannelFromPath(path *u256.Uint) (*u256.Uint, uint32)

source

DequeueChannelFromPath pops the lowest 32-bit channel slot off the path and shifts the remainder right. Returns the truncated path and the popped channel ID. A channel ID of 0 means the path was empty.

Based on Union's `dequeue_channel_from_path` path helper.

1func DeriveBatchSalt(index *u256.Uint, salt [32]byte) [32]byte

source

1func DeriveForwardSalt(salt [32]byte) [32]byte

source

1func DeriveSenderSalt(sender []byte, salt [32]byte) [32]byte

source

DeriveSenderSalt computes:

Example

1keccak256((sender, salt).abi_encode())

matching Union's alloy-sol-types encoding of a top-level dynamic tuple. Callers must pass the raw UTF-8 bytes of the bech32 account string.

1func EncodeAck(a Ack) ([]byte, error)

source

1func EncodeBatch(b Batch) ([]byte, error)

source

1func EncodeBatchAck(a BatchAck) ([]byte, error)

source

1func EncodeCall(c Call) ([]byte, error)

source

1func EncodeForward(f Forward) ([]byte, error)

source

1func EncodeInstruction(ins Instruction) ([]byte, error)

source

1func EncodeSolverMetadata(m SolverMetadata) ([]byte, error)

source

1func EncodeTokenInitializer(i TokenInitializer) ([]byte, error)

source

EncodeTokenInitializer encodes the ZkgmERC20 initialize(...) calldata carried in TokenMetadata.Initializer. i.Authority/i.Minter default to the zero address when nil; callers that need a real EVM authority/minter (production sends targeting a real chain) set them explicitly.

1func EncodeTokenMetadata(m TokenMetadata) ([]byte, error)

source

1func EncodeTokenOrderAck(a TokenOrderAck) ([]byte, error)

source

1func EncodeTokenOrderV1(o TokenOrderV1) ([]byte, error)

source

1func EncodeTokenOrderV2(o TokenOrderV2) ([]byte, error)

source

1func EncodeZkgmPacket(p ZkgmPacket) ([]byte, error)

source

1func GetChannelFromPath(path *u256.Uint, index int) uint32

source

GetChannelFromPath returns the channel ID stored at the given 32-bit slot (0-indexed from the LSB). Returns 0 if the slot is empty or out of range.

Based on Union's `get_channel_from_path` path helper.

1func HopCount(path *u256.Uint) int

source

HopCount returns the number of 32-bit channel slots occupied by path. A nil or zero path has zero hops.

1func IsForwardedPacket(salt [32]byte) bool

source

1func MakePathFromChannel(channelID uint32, index int) *u256.Uint

source

MakePathFromChannel builds a path containing channelID at the given slot.

Based on Union's `make_path_from_channel` path helper.

1func MetadataImage(meta TokenMetadata) [32]byte

source

MetadataImage returns keccak256(TokenMetadata), the on-chain identity of the metadata used to mint a voucher.

1func PopChannelFromPath(path *u256.Uint) (*u256.Uint, uint32)

source

PopChannelFromPath extracts the highest non-zero 32-bit channel slot from the path, returning the path with that slot cleared and the popped channel ID. A channel ID of 0 means the path was empty.

Based on Union's `pop_channel_from_path` path helper.

1func Pow10(exp int) *u256.Uint

source

Pow10 returns 10^exp as a uint256. exp is small (a token's decimal excess over the canonical precision), so float pow is exact and sufficient.

1func PredictCallProxyAccount(path *u256.Uint, channelId types.ChannelId, sender []byte) string

source

PredictCallProxyAccount returns the synthetic Gno address that represents the given (path, destinationChannel, sender) tuple as a callable account.

key = zkgm1<first-20-bytes-of-keccak(ZKGM_CALL_PROXY || path || channelId || sender)>

1func PredictWrappedToken(path *u256.Uint, channelId uint32, baseToken []byte) string

source

PredictWrappedToken derives the legacy wrapped IBC denom for a v1 token order.

1func PredictWrappedTokenV2(path *u256.Uint, channelId uint32, baseToken []byte, metadataImage [32]byte) string

source

PredictWrappedTokenV2 derives the IBC voucher denom for a v2 token order.

1func ReverseChannelPath(path *u256.Uint) (*u256.Uint, error)

source

ReverseChannelPath returns a path with the same channel hops in reversed order. Empty channel slots are skipped. Returns ErrChannelPathFull when the reversed path would overflow.

Based on Union's `reverse_channel_path` path helper.

1func ScaleDownToInt64(amount *u256.Uint, scaleExp int) (int64, error)

source

ScaleDownToInt64 narrows an origin-precision amount to an int64 ledger amount by dividing by 10^scaleExp. scaleExp <= 0 is the identity narrow, used by native and low-decimal tokens.

1func TintForwardSalt(salt [32]byte) [32]byte

source

1func Uint256FromBytes32(bz [32]byte) *u256.Uint

source

Uint256FromBytes32 converts a big-endian bytes32 value into a uint256.

1func Uint256ToBytes32(x *u256.Uint) [32]byte

source

Uint256ToBytes32 returns the big-endian 32-byte encoding of x.

1func UpdateChannelPath(path *u256.Uint, nextChannelID uint32) (*u256.Uint, error)

source

UpdateChannelPath appends nextChannelID to the path at the next free 32-bit slot. Returns ErrChannelPathFull when the path can no longer hold another hop.

Uses the occupied slot count so full-width 32-bit channel IDs still append to the immediately next slot instead of skipping an aligned bit boundary.

1func DecodeAck(data []byte) (Ack, error)

source

1func DecodeBatch(data []byte) (Batch, error)

source

1func DecodeBatchAck(data []byte) (BatchAck, error)

source

1func DecodeCall(data []byte) (Call, error)

source

1func DecodeForward(data []byte) (Forward, error)

source

1func DecodeInstruction(data []byte) (Instruction, error)

source

1func DecodeSolverMetadata(data []byte) (SolverMetadata, error)

source

1func DecodeTokenInitializer(data []byte) (TokenInitializer, error)

source

DecodeTokenInitializer decodes the ZkgmERC20 initialize(...) calldata carried in TokenMetadata.Initializer, round-tripping every field encoded by EncodeTokenInitializer (including Authority/Minter, which a receiving Gno chain otherwise has no use for beyond display/reconstruction).

1func DecodeTokenMetadata(data []byte) (TokenMetadata, error)

source

1func DecodeTokenOrderAck(data []byte) (TokenOrderAck, error)

source

1func DecodeTokenOrderV1(data []byte) (TokenOrderV1, error)

source

1func DecodeTokenOrderV2(data []byte) (TokenOrderV2, error)

source

1func DecodeZkgmPacket(data []byte) (ZkgmPacket, error)

source

1type Ack struct {
2	Tag      *u256.Uint
3	InnerAck []byte
4}

source

Ack wraps an acknowledgement tag and payload.

Mirrors `Ack` at com.rs:104.

1type Batch struct {
2	Instructions []Instruction
3}

source

Batch groups multiple instructions.

Mirrors `Batch` at com.rs:61.

1type BatchAck struct {
2	Acknowledgements [][]byte
3}

source

BatchAck groups acknowledgement payloads.

Mirrors `BatchAck` at com.rs:109.

1type Call struct {
2	Sender           []byte
3	Eureka           bool
4	ContractAddress  []byte
5	ContractCalldata []byte
6}

source

Call describes an application call instruction.

Mirrors `Call` at com.rs:54.

 1type CallEnv struct {
 2	Caller             string
 3	ProxyAccount       string
 4	Path               *u256.Uint
 5	SourceChannel      string
 6	DestinationChannel string
 7	Sender             []byte
 8	Calldata           []byte
 9	Relayer            []byte
10	RelayerMsg         []byte
11}

source

1type Forward struct {
2	Path             *u256.Uint
3	TimeoutHeight    uint64
4	TimeoutTimestamp uint64
5	Instruction      Instruction
6}

source

Forward wraps another instruction for forwarding across a channel path.

Mirrors `Forward` at com.rs:46.

1type Instruction struct {
2	Version uint8
3	Opcode  uint8
4	Operand []byte
5}

source

Instruction identifies an operation and carries its ABI-encoded operand.

Mirrors `Instruction` at com.rs:40.

 1type IntentCallEnv struct {
 2	Caller             string
 3	ProxyAccount       string
 4	Path               *u256.Uint
 5	SourceChannel      string
 6	DestinationChannel string
 7	Sender             []byte
 8	Calldata           []byte
 9	MarketMaker        []byte
10	MarketMakerMsg     []byte
11}

source

1type SolverMetadata struct {
2	SolverAddress []byte
3	Metadata      []byte
4}

source

SolverMetadata carries market maker solver data.

Mirrors `SolverMetadata` at com.rs:98.

1type TokenInitializer struct {
2	Authority []byte
3	Minter    []byte
4	Name      string
5	Symbol    string
6	Decimals  uint8
7}

source

TokenInitializer holds token display metadata; decimals are metadata only, never used for scaling. Authority and Minter are the ZkgmERC20 initialize(...) EVM addresses (20 bytes each): the admin authority, and the address granted the minter role (the EVM ZKGM contract, named `zkgm` in the Solidity signature — see docs/guides/zkgm-packet-send/initialize.md). Leave them nil to encode the zero address, the default for callers that don't care about a real EVM authority/minter.

1type TokenMetadata struct {
2	Implementation []byte
3	Initializer    []byte
4}

source

TokenMetadata carries wrapped token implementation initialization data.

Mirrors `TokenMetadata` at com.rs:92.

1type TokenOrderAck struct {
2	FillType    *u256.Uint
3	MarketMaker []byte
4}

source

TokenOrderAck describes token order settlement acknowledgement data.

Mirrors `TokenOrderAck` at com.rs:114.

 1type TokenOrderV1 struct {
 2	Sender            []byte
 3	Receiver          []byte
 4	BaseToken         []byte
 5	BaseAmount        *u256.Uint
 6	BaseTokenSymbol   string
 7	BaseTokenName     string
 8	BaseTokenDecimals uint8
 9	BaseTokenPath     *u256.Uint
10	QuoteToken        []byte
11	QuoteAmount       *u256.Uint
12}

source

TokenOrderV1 is the legacy token order shape with token metadata fields.

Mirrors `TokenOrderV1` at com.rs:66.

 1type TokenOrderV2 struct {
 2	Sender      []byte
 3	Receiver    []byte
 4	BaseToken   []byte
 5	BaseAmount  *u256.Uint
 6	QuoteToken  []byte
 7	QuoteAmount *u256.Uint
 8	Kind        uint8
 9	Metadata    []byte
10}

source

TokenOrderV2 is the current token order shape.

Mirrors `TokenOrderV2` at com.rs:80.

1type ZkgmPacket struct {
2	Salt        [32]byte
3	Path        *u256.Uint
4	Instruction Instruction
5}

source

ZkgmPacket is the outer ZKGM packet envelope.

Mirrors `ZkgmPacket` at com.rs:33.

1type Zkgmable interface {
2	// OnZkgm handles a standard ZKGM Call.
3	OnZkgm(cur realm, env CallEnv) error
4
5	// OnIntentZkgm handles the intent-settlement Call variant.
6	OnIntentZkgm(cur realm, env IntentCallEnv) error
7}

source

Zkgmable is implemented by realms that receive ZKGM Call instructions dispatched from the ZKGM proxy.

bytes stdlib
crypto/keccak256 stdlib
encoding/binary stdlib
encoding/hex stdlib
errors stdlib
gno.land/p/onbloc/encoding/abi package
gno.land/p/onbloc/ibc/union/types package
gno.land/p/onbloc/math/uint256 package
math stdlib

tokenbucket

Constants 3

Variables 19

Functions 46

Types 16

Imports 9

Source Files 9

Directories 1