feat: replace postActions/extraMsg with safe_deposit for UTXO deposits

.changeset/safe-deposit-utxo.md

@@ -0,0 +1,6 @@
+---
+"@omni-bridge/core": minor
+"@omni-bridge/near": minor
+---
+
+Replace `postActions`/`extraMsg` with `safe_deposit` on `getUtxoDepositAddress`. NEAR builder now calls `safe_verify_deposit` when `safe_deposit` is provided.

docs/reference/core.mdx

@@ -20,6 +20,7 @@ import {
   type TransferStatus,
   type Chain,
   type PostAction,
+  type SafeDeposit,
   type UtxoChainParam,
   type UtxoDepositAddressResponse,
 
@@ -427,12 +428,14 @@ bridge.getUtxoDepositAddress(
   Optional configuration for the deposit.
 
   <Expandable title="UtxoDepositOptions properties">
-    <ResponseField name="postActions" type="PostAction[]">
-      Post-actions to execute after the deposit is finalized on NEAR. Used for automatic bridging to other chains.
-    </ResponseField>
-
-    <ResponseField name="extraMsg" type="string">
-      Extra message to include in the deposit.
+    <ResponseField name="safeDeposit" type="SafeDeposit">
+      Safe deposit message. When provided, the deposit will use `safe_verify_deposit` on finalization.
+
+      <Expandable title="SafeDeposit properties">
+        <ResponseField name="msg" type="string" required>
+          Message for the safe deposit.
+        </ResponseField>
+      </Expandable>
     </ResponseField>
   </Expandable>
 </ResponseField>
@@ -454,10 +457,6 @@ bridge.getUtxoDepositAddress(
     <ResponseField name="recipient" type="string">
       The recipient on NEAR.
     </ResponseField>
-
-    <ResponseField name="postActions" type="PostAction[]">
-      Post-actions if any were provided.
-    </ResponseField>
   </Expandable>
 </ResponseField>
 
@@ -474,16 +473,12 @@ const deposit = await bridge.getUtxoDepositAddress(
 
 console.log(`Send BTC to: ${deposit.address}`)
 
-// With post-actions for automatic bridging to Ethereum
-const depositWithBridge = await bridge.getUtxoDepositAddress(
+// With safe deposit
+const safeDeposit = await bridge.getUtxoDepositAddress(
   ChainKind.Btc,
   "alice.near",
   {
-    postActions: [{
-      receiver_id: "omni.bridge.near",
-      amount: "0",
-      msg: JSON.stringify({ recipient: "eth:0x..." }),
-    }]
+    safeDeposit: { msg: "safe deposit" }
   }
 )
 ```
@@ -860,8 +855,7 @@ Gets a deposit address for Bitcoin or Zcash.
 api.getUtxoDepositAddress(
   chain: UtxoChainParam,
   recipient: string,
-  postActions?: PostAction[] | null,
-  extraMsg?: string | null
+  safeDeposit?: SafeDeposit | null
 ): Promise<UtxoDepositAddressResponse>
 ```
 
@@ -875,36 +869,16 @@ api.getUtxoDepositAddress(
   NEAR recipient account ID.
 </ResponseField>
 
-<ResponseField name="postActions" type="PostAction[] | null">
-  Optional post-actions to execute after deposit finalization.
-
-  <Expandable title="PostAction properties">
-    <ResponseField name="receiver_id" type="string" required>
-      NEAR account to receive the action.
-    </ResponseField>
-
-    <ResponseField name="amount" type="string" required>
-      Amount to send with the action.
-    </ResponseField>
+<ResponseField name="safeDeposit" type="SafeDeposit | null">
+  Optional safe deposit message.
 
+  <Expandable title="SafeDeposit properties">
     <ResponseField name="msg" type="string" required>
-      Message/arguments for the action.
-    </ResponseField>
-
-    <ResponseField name="gas" type="string">
-      Optional gas limit.
-    </ResponseField>
-
-    <ResponseField name="memo" type="string | null">
-      Optional memo.
+      Message for the safe deposit.
     </ResponseField>
   </Expandable>
 </ResponseField>
 
-<ResponseField name="extraMsg" type="string | null">
-  Optional extra message.
-</ResponseField>
-
 ### Returns
 
 <ResponseField name="UtxoDepositAddressResponse" type="UtxoDepositAddressResponse">

docs/reference/near.mdx

@@ -61,6 +61,7 @@ import {
   type UtxoDepositFinalizationParams,
   type UtxoDepositMsg,
   type UtxoPostAction,
+  type UtxoSafeDeposit,
   type UtxoWithdrawalInitParams,
   type UtxoWithdrawalOutput,
   type UtxoWithdrawalVerifyParams,
@@ -785,7 +786,7 @@ Methods for interacting with the Bitcoin and Zcash UTXO connectors on NEAR.
 
 ### buildUtxoDepositFinalization
 
-Build a transaction to finalize a UTXO deposit on NEAR. Calls `verify_deposit` on the connector contract.
+Build a transaction to finalize a UTXO deposit on NEAR. Calls `verify_deposit` (or `safe_verify_deposit` when `safe_deposit` is provided) on the connector contract.
 
 #### Signature
 
@@ -814,6 +815,10 @@ buildUtxoDepositFinalization(params: UtxoDepositFinalizationParams): NearUnsigne
         <ResponseField name="extra_msg" type="string">
           Optional extra message.
         </ResponseField>
+
+        <ResponseField name="safe_deposit" type="UtxoSafeDeposit">
+          Safe deposit message. When provided, uses `safe_verify_deposit` instead of `verify_deposit`.
+        </ResponseField>
       </Expandable>
     </ResponseField>
 

packages/core/src/api.ts

@@ -195,6 +195,10 @@ const PostActionSchema = z.object({
 })
 export type PostAction = z.infer<typeof PostActionSchema>
 
+export interface SafeDeposit {
+  msg: string
+}
+
 const UtxoDepositAddressResponseSchema = z.object({
   address: z.string(),
 })
@@ -358,19 +362,15 @@ export class BridgeAPI {
   async getUtxoDepositAddress(
     chain: UtxoChainParam,
     recipient: string,
-    postActions?: PostAction[] | null,
-    extraMsg?: string | null,
+    safeDeposit?: SafeDeposit | null,
   ): Promise<UtxoDepositAddressResponse> {
     const body: Record<string, unknown> = {
       chain,
       recipient,
     }
 
-    if (postActions !== undefined && postActions !== null) {
-      body["post_actions"] = postActions
-    }
-    if (extraMsg !== undefined && extraMsg !== null) {
-      body["extra_msg"] = extraMsg
+    if (safeDeposit !== undefined && safeDeposit !== null) {
+      body["safe_deposit"] = safeDeposit
     }
 
     const url = this.buildUrl("/api/v3/utxo/get_user_deposit_address")
@@ -401,9 +401,8 @@ export class BridgeAPI {
   async getUtxoUserDepositAddress(
     chain: UtxoChainParam,
     recipient: string,
-    postActions?: PostAction[] | null,
-    extraMsg?: string | null,
+    safeDeposit?: SafeDeposit | null,
   ): Promise<UtxoDepositAddressResponse> {
-    return this.getUtxoDepositAddress(chain, recipient, postActions, extraMsg)
+    return this.getUtxoDepositAddress(chain, recipient, safeDeposit)
   }
 }

packages/core/src/bridge.ts

@@ -3,7 +3,7 @@
  */
 
 import { Near } from "near-kit"
-import { BridgeAPI, type Chain, type PostAction, type UtxoChainParam } from "./api.js"
+import { BridgeAPI, type Chain, type SafeDeposit, type UtxoChainParam } from "./api.js"
 import { type ChainAddresses, getAddresses } from "./config.js"
 import { ValidationError } from "./errors.js"
 import {
@@ -28,14 +28,10 @@ export interface BridgeConfig {
  */
 export interface UtxoDepositOptions {
   /**
-   * Post-actions to execute after the deposit is finalized on NEAR.
-   * Used for automatic bridging to other chains.
+   * Safe deposit message. When provided, the deposit will use `safe_verify_deposit`
+   * which requires a NEAR deposit but doesn't need post-actions.
    */
-  postActions?: PostAction[]
-  /**
-   * Extra message to include in the deposit
-   */
-  extraMsg?: string
+  safeDeposit?: SafeDeposit
 }
 
 /**
@@ -54,10 +50,6 @@ export interface UtxoDepositResult {
    * The recipient on NEAR
    */
   recipient: string
-  /**
-   * Post-actions if any were provided
-   */
-  postActions?: PostAction[]
 }
 
 /**
@@ -331,21 +323,14 @@ class BridgeImpl implements Bridge {
     const response = await this.api.getUtxoDepositAddress(
       chainParam,
       recipient,
-      options?.postActions,
-      options?.extraMsg,
+      options?.safeDeposit,
     )
 
-    const result: UtxoDepositResult = {
+    return {
       address: response.address,
       chain: chainParam,
       recipient,
     }
-
-    if (options?.postActions) {
-      result.postActions = options.postActions
-    }
-
-    return result
   }
 }
 

packages/core/src/index.ts

@@ -11,6 +11,7 @@ export {
   type BridgeAPIConfig,
   type Chain,
   type PostAction,
+  type SafeDeposit,
   type Transfer,
   type TransferStatus,
   type UtxoChainParam,

packages/core/tests/api.test.ts

@@ -262,20 +262,10 @@ describe("BridgeAPI", () => {
       })
     })
 
-    it("should handle post actions parameter", async () => {
-      const postActions = [
-        {
-          receiver_id: "receiver.near",
-          amount: "1000000000000000000000000",
-          msg: "test message",
-        },
-      ]
-      const response = await api.getUtxoDepositAddress(
-        "btc",
-        "recipient.near",
-        postActions,
-        "extra message",
-      )
+    it("should handle safe_deposit parameter", async () => {
+      const response = await api.getUtxoDepositAddress("btc", "recipient.near", {
+        msg: "safe deposit message",
+      })
       expect(response).toEqual({
         address: "tb1qssh0ejglq0v53pwrsxlhxpxw29gfu6c4ls9eyy",
       })

packages/near/src/builder.ts

@@ -607,6 +607,7 @@ class NearBuilderImpl implements NearBuilder {
     const connector = this.getUtxoConnectorAddress(params.chain)
 
     // Build deposit_msg for the contract (convert bigint amounts to strings)
+    const isSafeDeposit = params.depositMsg.safe_deposit != null
     const depositMsg = {
       recipient_id: params.depositMsg.recipient_id,
       post_actions: params.depositMsg.post_actions?.map((action) => ({
@@ -617,6 +618,7 @@ class NearBuilderImpl implements NearBuilder {
         gas: action.gas?.toString(),
       })),
       extra_msg: params.depositMsg.extra_msg,
+      safe_deposit: params.depositMsg.safe_deposit,
     }
 
     const args = {
@@ -630,10 +632,10 @@ class NearBuilderImpl implements NearBuilder {
 
     const action: NearAction = {
       type: "FunctionCall",
-      methodName: "verify_deposit",
+      methodName: isSafeDeposit ? "safe_verify_deposit" : "verify_deposit",
       args: encodeArgs(args),
       gas: GAS.UTXO_VERIFY_DEPOSIT,
-      deposit: 0n,
+      deposit: isSafeDeposit ? DEPOSIT.SAFE_VERIFY_DEPOSIT : 0n,
     }
 
     return {

packages/near/src/index.ts

@@ -47,6 +47,7 @@ export {
   type UtxoDepositFinalizationParams,
   type UtxoDepositMsg,
   type UtxoPostAction,
+  type UtxoSafeDeposit,
   type UtxoWithdrawalInitParams,
   type UtxoWithdrawalOutput,
   type UtxoWithdrawalSignParams,

packages/near/src/types.ts

@@ -30,6 +30,7 @@ export const GAS = {
 export const DEPOSIT = {
   ONE_YOCTO: BigInt(parseAmount("1 yocto")),
   MPC_SIGNING: BigInt(parseAmount("0.25 NEAR")),
+  SAFE_VERIFY_DEPOSIT: BigInt(parseAmount("0.0012 NEAR")),
 } as const
 
 /**
@@ -254,13 +255,22 @@ export interface UtxoPostAction {
   gas?: bigint
 }
 
+/**
+ * Safe deposit message for UTXO deposits.
+ * When present, the finalization uses `safe_verify_deposit` instead of `verify_deposit`.
+ */
+export interface UtxoSafeDeposit {
+  msg: string
+}
+
 /**
  * Deposit message for UTXO deposits
  */
 export interface UtxoDepositMsg {
   recipient_id: string
   post_actions?: UtxoPostAction[]
   extra_msg?: string
+  safe_deposit?: UtxoSafeDeposit
 }
 
 /**

packages/near/tests/utxo.test.ts

@@ -1,7 +1,7 @@
 import { ChainKind } from "@omni-bridge/core"
 import { describe, expect, it } from "vitest"
 import { createNearBuilder } from "../src/builder.js"
-import { GAS, DEPOSIT } from "../src/types.js"
+import { DEPOSIT, GAS } from "../src/types.js"
 
 describe("NearBuilder UTXO methods", () => {
   const builder = createNearBuilder({ network: "testnet" })
@@ -98,6 +98,29 @@ describe("NearBuilder UTXO methods", () => {
       expect(args.deposit_msg.post_actions).toHaveLength(1)
       expect(args.deposit_msg.post_actions[0].amount).toBe("1000000")
     })
+
+    it("uses safe_verify_deposit when safe_deposit is provided", () => {
+      const tx = builder.buildUtxoDepositFinalization({
+        chain: "btc",
+        depositMsg: {
+          recipient_id: "alice.testnet",
+          safe_deposit: { msg: "safe deposit" },
+        },
+        txBytes: [0x01, 0x02],
+        vout: 0,
+        txBlockBlockhash: "00000000000000000001abc123",
+        txIndex: 1,
+        merkleProof: ["hash1"],
+        signerId: "relayer.testnet",
+      })
+
+      expect(tx.actions[0]?.methodName).toBe("safe_verify_deposit")
+      expect(tx.actions[0]?.deposit).toBe(DEPOSIT.SAFE_VERIFY_DEPOSIT)
+
+      const argsJson = new TextDecoder().decode(tx.actions[0]?.args)
+      const args = JSON.parse(argsJson)
+      expect(args.deposit_msg.safe_deposit).toEqual({ msg: "safe deposit" })
+    })
   })
 
   describe("buildUtxoWithdrawalInit", () => {