ICS20 ↔ ZKGM adapter for single-sign bridging (AtomOne ↔ Gno ↔ Union ↔ EVM)

[aronpark1007]

Background

To support single-signature bridging between AtomOne and EVM, the Gno chain acts as a protocol relay between ICS20 (spoken by AtomOne) and ZKGM/UCS03 (spoken by Union). The user signs once on either end; everything on Gno is automatic.

The two directions are symmetric in design — both use an adapter realm on Gno that translates one protocol's trigger into the other's outbound call.

Architecture

Forward: AtomOne → EVM

AtomOne ──[ICS20 + memo]──▶ Gno ──[ZKGM OP_TOKEN_ORDER]──▶ Union ──▶ EVM
                             │
                        OnRecvPacket
                        mint token
                        parse memo → ForwardMetadata
                        zkgm.Send(OP_TOKEN_ORDER)

Reverse: EVM → AtomOne

EVM ──[ZKGM OP_BATCH]──▶ Union ──▶ Gno ──[ICS20]──▶ AtomOne
                                     │
                          OP_TOKEN_ORDER → mint to adapter realm
                          OP_CALL → ZkgmIcs20Adapter.OnZkgm()
                                    parse call data → ICS20ForwardInfo
                                    ics20.Send()

Both directions reduce to the same pattern: an adapter realm on Gno parses a routing payload and fires an outbound packet on the other protocol.

Direction	Trigger	Payload
AtomOne → EVM	ICS20 memo field	{"forward": {"receiver": "0x...", "port": "transfer", "channel": "channel-1", "timeout": "10m", "retries": 2}}
EVM → AtomOne	ZKGM OP_CALL data	{"ics20": {"channel_id": X, "receiver": "cosmos1...", "timeout_timestamp": ...}}

---

Tasks

gno-realms

• Implement ICS20 transfer realm (r/aib/ibc/apps/transfer) with IBCApp interface
  • OnRecvPacket (mint/unescrow)
  • OnAcknowledgementPacket and OnTimeoutPacket (refund)
  • denom trace path construction
• Add outbound Send() function for ICS20 (required for reverse direction)
• Add TransferHook interface and SetHook() registration; hook is called after minting and its error rolls back the entire recv atomically
• Add FungibleTokenPacketData type with denom, amount, sender, receiver, memo fields and JSON encoding

gno-ibc — forward: AtomOne → EVM

• Define forward memo JSON schema (p/core/ibc/ics20hook/types.gno) following PFM standard

  {
    "forward": {
      "receiver": "0x...",
      "port": "transfer",
      "channel": "channel-1",
      "timeout": "10m",
      "retries": 2
    }
  }

• Implement ZkgmMemoHook (r/core/ibc/v1/apps/ics20hook/hook.gno): parse memo → look up denom registry → build TokenOrderV2 instruction → call zkgm.Send()
• Implement denom mapping registry (r/core/ibc/v1/apps/ics20hook/registry.gno): admin-controlled RegisterDenom / UnregisterDenom, maps ICS20 voucher denom to ZKGM baseToken
• Wire hook at chain init via ics20transfer.SetHook(zkgmMemoHook)

gno-ibc — reverse: EVM → AtomOne

• Define reverse call data JSON schema

  {"ics20": {"channel_id": X, "receiver": "cosmos1...", "timeout_timestamp": ...}}

• Implement ZkgmIcs20Adapter realm implementing OnZkgm(callEnv): parse callEnv.Operand → look up denom registry → call ics20transfer.Send()
• EVM-side packet must be OP_BATCH: [OP_TOKEN_ORDER (receiver = adapter realm), OP_CALL (receiver = adapter realm, data = ICS20ForwardInfo)] — both steps execute atomically in a single Gno tx

---

Out of Scope

• Multi-hop ZKGM forwarding via OP_FORWARD
• ICS20 v2 (ics20-v2) multi-token transfer support (AtomOne currently supports v1 only)

[aronpark1007]

A few gaps worth resolving before implementation starts, ordered by importance:

1. Forward path: no refund route after ZKGM timeout

When AtomOne → Gno ICS20 recv succeeds (success ack sent back to AtomOne) and the resulting ZKGM packet later times out, the ZKGM refund lands in the adapter realm address on Gno — there is no path back to the original sender on AtomOne. We should decide the handling policy before implementing (e.g. admin drain, or catching ZKGM ack/timeout in ZkgmMemoHook to fire a reverse ICS20 send back to AtomOne). This is the biggest fund-safety risk.

2. OnRecvPacket atomicity vs. IBCApp contract

The IBCApp interface doc states: "the underlying transaction is not aborted" when OnRecvPacket returns PacketStatus_Failure. That means store writes made before returning failure are not rolled back. The spec says "hook error rolls back the entire recv atomically," but the mechanism to achieve this (e.g. deferring the mint until after the hook succeeds, or using revive/recover) needs to be spelled out, otherwise mint-then-hook-fail leaves tokens minted with a failure ack.

3. Salt generation for zkgm.Send() inside the hook

Send() requires a [32]byte salt. The spec doesn't say how to derive it. It should be deterministic from the incoming ICS20 packet (e.g. sha256(sourceClient || sequence)) so it can be reproduced if needed and to avoid collisions (a duplicate salt panics).

4. Rate limiting for hook-initiated ZKGM sends

The existing impl runs zkgm.RateLimit() on every outbound token order (token_order.gno). It's not clear whether hook-triggered sends are subject to the same limit or are exempt. Should be explicit either way.

5. channel_id type mismatch between the two schemas

The forward memo channel_id is a ZKGM ChannelId (uint32), while the reverse call data channel_id would reference an aib IBC client ID (string). Using the same field name across schemas that have different types and semantics is confusing. Suggest distinguishing them explicitly in the schema definitions (e.g. zkgm_channel_id vs. ics20_client_id).

---

This comment was generated by Claude AI — please treat it as a reference only.

[notJoon]

In the forward architecture, it describes that we calls zkgm.Send(OP_TOKEN_ORDER) from inside OnRecvPacket, but after checking zkgm.Send calls runtime.AssertOriginCall() unconditionally. this check only passes when NumCallFrames() <= 2. the recv hook runs many frames deep inside the relayer tx, so it possibly always panics.

therefore I think we might need a new origin call exempt, adapter-gated send entry point (i.e. SendFromHook?). the codebase already has this shape in BachSend and ReleaseNative with no AssertOriginCall gate, so I think this should be works well.

additionally in reverse path, Transfer() fixes the packet Sender to unsafe.OriginCaller(). on the send side, OnSendPacket then burns the voucher from data.Sender (https://github.com/allinbits/gno-realms/blob/5cbe7cbee045bdb2203355883d5dd9454b7a50f8/gno.land/r/aib/ibc/apps/transfer/app.gno#L111-L113). in the reverse flow the OriginCaller is the relayer EOA, not the adapter realm that actually holds the minted voucher. so the burn targets the wrong account and fails.

[notJoon]

EVM-side packet must be OP_BATCH: [OP_TOKEN_ORDER (receiver = adapter realm), OP_CALL (receiver = adapter realm, data = ICS20ForwardInfo)] — both steps execute atomically in a single Gno tx

executeBatch continues after a child OP_CALL error, and the preceding OP_TOEN_ORDER mint stands. a failed reverse forward therefore leaves the voucher minted to the adapter stranded.

so the adapter OnZkgm must validate everything before taking custody (should return errors only in the pre-custody stage). should we add an admin recovery path for stranded mints?

2. OnRecvPacket atomicity vs. IBCApp contract

The IBCApp interface doc states: "the underlying transaction is not aborted" when OnRecvPacket returns PacketStatus_Failure. That means store writes made before returning failure are not rolled back. The spec says "hook error rolls back the entire recv atomically," but the mechanism to achieve this (e.g. deferring the mint until after the hook succeeds, or using revive/recover) needs to be spelled out, otherwise mint-then-hook-fail leaves tokens minted with a failure ack.

Achieve atomicity by an explicit compensating burn of the only minted voucher before returning Failure -- then the source chain refunds via the error ack. A panic would roll back the receipt too. Which means no ack is written and the user is refunded on timeout, and it lets a bad hook grief relayers. so compensating burn is more preferred over panic

[notJoon]

I considered making modifications to the gno.land/r/aib/ibc/apps/transfer package in gno-realms. However, since the transfer package does not introduce a dependency on the aib/ibc implementation, it seems simpler to fork it into the gno-ibc repository and implement the changes there.

[aronpark1007]

Note: two IBC cores in play

The adapter described in this issue spans two fundamentally different IBC transport layers:

Leg	Core realm	Model
AtomOne → Gno (ICS20)	r/aib/ibc/core	Client-based, channel-less (IBC v2 / Eureka)
Gno → Union (ZKGM)	r/core/ibc/v1/core	Channel/connection-based (IBC v1)

AtomOne runs ibc-go v10, and r/aib/ibc/core reflects this by routing packets via SourceClient/DestinationClient with no channel abstraction. r/core/ibc/v1/core follows the classic IBC v1 spec, which Union's relayer currently depends on.

As a result, ICS20 and ZKGM reference two separate core realms — packets entering from AtomOne go through the client-based core; packets leaving toward Union go through the channel-based v1 core. Each leg speaks the protocol its counterparty understands, so this is functionally correct.

This is not something we can address unilaterally. The mismatch is an external constraint: as long as Union does not support IBC v2, two cores is the only viable approach. If Union adds IBC v2 support in the future, it would be worth revisiting whether the two cores can be consolidated.