@atomiqlabs/sdk 8.7.7 → 8.9.0

package/dist/intermediaries/auth/SignedKeyBasedAuth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Adds a `x-atomiq-auth` header with the following binary format, that is hex-encoded:
+ * - 4 bytes - timestamp (timestamp when the request was sent)
+ * - 32 bytes - random bytes (entropy, to be signed)
+ *
+ * - 32 bytes - key of the signing authority
+ * - 64 bytes - schnorr signature signing the request signing key by the signing authority
+ *
+ * - 32 bytes - request signing key (signed by the signing authority)
+ * - 64 bytes - schnorr signature of the timestamp and random bytes
+ *
+ * Uses secp256k1 curve and schnorr signatures
+ */
+export declare function getSignedKeyBasedAuthHandler(certificate: string, privateKey: string): (type: "GET" | "POST", url: string, body?: any) => Record<string, string>;

package/dist/intermediaries/auth/SignedKeyBasedAuth.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSignedKeyBasedAuthHandler = void 0;
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const Utils_1 = require("../../utils/Utils");
+function parsePrivateKey(value, name) {
+    if (!/^[0-9a-fA-F]{64}$/.test(value))
+        throw new Error(`${name} must be a 32-byte hex private key`);
+    const bytes = Buffer.from(value, "hex");
+    if (!secp256k1_1.secp256k1.utils.isValidPrivateKey(bytes))
+        throw new Error(`${name} is not a valid secp256k1 private key`);
+    return bytes;
+}
+function parsePublicKey(value, name) {
+    if (!/^[0-9a-fA-F]{64}$/.test(value))
+        throw new Error(`${name} must be an X-only 32-byte hex public key`);
+    if (!secp256k1_1.secp256k1.utils.isValidPublicKey(Buffer.from("02" + value, "hex"), true))
+        throw new Error(`${name} is not a valid X-only 32-byte secp256k1 public key`);
+    return Buffer.from(value, "hex");
+}
+function parseSignature(value, name) {
+    if (!/^[0-9a-fA-F]{128}$/.test(value))
+        throw new Error(`${name} must be a valid 64-byte hex schnorr signature`);
+    return Buffer.from(value, "hex");
+}
+const CERTIFICATE_LENGTH = 64 + 128 + 64;
+/**
+ * Adds a `x-atomiq-auth` header with the following binary format, that is hex-encoded:
+ * - 4 bytes - timestamp (timestamp when the request was sent)
+ * - 32 bytes - random bytes (entropy, to be signed)
+ *
+ * - 32 bytes - key of the signing authority
+ * - 64 bytes - schnorr signature signing the request signing key by the signing authority
+ *
+ * - 32 bytes - request signing key (signed by the signing authority)
+ * - 64 bytes - schnorr signature of the timestamp and random bytes
+ *
+ * Uses secp256k1 curve and schnorr signatures
+ */
+function getSignedKeyBasedAuthHandler(certificate, privateKey) {
+    const _privateKey = parsePrivateKey(privateKey, "Private key");
+    if (certificate.length !== CERTIFICATE_LENGTH)
+        throw new Error(`Certificate has invalid length, expected ${CERTIFICATE_LENGTH}!`);
+    const authorityPublicKey = parsePublicKey(certificate.substring(0, 64), "Certificate: Authority Public key");
+    const authoritySignature = parseSignature(certificate.substring(64, 64 + 128), "Certificate: Authority Signature");
+    const signingPublicKey = parsePublicKey(certificate.substring(64 + 128), "Certificate: Signing Public key");
+    if (!secp256k1_1.schnorr.verify(authoritySignature, signingPublicKey, authorityPublicKey))
+        throw new Error("Invalid certificate, authority signature is not valid!");
+    if (!signingPublicKey.equals(secp256k1_1.schnorr.getPublicKey(privateKey)))
+        throw new Error("Passed private key doesn't match the certificate!");
+    const _certificate = Buffer.from(certificate, "hex");
+    return () => {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const timestampBuffer = Buffer.alloc(4);
+        timestampBuffer.writeUInt32BE(timestamp);
+        const requestUid = (0, Utils_1.randomBytes)(32);
+        const toSign = Buffer.concat([timestampBuffer, requestUid]);
+        const signature = secp256k1_1.schnorr.sign(toSign, _privateKey);
+        return {
+            "x-atomiq-auth": Buffer.concat([
+                toSign,
+                _certificate,
+                signature
+            ]).toString("hex")
+        };
+    };
+}
+exports.getSignedKeyBasedAuthHandler = getSignedKeyBasedAuthHandler;

package/dist/storage/IUnifiedStorage.d.ts

@@ -14,12 +14,14 @@ export type QueryParams = {
     value: any | any[];
 };
 /**
- * Base type for stored objects, every storage object MUST have an `id` field
+ * Base type for stored objects, every storage object MUST have an `id` field. The object might also specify a `_meta`
+ *  field which gets carried to the delete/save operations (and can be used to implement optimistic concurrency)
  *
  * @category Storage
  */
 export type UnifiedStoredObject = {
     id: string;
+    _meta?: any;
 } & any;
 /**
  * Defines simple indexes (for queries that use a single key)
@@ -59,27 +61,67 @@ export interface IUnifiedStorage<I extends UnifiedStorageIndexes, C extends Unif
      *  - [[condition1, condition2]] - returns all rows where condition1 AND condition2 is met
      *  - [[condition1], [condition2]] - returns all rows where condition1 OR condition2 is met
      *  - [[condition1, condition2], [condition3]] - returns all rows where (condition1 AND condition2) OR condition3 is met
+     *
+     * You can also add an optional `_meta` field in the returned unified storage object which gets attached to that
+     *  returned object and will be present for subsequent saves and removal of this object, if you specify the `_meta`
+     *  field here, you need to explicitly handle it in the all the saving and remove functions and not simply serialize
+     *  it into the storage
+     *
      * @param params
      */
     query(params: Array<Array<QueryParams>>): Promise<Array<UnifiedStoredObject>>;
     /**
      * Saves an object to storage, updating indexes as needed
+     *
+     * If the object contains a `_meta` field, this will be also present in the to-be-saved value, to mutate the `_meta`
+     *  field of the object that is saved, you can mutate the `_meta` field directly on the passed value, which then
+     *  gets reflected automatically in the existing object. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Object to save (must have an id property)
      */
     save(value: UnifiedStoredObject): Promise<void>;
     /**
      * Saves multiple objects to storage in a batch operation
+     *
+     * If the objects contain a `_meta` field, this will be also present in the to-be-saved values, to mutate the `_meta`
+     *  field of the objects that are saved, you can mutate the `_meta` field directly on the passed values, which then
+     *  gets reflected automatically in the existing objects. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Array of objects to save
+     * @param lenient In lenient mode the persistency layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    saveAll(value: UnifiedStoredObject[]): Promise<void>;
+    saveAll(value: UnifiedStoredObject[], lenient?: boolean): Promise<void>;
     /**
      * Removes an object from storage
+     *
+     * If the object contains a `_meta` field, this will be also present in the to-be-removed value, to mutate the `_meta`
+     *  field of the object that is saved, you can mutate the `_meta` field directly on the passed value, which then
+     *  gets reflected automatically in the existing object. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Object to remove (must have an id property)
      */
     remove(value: UnifiedStoredObject): Promise<void>;
     /**
      * Removes multiple objects from storage in a batch operation
+     *
+     * If the objects contain a `_meta` field, this will be also present in the to-be-removed values, to mutate the `_meta`
+     *  field of the objects that are saved, you can mutate the `_meta` field directly on the passed values, which then
+     *  gets reflected automatically in the existing objects. The mutated `_meta` field is copied even if the function
+     *  throws, hence the implementations must be careful with setting the `_meta` field on the still in-flight requests
+     *  that might fail.
+     *
      * @param value Array of objects to remove
+     * @param lenient In lenient mode the persistency layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    removeAll(value: UnifiedStoredObject[]): Promise<void>;
+    removeAll(value: UnifiedStoredObject[], lenient?: boolean): Promise<void>;
 }

package/dist/storage/UnifiedSwapStorage.d.ts

@@ -98,8 +98,11 @@ export declare class UnifiedSwapStorage<T extends ChainType> {
     /**
      * Saves multiple swaps to storage in a batch operation
      * @param values Array of swaps to save
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    saveAll<S extends ISwap<T>>(values: S[]): Promise<void>;
+    saveAll<S extends ISwap<T>>(values: S[], lenient?: boolean): Promise<void>;
     /**
      * Removes a swap from storage
      * @param value Swap to remove
@@ -108,7 +111,10 @@ export declare class UnifiedSwapStorage<T extends ChainType> {
     /**
      * Removes multiple swaps from storage in a batch operation
      * @param values Array of swaps to remove
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    removeAll<S extends ISwap<T>>(values: S[]): Promise<void>;
+    removeAll<S extends ISwap<T>>(values: S[], lenient?: boolean): Promise<void>;
 }
 export {};

package/dist/storage/UnifiedSwapStorage.js

@@ -79,18 +79,37 @@ class UnifiedSwapStorage {
     async save(value) {
         if (!this.noWeakRefMap)
             this.weakRefCache.set(value.getId(), new WeakRef(value));
-        await this.storage.save(value.serialize());
+        const serialized = value.serialize();
+        try {
+            await this.storage.save(serialized);
+        }
+        finally {
+            value._meta = serialized._meta;
+        }
         value._persisted = true;
     }
     /**
      * Saves multiple swaps to storage in a batch operation
      * @param values Array of swaps to save
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    async saveAll(values) {
+    async saveAll(values, lenient) {
         if (!this.noWeakRefMap)
             values.forEach(value => this.weakRefCache.set(value.getId(), new WeakRef(value)));
-        await this.storage.saveAll(values.map(obj => obj.serialize()));
-        values.forEach(value => value._persisted = true);
+        const serialized = values.map(obj => obj.serialize());
+        try {
+            await this.storage.saveAll(serialized, lenient);
+        }
+        finally {
+            values.forEach((value, index) => {
+                value._meta = serialized[index]._meta;
+            });
+        }
+        values.forEach((value) => {
+            value._persisted = true;
+        });
     }
     /**
      * Removes a swap from storage
@@ -99,18 +118,37 @@ class UnifiedSwapStorage {
     async remove(value) {
         if (!this.noWeakRefMap)
             this.weakRefCache.delete(value.getId());
-        await this.storage.remove(value.serialize());
+        const serialized = value.serialize();
+        try {
+            await this.storage.remove(serialized);
+        }
+        finally {
+            value._meta = serialized._meta;
+        }
         value._persisted = false;
     }
     /**
      * Removes multiple swaps from storage in a batch operation
      * @param values Array of swaps to remove
+     * @param lenient In lenient mode the underlying persistent layer doesn't throw on individual swap failures due to
+     *  optimistic concurrency, or other (implementation specific), this flag is to be used when the saving of the swap
+     *  isn't mission-critical for executing next steps (e.g. in tick or sync loops)
      */
-    async removeAll(values) {
+    async removeAll(values, lenient) {
         if (!this.noWeakRefMap)
             values.forEach(value => this.weakRefCache.delete(value.getId()));
-        await this.storage.removeAll(values.map(obj => obj.serialize()));
-        values.forEach(value => value._persisted = false);
+        const serialized = values.map(obj => obj.serialize());
+        try {
+            await this.storage.removeAll(serialized, lenient);
+        }
+        finally {
+            values.forEach((value, index) => {
+                value._meta = serialized[index]._meta;
+            });
+        }
+        values.forEach((value) => {
+            value._persisted = false;
+        });
     }
 }
 exports.UnifiedSwapStorage = UnifiedSwapStorage;

package/dist/swapper/Swapper.d.ts

@@ -39,6 +39,9 @@ import { LNURLPay } from "../types/lnurl/LNURLPay";
 import { NotNever } from "../utils/TypeUtils";
 import { LightningInvoiceCreateService } from "../types/wallets/LightningInvoiceCreateService";
 import { SwapSide } from "../enums/SwapSide";
+import { IntermediaryAPI } from "../intermediaries/apis/IntermediaryAPI";
+import { BitcoinWalletUtxo, IBitcoinWallet } from "../bitcoin/wallet/IBitcoinWallet";
+import { MinimalBitcoinWalletInterface } from "../types/wallets/MinimalBitcoinWalletInterface";
 /**
  * Configuration options for the Swapper
  * @category Core
@@ -97,8 +100,9 @@ export type SwapperOptions = {
     noTimers?: boolean;
     /**
      * By setting this flag, the swapper doesn't subscribe to on-chain events. To make sure the swap states are
-     *  properly updated you should call the {@link Swapper._syncSwaps} function periodically. This flag should be
-     *  set when you run an environment that doesn't support long-running timers and websocket connections - e.g.
+     *  properly updated you should either call the {@link Swapper._syncSwaps} function periodically, or use the
+     *  {@link Swapper._pollChainEvents} function to manually poll for on-chain events. This flag should be set
+     *  when you run an environment that doesn't support long-running timers and websocket connections - e.g.
      *  serverless environments like Azure Function Apps or AWS Lambda
      */
     noEvents?: boolean;
@@ -128,7 +132,7 @@ export type SwapperOptions = {
      *  want to only create a swap, and then later on retrieve it with the `swapper.getSwapById()` function.
      *
      * Setting this to `false` means the SDK only saves and persists swaps that are considered initiated, i.e. when
-     *  `commit()`, `execute()` or `waitTillPayment` is called (or their respective txs... prefixed variations). This
+     *  `commit()`, `execute()` or `waitTillPayment()` is called (or their respective txs... prefixed variations). This
      *  might save calls to the persistent storage for swaps that are never initiated. This is useful in e.g.
      *  frontend implementations where the frontend holds the swap object reference until it is initiated anyway, not
      *  necessitating the saving of the swap data to the persistent storage until it is actually initiated.
@@ -139,6 +143,13 @@ export type SwapperOptions = {
      *  (as checked from multiple server sources) it adjusts the `Date.now()` function to return proper actual time.
      */
     automaticClockDriftCorrection?: boolean;
+    /**
+     * Used in centralized API deployments to allow higher rate limits from LPs
+     */
+    signedKeyBasedAuth?: {
+        certificate: string;
+        privateKey: string;
+    };
 };
 /**
  * Type representing multiple blockchain configurations
@@ -246,6 +257,10 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Pricing API used by the SDK
      */
     readonly prices: ISwapPrice<T>;
+    /**
+     * API for contacting LPs
+     */
+    readonly lpApi: IntermediaryAPI;
     /**
      * Intermediary discovery instance
      */
@@ -265,6 +280,10 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Initializes the swap storage and loads existing swaps, needs to be called before any other action
      */
     init(): Promise<void>;
+    /**
+     * Whether the SDK is initialized (after {@link init} is called)
+     */
+    isInitialized(): boolean;
     /**
      * Stops listening for onchain events and closes this Swapper instance
      */
@@ -346,7 +365,7 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * @param additionalParams Additional parameters sent to the LP when creating the swap
      * @param options Additional options for the swap
      */
-    createFromBTCSwapNew<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, recipient: string, tokenAddress: string, amount: bigint, exactOut?: boolean, additionalParams?: Record<string, any> | undefined, options?: SpvFromBTCOptions): Promise<SpvFromBTCSwap<T[ChainIdentifier]>>;
+    createFromBTCSwapNew<ChainIdentifier extends ChainIds<T>>(chainIdentifier: ChainIdentifier, recipient: string, tokenAddress: string, amount: bigint | null, exactOut?: boolean, additionalParams?: Record<string, any> | undefined, options?: SpvFromBTCOptions): Promise<SpvFromBTCSwap<T[ChainIdentifier]>>;
     /**
      * Creates LEGACY Bitcoin -> Smart chain ({@link SwapType.FROM_BTC}) swap
      *
@@ -505,6 +524,44 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
     swap<C extends ChainIds<T>>(srcToken: Token<C> | string, dstToken: Token<C> | string, amount: bigint | string | undefined, exactIn: boolean | SwapAmountType, src: undefined | string | LNURLWithdraw, dst: string | LNURLPay | LightningInvoiceCreateService, options?: FromBTCLNOptions | SpvFromBTCOptions | FromBTCOptions | ToBTCOptions | (ToBTCLNOptions & {
         comment?: string;
     }) | FromBTCLNAutoOptions): Promise<ISwap<T[C]>>;
+    /**
+     * A helper function to sweep all the funds from a given wallet in a single swap, after getting the quote you can
+     *  execute the swap by passing the returned `feeRate` and `utxos` to the {@link SpvFromBTCSwap.execute},
+     *  {@link SpvFromBTCSwap.getFundedPsbt} or {@link SpvFromBTCSwap.sendBitcoinTransaction} functions along
+     *  with `spendFully=true`.
+     *
+     * @example
+     * Create the swap first using this function
+     * ```ts
+     * const {swap, utxos, btcFeeRate} = await swapper.sweepBitcoinWallet(wallet, Tokens.CITREA.CBTC, dstAddress);
+     * ```
+     * Then execute it using one of these execution paths - ensure that you supply the returned `utxos`, `btcFeeRate`
+     *  params and also set `spendFully` to `true`!
+     *
+     * a) Execute and pass the returned utxos and btcFeeRate:
+     * ```ts
+     * await swap.execute(wallet, undefined, {feeRate: btcFeeRate, utxos: utxos, spendFully: true});
+     * ```
+     *
+     * b) Get funded PSBT to sign externally:
+     * ```ts
+     * const {psbt, psbtHex, psbtBase64, signInputs} = await swap.getFundedPsbt(wallet, btcFeeRate, undefined, utxos, true);
+     * // Sign the psbt at the specified signInputs indices
+     * const signedPsbt = ...;
+     * // Then submit back to the SDK
+     * await swap.submitPsbt(signedPsbt);
+     * ```
+     *
+     * c) Only sign and send the signed PSBT with the provided wallet:
+     * ```ts
+     * await swap.sendBitcoinTransaction(wallet, btcFeeRate, utxos, true);
+     * ```
+     */
+    sweepBitcoinWallet<C extends ChainIds<T>>(srcWallet: IBitcoinWallet | MinimalBitcoinWalletInterface, _dstToken: SCToken<C> | string, dstAddress: string, options?: SpvFromBTCOptions): Promise<{
+        swap: SpvFromBTCSwap<T[C]>;
+        utxos: BitcoinWalletUtxo[];
+        btcFeeRate: number;
+    }>;
     /**
      * Returns all swaps
      */
@@ -513,6 +570,14 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * Returns all swaps for the specific chain, and optionally also for a specific signer's address
      */
     getAllSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
+    /**
+     * Returns all swaps which are pending (i.e. not in their final state yet)
+     */
+    getPendingSwaps(): Promise<ISwap[]>;
+    /**
+     * Returns swaps which are pending (i.e. not in their final state yet) for the specific chain, and optionally also for a specific signer's address
+     */
+    getPendingSwaps<C extends ChainIds<T>>(chainId: C, signer?: string): Promise<ISwap<T[C]>[]>;
     /**
      * Returns all swaps where an action is required (either claim or refund)
      */
@@ -574,6 +639,14 @@ export declare class Swapper<T extends MultiChain> extends EventEmitter<{
      * @param signer Optional signer to only run swap sync for swaps initiated by this signer
      */
     _syncSwaps<C extends ChainIds<T>>(chainId?: C, signer?: string): Promise<void>;
+    /**
+     * When the swapper is initiated with the `noEvents` config this function allows you to manually poll for on-chain
+     *  events. It returns an events cursor which you should save and pass to the next call to the `poll()` function.
+     *
+     * @param chainId Chain for which to poll the chain events listener for
+     * @param lastEventCursorState Event cursor state returned from the last call to the `poll()` function
+     */
+    _pollChainEvents<C extends ChainIds<T>>(chainId: C, lastEventCursorState?: any): Promise<any>;
     /**
      * Recovers swaps from on-chain historical data.
      *