Generalise Escrow so it can be used by 3rd parties (#8356)

Author: megrogan

Cargo.lock

@@ -365,7 +365,7 @@ impl Job for NotifyEscrowCanisterOfDepositJob {
                 escrow_canister_id,
                 &escrow_canister::notify_deposit::Args {
                     swap_id: self.swap_id,
-                    user_id: Some(self.user_id),
+                    deposited_by: Some(self.user_id.into()),
                 },
             )
             .await

backend/canisters/community/impl/src/timer_job_types.rs

@@ -13,7 +13,10 @@ fn c2c_notify_p2p_swap_status_change(args: Args) {
 }
 
 fn c2c_notify_p2p_swap_status_change_impl(args: Args, state: &mut RuntimeState) {
-    let P2PSwapLocation::Message(m) = args.location;
+    let P2PSwapLocation::Message(m) = args.location else {
+        return;
+    };
+
     let mut result = None;
 
     if let Chat::Channel(_, channel_id) = m.chat {
@@ -75,7 +78,7 @@ fn c2c_notify_p2p_swap_status_change_impl(args: Args, state: &mut RuntimeState)
                         .chat
                         .events
                         .complete_p2p_swap(
-                            c.accepted_by,
+                            c.accepted_by.into(),
                             m.thread_root_message_index,
                             m.message_id,
                             c.token0_transfer_out.block_index,

backend/canisters/community/impl/src/updates/c2c_notify_p2p_swap_status_change.rs

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - Expose `liquid_cycles_balance` in metrics ([#8350](https://github.com/open-chat-labs/open-chat/pull/8350))
 - Add delay before retrying c2c call under certain error conditions ([#8355](https://github.com/open-chat-labs/open-chat/pull/8355))
+- Generalise Escrow so it can be used by 3rd parties ([#8356](https://github.com/open-chat-labs/open-chat/pull/8356))
 
 ## [[2.0.1694](https://github.com/open-chat-labs/open-chat/releases/tag/v2.0.1694-escrow)] - 2025-04-09
 

backend/canisters/escrow/CHANGELOG.md

@@ -7,6 +7,7 @@ edition.workspace = true
 
 [dependencies]
 candid = { workspace = true }
+candid_gen = { path = "../../../libraries/candid_gen" }
 icrc-ledger-types = { workspace = true }
 oc_error_codes = { path = "../../../libraries/error_codes" }
 serde = { workspace = true }

backend/canisters/escrow/api/Cargo.toml

@@ -0,0 +1,154 @@
+type CanisterId = principal;
+type ChannelId = nat32;
+type ChatId = CanisterId;
+type CommunityId = CanisterId;
+type MessageId = nat64;
+type MessageIndex = nat32;
+type TimestampMillis = nat64;
+
+type OCError = record { nat16; opt text; };
+
+type Chat = variant {
+    Direct : ChatId;
+    Group : ChatId;
+    Channel : record { CommunityId; ChannelId };
+};
+
+type TokenInfo = record {
+    symbol : text;
+    ledger : CanisterId;
+    decimals : nat8;
+    fee : nat;
+};
+
+type P2PSwapLocation = variant {
+    Message : Message;
+    External;
+};
+
+type Message = record {
+    chat : Chat;
+    thread_root_message_index : opt MessageIndex;
+    message_id : MessageId;
+};
+
+type CreateSwapArgs = record {
+    // Specifies whether the swap is associated with an OpenChat message or is External.
+    location : P2PSwapLocation;
+
+    // The token to be deposited by the offerer of the swap.
+    token0 : TokenInfo;
+
+    // The amount of token0 to be deposited. When making the deposit it is necessary to add the fee to this amount to cover the transaction fee for the swap or refund.
+    token0_amount : nat;
+
+    // The principal of the party offering the swap. If this is not specified then the caller's principal is used.
+    token0_principal : opt principal;
+
+    // The token to be deposited by the accepter of the swap.
+    token1 : TokenInfo;
+
+    // The amount of token1 to be deposited. When making the deposit it is necessary to add the fee to this amount to cover the transaction fee for the swap or refund.
+    token1_amount : nat;
+
+    // The principal of the party who can accept the swap. If this is not specified then anyone can accept the swap.
+    token1_principal : opt principal;
+
+    // The swap will expire after this timestamp.
+    expires_at : TimestampMillis;
+
+    // The principals of parties other than the offerer who can cancel the swap.
+    additional_admins : vec principal;
+
+    // If specified, this canister will be notified when the status of the swap has changed.
+    canister_to_notify : opt CanisterId;
+};
+
+type CreateSwapResponse = variant {
+    Success : record {
+        id : nat32;
+        // These addresses use the standard text encoding for ICRC-1 accounts:
+        // https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md#textual-encoding-of-icrc-1-accounts        
+        token0_deposit_address : text;
+        token1_deposit_address : opt text;
+    };
+    InvalidSwap : text;
+    Error : OCError;
+};
+
+type CancelSwapArgs = record {
+    swap_id : nat32;
+};
+
+type CancelSwapResponse = variant {
+    Success;
+    SwapAlreadyAccepted;
+    SwapExpired;
+    SwapNotFound;
+    NotAuthorized;
+    Error : OCError;
+};
+
+type NotifyDepositArgs = record {
+    swap_id : nat32;
+
+    // The principal of the party whose tokens have been deposited
+    deposited_by : opt principal;
+};
+
+type NotifyDepositResponse = variant {
+    Success : record {
+        complete : bool;
+    };
+    BalanceTooLow : record {
+        balance : nat;
+        balance_required : nat;
+    };
+    SwapAlreadyAccepted;
+    SwapCancelled;
+    SwapExpired;
+    SwapNotFound;
+    NotAuthorized;
+    InternalError : text;
+    Error : OCError;
+};
+
+type LookupSwapArgs = record {
+    swap_id : nat32;
+
+    // The principal of the accepting party or the caller if not specified
+    accepting_principal : opt principal;
+};
+
+type LookupSwapResponse = variant {
+    Success: record {
+        id : nat32;
+        location : P2PSwapLocation;
+        created_at : TimestampMillis;
+        offered_by : principal;
+        restricted_to : opt principal;
+        token0 : TokenInfo;
+        amount0 : nat;
+        // This address uses the standard text encoding for ICRC-1 accounts:
+        // https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md#textual-encoding-of-icrc-1-accounts
+        token0_deposit_address : text;
+        token1 : TokenInfo;
+        amount1 : nat;
+        // This address uses the standard text encoding for ICRC-1 accounts:
+        // https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md#textual-encoding-of-icrc-1-accounts        
+        token1_deposit_address : text;
+        expires_at : TimestampMillis;
+        additional_admins : vec principal;
+        canister_to_notify : opt CanisterId;
+    };
+    SwapNotFound;
+    PrincipalNotFound;
+    Error : OCError;
+};
+
+service : {
+    lookup_swap : (LookupSwapArgs) -> (LookupSwapResponse) query;    
+    create_swap : (CreateSwapArgs) -> (CreateSwapResponse);
+    cancel_swap : (CancelSwapArgs) -> (CancelSwapResponse);
+    notify_deposit : (NotifyDepositArgs) -> (NotifyDepositResponse);
+};

backend/canisters/escrow/api/can.did

@@ -3,12 +3,14 @@ use icrc_ledger_types::icrc1::account::Subaccount;
 use serde::Serialize;
 use sha256::sha256;
 use types::icrc1::CompletedCryptoTransaction;
-use types::{P2PSwapLocation, TimestampMillis, UserId};
+use types::{P2PSwapLocation, TimestampMillis};
 
 mod lifecycle;
+mod queries;
 mod updates;
 
 pub use lifecycle::*;
+pub use queries::*;
 pub use updates::*;
 
 #[derive(Serialize, Deserialize, Debug)]
@@ -33,13 +35,13 @@ pub struct SwapStatusExpired {
 
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SwapStatusAccepted {
-    pub accepted_by: UserId,
+    pub accepted_by: Principal,
     pub accepted_at: TimestampMillis,
 }
 
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SwapStatusCompleted {
-    pub accepted_by: UserId,
+    pub accepted_by: Principal,
     pub accepted_at: TimestampMillis,
     pub token0_transfer_out: CompletedCryptoTransaction,
     pub token1_transfer_out: CompletedCryptoTransaction,
@@ -49,14 +51,15 @@ pub struct SwapStatusCompleted {
 #[derive(Serialize, Deserialize, Debug)]
 pub struct SwapStatusChange {
     pub swap_id: u32,
-    pub created_by: UserId,
+    #[serde(alias = "created_by")]
+    pub offered_by: Principal,
     pub location: P2PSwapLocation,
     pub status: SwapStatus,
 }
 
-pub fn deposit_subaccount(user_id: UserId, swap_id: u32) -> Subaccount {
+pub fn deposit_subaccount(principal: Principal, swap_id: u32) -> Subaccount {
     let mut bytes = Vec::new();
-    bytes.extend_from_slice(Principal::from(user_id).as_slice());
+    bytes.extend_from_slice(principal.as_slice());
     bytes.extend_from_slice(&swap_id.to_be_bytes());
     sha256(&bytes)
 }

backend/canisters/escrow/api/src/lib.rs

@@ -1,4 +1,12 @@
+use candid_gen::generate_candid_method;
+
 fn main() {
+    generate_candid_method!(escrow, lookup_swap, query);
+
+    generate_candid_method!(escrow, create_swap, update);
+    generate_candid_method!(escrow, cancel_swap, update);
+    generate_candid_method!(escrow, notify_deposit, update);
+
     candid::export_service!();
     std::print!("{}", __export_service());
 }

backend/canisters/escrow/api/src/main.rs

@@ -0,0 +1,37 @@
+use candid::{CandidType, Principal};
+use oc_error_codes::OCError;
+use serde::{Deserialize, Serialize};
+use types::{CanisterId, P2PSwapLocation, TimestampMillis, TokenInfo};
+
+#[derive(CandidType, Serialize, Deserialize, Debug)]
+pub struct Args {
+    pub swap_id: u32,
+    pub accepting_principal: Option<Principal>,
+}
+
+#[expect(clippy::large_enum_variant)]
+#[derive(CandidType, Serialize, Deserialize, Debug)]
+pub enum Response {
+    Success(Swap),
+    SwapNotFound,
+    PrincipalNotFound,
+    Error(OCError),
+}
+
+#[derive(CandidType, Serialize, Deserialize, Debug)]
+pub struct Swap {
+    pub id: u32,
+    pub location: P2PSwapLocation,
+    pub created_at: TimestampMillis,
+    pub offered_by: Principal,
+    pub restricted_to: Option<Principal>,
+    pub token0: TokenInfo,
+    pub amount0: u128,
+    pub token0_deposit_address: String,
+    pub token1: TokenInfo,
+    pub amount1: u128,
+    pub token1_deposit_address: String,
+    pub expires_at: TimestampMillis,
+    pub additional_admins: Vec<Principal>,
+    pub canister_to_notify: Option<CanisterId>,
+}

backend/canisters/escrow/api/src/queries/lookup_swap.rs

@@ -0,0 +1 @@
+pub mod lookup_swap;