Merge pull request #18 from Moonlight-Protocol/feat/add-client-helping-functions-to-channel-client

Author: fazzatti

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonlight/moonlight-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A privacy-focused toolkit for the Moonlight protocol on Stellar Soroban smart contracts.",
   "license": "MIT",
   "tasks": {

src/privacy-channel/index.ts

@@ -8,12 +8,20 @@ import { StellarDerivator } from "../derivation/stellar/index.ts";
 import type { StellarNetworkId } from "../derivation/stellar/stellar-network-id.ts";
 import {
   type ChannelInvokeMethods,
-  type ChannelReadMethods,
+  ChannelReadMethods,
   ChannelSpec,
 } from "./constants.ts";
-import type { ChannelInvoke, ChannelRead } from "./types.ts";
+import type {
+  ChannelInvoke,
+  ChannelRead,
+  GetUTXOAccountHandlerArgs,
+} from "./types.ts";
 import type { xdr } from "@stellar/stellar-sdk";
 import * as E from "./error.ts";
+import type { UTXOPublicKey } from "../core/utxo-keypair-base/types.ts";
+import { Buffer } from "buffer";
+import { MoonlightTransactionBuilder } from "../transaction-builder/index.ts";
+import { UtxoBasedStellarAccount } from "../utxo-based-account/utxo-based-stellar-account/index.ts";
 
 export class PrivacyChannel {
   private _client: Contract;
@@ -142,8 +150,73 @@ export class PrivacyChannel {
     return this.getClient().getContractId();
   }
 
+  /**
+   * Returns a function that fetches balances for given UTXO public keys.
+   *
+   * @returns {(publicKeys: Uint8Array[]) => Promise<bigint[]>}
+   */
+  public getBalancesFetcher(): (
+    publicKeys: UTXOPublicKey[],
+  ) => Promise<bigint[]> {
+    const fetchBalances = (publicKeys: UTXOPublicKey[]) => {
+      return this.read({
+        method: ChannelReadMethods.utxo_balances,
+        methodArgs: { utxos: publicKeys.map((pk) => Buffer.from(pk)) },
+      });
+    };
+
+    return fetchBalances;
+  }
+
+  /**
+   *  Creates and returns a MoonlightTransactionBuilder instance
+   *  pre-configured for this privacy channel.
+   *
+   * @returns {MoonlightTransactionBuilder} A pre-configured MoonlightTransactionBuilder instance.
+   */
+  public getTransactionBuilder(): MoonlightTransactionBuilder {
+    const txBuilder = new MoonlightTransactionBuilder({
+      channelId: this.getChannelId(),
+      authId: this.getAuthId(),
+      network: this.getNetworkConfig().networkPassphrase,
+      assetId: this.getAssetId(),
+    });
+
+    return txBuilder;
+  }
+
+  /**
+   *  Creates and returns a UtxoBasedStellarAccount handler
+   *  pre-configured for this privacy channel.
+   *
+   * @param {GetUTXOAccountHandlerArgs} args  - The arguments for creating the UTXO account handler.
+   * @param {Ed25519SecretKey} args.root - The root secret key for the Stellar account.
+   * @param {Object} [args.options] - Additional options for the UTXO account handler.
+   * @returns {UtxoBasedStellarAccount} A handler for UTXO-based Stellar accounts, pre-configured for this privacy channel. Use this to manage UTXO-based operations for the associated Stellar account.
+   */
+  public getUTXOAccountHandler(
+    args: GetUTXOAccountHandlerArgs,
+  ): UtxoBasedStellarAccount {
+    const { root, options } = args;
+
+    const derivator = new StellarDerivator().withNetworkAndContract(
+      this.getNetworkConfig().networkPassphrase as StellarNetworkId,
+      this.getChannelId() as ContractId,
+    );
+    const accountHandler = new UtxoBasedStellarAccount({
+      derivator,
+      root,
+      options: {
+        ...options,
+        fetchBalances: this.getBalancesFetcher(),
+      },
+    });
+
+    return accountHandler;
+  }
+
   //==========================================
-  // Read / Write Methods
+  // Contract Read / Write Methods
   //==========================================
   //
   //

src/privacy-channel/types.ts

@@ -1,6 +1,11 @@
-import type { ContractId, Ed25519PublicKey } from "@colibri/core";
+import type {
+  ContractId,
+  Ed25519PublicKey,
+  Ed25519SecretKey,
+} from "@colibri/core";
 import type { Buffer } from "node:buffer";
 import type { ChannelInvokeMethods, ChannelReadMethods } from "./constants.ts";
+import type { UTXOBasedAccountConstructorArgs } from "../utxo-based-account/types.ts";
 
 export type ChannelConstructorArgs = {
   admin: Ed25519PublicKey | ContractId;
@@ -73,3 +78,19 @@ export type ChannelInvoke = {
     output: None;
   };
 };
+
+export type GetUTXOAccountHandlerArgs =
+  & Pick<
+    UTXOBasedAccountConstructorArgs<string, Ed25519SecretKey, `${number}`>,
+    "root"
+  >
+  & {
+    options?: Omit<
+      UTXOBasedAccountConstructorArgs<
+        string,
+        Ed25519SecretKey,
+        `${number}`
+      >["options"],
+      "fetchBalances"
+    >;
+  };

src/utxo-based-account/index.ts

@@ -2,7 +2,10 @@ import { UTXOKeypair } from "../core/utxo-keypair/index.ts";
 import { UTXOStatus } from "../core/utxo-keypair/types.ts";
 import type { BaseDerivator } from "../derivation/base/index.ts";
 import { UTXOSelectionStrategy } from "./selection-strategy.ts";
-import type { UTXOSelectionResult } from "./types.ts";
+import type {
+  UTXOBasedAccountConstructorArgs,
+  UTXOSelectionResult,
+} from "./types.ts";
 import * as E from "./error.ts";
 import { assert } from "../utils/assert/assert.ts";
 /**
@@ -46,16 +49,7 @@ export class UtxoBasedAccount<
   /**
    * Creates a new UtxoBasedAccount instance
    */
-  constructor(args: {
-    derivator: BaseDerivator<Context, Root, Index>;
-    root: Root;
-    options?: {
-      batchSize?: number;
-      fetchBalances?: (publicKeys: Uint8Array[]) => Promise<bigint[]>;
-      startIndex?: number;
-      maxReservationAgeMs?: number;
-    };
-  }) {
+  constructor(args: UTXOBasedAccountConstructorArgs<Context, Root, Index>) {
     this.root = args.root;
     this.derivator = args.derivator;
     this.derivator.withRoot(this.root);

src/utxo-based-account/types.ts

@@ -1,4 +1,5 @@
 import type { UTXOKeypair } from "../core/utxo-keypair/index.ts";
+import type { BaseDerivator } from "../derivation/base/index.ts";
 
 /**
  * Result of UTXO selection for transfers
@@ -8,3 +9,18 @@ export interface UTXOSelectionResult<Context extends string> {
   totalAmount: bigint;
   changeAmount: bigint;
 }
+
+export type UTXOBasedAccountConstructorArgs<
+  Context extends string,
+  Root extends string,
+  Index extends `${number}`,
+> = {
+  derivator: BaseDerivator<Context, Root, Index>;
+  root: Root;
+  options?: {
+    batchSize?: number;
+    fetchBalances?: (publicKeys: Uint8Array[]) => Promise<bigint[]>;
+    startIndex?: number;
+    maxReservationAgeMs?: number;
+  };
+};