Merge remote-tracking branch 'origin/main' into feat/hypercore-support

# Conflicts:
#	packages/core/tests/bridge.test.ts

Author: kiseln

.changeset/zcash-memo-validation.md

@@ -0,0 +1,5 @@
+---
+"@omni-bridge/core": patch
+---
+
+Add destination memo typing and validation for Zcash memo handoff.

docs/core-concepts/omni-addresses.mdx

@@ -105,8 +105,10 @@ enum ChainKind {
   Btc = 6,
   Zcash = 7,
   Pol = 8,
-  Abs = 9,
-  Strk = 10
+  HyperEvm = 9,
+  Strk = 10,
+  Abs = 11,
+  Fogo = 12,
 }
 ```
 

docs/guides/advanced/manual-finalization.mdx

@@ -86,15 +86,28 @@ const initResult = await toNearKitTransaction(near, initTx).send()
 After the transfer is initialized, you must call `signTransfer` to trigger MPC signing:
 
 ```typescript
-// Extract the transfer ID from the InitTransferEvent in the logs
-const initEvent = parseInitTransferEvent(initResult)
+import { ChainKind } from "@omni-bridge/core"
+import type { InitTransferEvent } from "@omni-bridge/near"
+
+// Parse the InitTransferEvent from NEAR logs
+const initEventLog = initResult.receipts_outcome
+  .flatMap((r) => r.outcome.logs)
+  .find((log) => log.includes("InitTransferEvent"))
+
+if (!initEventLog) throw new Error("InitTransferEvent not found in logs")
+const initEvent: InitTransferEvent = JSON.parse(initEventLog).InitTransferEvent
 
 const signTx = nearBuilder.buildSignTransfer(
   {
-    origin_chain: "Near",
-    origin_nonce: initEvent.nonce,
+    origin_chain: ChainKind.Near,
+    origin_nonce: BigInt(initEvent.transfer_message.origin_nonce),
+  },
+  signerId, // fee recipient
+  {
+    fee: initEvent.transfer_message.fee.fee,
+    native_fee: initEvent.transfer_message.fee.native_fee,
   },
-  signerId
+  signerId,
 )
 
 const signResult = await toNearKitTransaction(near, signTx).send()
@@ -105,24 +118,46 @@ const signResult = await toNearKitTransaction(near, signTx).send()
 Parse the `SignTransferEvent` from the sign transaction logs and finalize on EVM:
 
 ```typescript
-import { createEvmBuilder } from "@omni-bridge/evm"
+import { createEvmBuilder, type TransferPayload } from "@omni-bridge/evm"
 import { ChainKind } from "@omni-bridge/core"
-import { MPCSignature } from "@omni-bridge/near"
+import { MPCSignature, type SignTransferEvent } from "@omni-bridge/near"
 
 const evm = createEvmBuilder({ network: "mainnet", chain: ChainKind.Eth })
 
-// Parse SignTransferEvent from signResult logs
-const signEvent = parseSignTransferEvent(signResult)
+// Parse SignTransferEvent from NEAR logs
+const signEventLog = signResult.receipts_outcome
+  .flatMap((r) => r.outcome.logs)
+  .find((log) => log.includes("SignTransferEvent"))
+
+if (!signEventLog) throw new Error("SignTransferEvent not found in logs")
+const signEvent: SignTransferEvent = JSON.parse(signEventLog).SignTransferEvent
+
+// Convert signature to EVM format (adds 27 to recovery_id)
+const signature = MPCSignature.fromRaw(signEvent.signature).toBytes(true)
+
+// Convert the NEAR payload (snake_case OmniAddresses) into the EVM TransferPayload
+const stripPrefix = (addr: string) => (addr.includes(":") ? addr.split(":")[1] : addr)
+let originChain = signEvent.message_payload.transfer_id.origin_chain
+if (typeof originChain === "string") {
+  originChain = ChainKind[originChain as keyof typeof ChainKind]
+}
 
-// Convert signature for EVM (adds 27 to recovery ID)
-const signature = MPCSignature.fromSignTransferEvent(signEvent).toBytes(true)
+const payload: TransferPayload = {
+  destinationNonce: BigInt(signEvent.message_payload.destination_nonce),
+  originChain: Number(originChain),
+  originNonce: BigInt(signEvent.message_payload.transfer_id.origin_nonce),
+  tokenAddress: stripPrefix(signEvent.message_payload.token_address) as `0x${string}`,
+  amount: BigInt(signEvent.message_payload.amount),
+  recipient: stripPrefix(signEvent.message_payload.recipient) as `0x${string}`,
+  feeRecipient: signEvent.message_payload.fee_recipient ?? "",
+}
 
-const tx = evm.buildFinalization(signEvent.message_payload, signature)
+const tx = evm.buildFinalization(payload, signature)
 await walletClient.sendTransaction(tx)
 ```
 
 <Note>
-The MPC signature needs format conversion for EVM — use `MPCSignature.toBytes(true)` to add 27 to the recovery ID. For Solana, use `toBytes(false)`.
+The MPC signature needs format conversion for EVM — use `MPCSignature.fromRaw(raw).toBytes(true)` to add 27 to the recovery ID. For Solana, pass the `MPCSignature` instance directly to the builder.
 </Note>
 
 ## From EVM to NEAR
@@ -132,24 +167,27 @@ The MPC signature needs format conversion for EVM — use `MPCSignature.toBytes(
 Ethereum uses the NEAR light client for verification:
 
 ```typescript
-import { createNearBuilder, toNearKitTransaction } from "@omni-bridge/near"
-import { getEvmProof, ProofKind } from "@omni-bridge/evm"
+import { ChainKind } from "@omni-bridge/core"
+import { createNearBuilder, ProofKind, toNearKitTransaction } from "@omni-bridge/near"
+import { getEvmProof, getInitTransferTopic } from "@omni-bridge/evm"
 
 const nearBuilder = createNearBuilder({ network: "mainnet" })
 
 // Wait for light client to sync (~15-20 min after source tx confirms)
 
-// Generate Merkle proof
-const proof = await getEvmProof(txHash, ChainKind.Eth)
+// Generate Merkle proof — needs the InitTransfer event topic and the source network
+const proof = await getEvmProof(txHash, getInitTransferTopic(), ChainKind.Eth, "mainnet")
 
-// Serialize for NEAR
-const proverArgs = nearBuilder.serializeEvmProofArgs({
-  proof_kind: ProofKind.InitTransfer,
-  proof,
+// Build and send finalization. `buildFinalization` serializes the proof internally.
+const tx = nearBuilder.buildFinalization({
+  sourceChain: ChainKind.Eth,
+  signerId,
+  evmProof: {
+    proof_kind: ProofKind.InitTransfer,
+    proof,
+  },
+  storageDepositActions: [], // add entries for recipient/fee_recipient if needed
 })
-
-// Build and send finalization
-const tx = nearBuilder.buildFinalization(ChainKind.Eth, proverArgs, signerId)
 await toNearKitTransaction(near, tx).send()
 ```
 
@@ -163,14 +201,13 @@ import { getWormholeVaa } from "@omni-bridge/core"
 // Wait for Wormhole guardians to sign (~1 min)
 const vaa = await getWormholeVaa(txSignature, "Mainnet")
 
-// Serialize for NEAR
-const proverArgs = nearBuilder.serializeWormholeProofArgs({
-  proof_kind: ProofKind.InitTransfer,
+// Finalize. `buildFinalization` serializes the VAA internally.
+const tx = nearBuilder.buildFinalization({
+  sourceChain: ChainKind.Base,
+  signerId,
   vaa,
+  storageDepositActions: [],
 })
-
-// Finalize
-const tx = nearBuilder.buildFinalization(ChainKind.Base, proverArgs, signerId)
 await toNearKitTransaction(near, tx).send()
 ```
 
@@ -183,12 +220,12 @@ import { getWormholeVaa } from "@omni-bridge/core"
 
 const vaa = await getWormholeVaa(solanaSignature, "Mainnet")
 
-const proverArgs = nearBuilder.serializeWormholeProofArgs({
-  proof_kind: ProofKind.InitTransfer,
+const tx = nearBuilder.buildFinalization({
+  sourceChain: ChainKind.Sol,
+  signerId,
   vaa,
+  storageDepositActions: [],
 })
-
-const tx = nearBuilder.buildFinalization(ChainKind.Sol, proverArgs, signerId)
 await toNearKitTransaction(near, tx).send()
 ```
 
@@ -199,7 +236,7 @@ Each destination has a `buildFinalization` method:
 | Destination | Method |
 |-------------|--------|
 | EVM | `evmBuilder.buildFinalization(payload, signature)` |
-| NEAR | `nearBuilder.buildFinalization(chain, proverArgs, signerId)` |
+| NEAR | `nearBuilder.buildFinalization({ sourceChain, signerId, vaa \| evmProof, storageDepositActions })` |
 | Solana | `solanaBuilder.buildFinalization(payload, signature, payer)` |
 
 ## Working Examples

docs/guides/advanced/token-deployment.mdx

@@ -111,15 +111,17 @@ const metadataEvent = JSON.parse(eventLog).LogMetadataEvent
 ### Step 2: Deploy Token (EVM)
 
 ```typescript
-const tx = evm.buildDeployToken(
-  metadataEvent.signature,
-  {
-    token: metadataEvent.metadata_payload.token,
-    name: metadataEvent.metadata_payload.name,
-    symbol: metadataEvent.metadata_payload.symbol,
-    decimals: metadataEvent.metadata_payload.decimals,
-  }
-)
+import { MPCSignature } from "@omni-bridge/near"
+
+// Convert the MPC signature to EVM format (adds 27 to recovery_id)
+const signature = MPCSignature.fromRaw(metadataEvent.signature).toBytes(true)
+
+const tx = evm.buildDeployToken(signature, {
+  token: metadataEvent.metadata_payload.token,
+  name: metadataEvent.metadata_payload.name,
+  symbol: metadataEvent.metadata_payload.symbol,
+  decimals: metadataEvent.metadata_payload.decimals,
+})
 
 await walletClient.sendTransaction(tx)
 ```
@@ -167,13 +169,16 @@ Solana doesn't require a separate bind step — the mapping is established durin
 ## Checking If Already Deployed
 
 ```typescript
-import { BridgeAPI } from "@omni-bridge/core"
+import { createBridge, ChainKind } from "@omni-bridge/core"
 
-const api = new BridgeAPI("mainnet")
-const tokenInfo = await api.getTokenInfo("eth:0xTokenAddress...")
+const bridge = createBridge({ network: "mainnet" })
+const bridgedToken = await bridge.getBridgedToken(
+  "eth:0xTokenAddress...",
+  ChainKind.Near,
+)
 
-if (tokenInfo.nearTokenId) {
-  console.log("Already deployed:", tokenInfo.nearTokenId)
+if (bridgedToken) {
+  console.log("Already deployed:", bridgedToken)
 } else {
   console.log("Needs deployment")
 }

docs/guides/near.mdx

@@ -64,12 +64,13 @@ console.log("Transfer initiated:", result.transaction.hash)
 <Accordion title="Using @near-js/* instead of near-kit">
 ```typescript
 import { createBridge } from "@omni-bridge/core"
-import { createNearBuilder, sendWithNearApiJs } from "@omni-bridge/near"
+import { createNearBuilder, toNearApiJsActions } from "@omni-bridge/near"
 import { Account } from "@near-js/accounts"
 import { JsonRpcProvider } from "@near-js/providers"
 import { InMemoryKeyStore } from "@near-js/keystores"
 import { KeyPair } from "@near-js/crypto"
 import { InMemorySigner } from "@near-js/signers"
+import type { Action } from "@near-js/transactions"
 
 const bridge = createBridge({ network: "mainnet" })
 const nearBuilder = createNearBuilder({ network: "mainnet" })
@@ -82,11 +83,18 @@ const account = new Account({ accountId: "alice.near", provider, signer })
 
 const signerId = "alice.near"
 
+// Helper: convert an SDK unsigned tx and dispatch via near-api-js
+const send = (tx: ReturnType<typeof nearBuilder.buildTransfer>) =>
+  account.signAndSendTransaction({
+    receiverId: tx.receiverId,
+    actions: toNearApiJsActions(tx) as Action[],
+  })
+
 // 1. Storage deposit
 const deposit = await nearBuilder.getRequiredStorageDeposit(signerId)
 if (deposit > 0n) {
   const depositTx = nearBuilder.buildStorageDeposit(signerId, deposit)
-  await sendWithNearApiJs(account, depositTx)
+  await send(depositTx)
 }
 
 // 2. Validate
@@ -101,7 +109,7 @@ const validated = await bridge.validateTransfer({
 
 // 3. Transfer
 const tx = nearBuilder.buildTransfer(validated, signerId)
-const result = await sendWithNearApiJs(account, tx)
+const result = await send(tx)
 
 console.log("Transfer initiated:", result.transaction.hash)
 ```
@@ -148,8 +156,7 @@ NEAR transactions need runtime context (nonce, block hash) that the SDK doesn't
 | Function | Library | What it does |
 |----------|---------|--------------|
 | `toNearKitTransaction()` | near-kit | Returns a chainable TransactionBuilder |
-| `sendWithNearApiJs()` | @near-js/* | Signs and sends in one call |
-| `toNearApiJsActions()` | @near-js/* | Returns raw Actions for manual handling |
+| `toNearApiJsActions()` | @near-js/* / near-api-js | Returns plain action objects for `Account.signAndSendTransaction` |
 
 The SDK returns a plain object:
 

docs/reference/core.mdx

@@ -1971,7 +1971,7 @@ async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
 import { ProofError } from "@omni-bridge/core"
 
 try {
-  const proof = await getEvmProof(txHash, topic, chain)
+  const proof = await getEvmProof(txHash, topic, chain, network)
 } catch (error) {
   if (error instanceof ProofError) {
     if (error.code === "PROOF_NOT_READY") {

packages/core/src/bridge.ts

@@ -18,6 +18,8 @@ import {
 import { getAddress, getChain, isEvmChain } from "./utils/address.js"
 import { normalizeAmount, validateTransferAmount } from "./utils/decimals.js"
 
+const MAX_ZCASH_MEMO_BYTES = 512
+
 export interface BridgeConfig {
   network: Network
   rpcUrls?: Partial<Record<ChainKind, string>>
@@ -225,6 +227,28 @@ class BridgeImpl implements Bridge {
       }
     }
 
+    if (params.destinationMemo !== undefined) {
+      if (destChain !== ChainKind.Zcash) {
+        throw new ValidationError(
+          "Destination memo is only supported for Zcash transfers",
+          "INVALID_MEMO",
+          { destChain: ChainKind[destChain], supportedChain: ChainKind[ChainKind.Zcash] },
+        )
+      }
+
+      const byteLength = new TextEncoder().encode(params.destinationMemo).length
+      if (byteLength > MAX_ZCASH_MEMO_BYTES) {
+        throw new ValidationError(
+          `Destination memo exceeds ${MAX_ZCASH_MEMO_BYTES} bytes`,
+          "INVALID_MEMO",
+          {
+            byteLength,
+            maxByteLength: MAX_ZCASH_MEMO_BYTES,
+          },
+        )
+      }
+    }
+
     // Look up bridged token first (needed for NEAR source tokens)
     let bridgedToken: OmniAddress | undefined
     if (tokenChain !== destChain) {

packages/core/src/errors.ts

@@ -17,6 +17,7 @@ export type ValidationErrorCode =
   | "INVALID_AMOUNT"
   | "INVALID_ADDRESS"
   | "INVALID_CHAIN"
+  | "INVALID_MEMO"
   | "TOKEN_NOT_REGISTERED"
   | "DECIMAL_OVERFLOW"
   | "AMOUNT_TOO_SMALL"

packages/core/src/types.ts

@@ -83,6 +83,11 @@ export interface TransferParams {
   sender: OmniAddress
   recipient: OmniAddress
   message?: string
+  /**
+   * Optional memo to attach on the destination chain. Currently supported for
+   * Zcash shielded recipients, where memos are limited to 512 bytes.
+   */
+  destinationMemo?: string
 }
 
 // Validated transfer (output from validation)