@fivenorth/loop-sdk 0.11.0 → 0.11.1

package/README.md

@@ -241,9 +241,70 @@ Coming soon
 
 Loop SDK also supports a server-side signing flow. Instead of a wallet popup, your backend signs and submits transactions directly using the user's private key.
 
+### Installation
+
+For server-side usage, you need to install the SDK and `node-forge`:
+
+```bash
+bun add @fivenorth/loop-sdk node-forge
+# or
+npm install @fivenorth/loop-sdk node-forge
+```
+
+**Note:** `node-forge` is a peer dependency and must be installed manually when using the server SDK. It's not required for browser usage.
+
+### Usage
+
+```javascript
+import { loop } from '@fivenorth/loop-sdk/server';
+
+// Initialize with private key
+loop.init({
+    privateKey: process.env.PRIVATE_KEY, // hex-encoded Ed25519 private key
+    partyId: process.env.PARTY_ID,       // your party ID
+    network: 'local',                    // or 'devnet', 'mainnet'
+    walletUrl: process.env.WALLET_URL,   // optional
+    apiUrl: process.env.API_URL,         // optional
+});
+
+// Authenticate to get API access
+await loop.authenticate();
+
+// Get the provider to interact with the ledger
+const provider = loop.getProvider();
+
+// List holdings
+const holdings = await provider.getHolding();
+console.log(holdings);
+
+// Get active contracts
+const contracts = await provider.getActiveContracts({
+    templateId: '#splice-amulet:Splice.Amulet:Amulet'
+});
+
+// Transfer tokens
+const preparedPayload = await provider.transfer(
+    'recipient::partyId',
+    1,
+    {
+        instrument_admin: '',
+        instrument_id: 'Amulet',
+    },
+    {
+        requestedAt: new Date(),
+        executeBefore: new Date(Date.now() + 24 * 60 * 60 * 1000),
+    }
+);
+
+// Execute the transaction
+const result = await loop.executeTransaction(preparedPayload);
+console.log('Transfer result:', result);
+```
+
 Example ideas:
 - List pending transfers
 - Accept a pending transfer
+- Automated transaction processing
 
 
 # Development Guide

package/dist/connection.js

@@ -0,0 +1,290 @@
+import { UnauthorizedError } from './errors';
+import { generateRequestId } from './provider';
+export class Connection {
+    walletUrl = 'https://cantonloop.com';
+    apiUrl = 'https://cantonloop.com';
+    ws = null;
+    network = 'main';
+    ticketId = null;
+    onMessageHandler = null;
+    reconnectPromise = null;
+    status = 'disconnected';
+    constructor({ network, walletUrl, apiUrl }) {
+        this.network = network || 'main';
+        // Set default common value based on network
+        switch (this.network) {
+            case 'local':
+                this.walletUrl = 'http://localhost:3000';
+                this.apiUrl = 'http://localhost:8080';
+                break;
+            case 'devnet':
+            case 'dev':
+                this.walletUrl = 'https://devnet.cantonloop.com';
+                this.apiUrl = 'https://devnet.cantonloop.com';
+                break;
+            case 'testnet':
+            case 'test':
+                this.walletUrl = 'https://testnet.cantonloop.com';
+                this.apiUrl = 'https://testnet.cantonloop.com';
+                break;
+            case 'mainnet':
+            case 'main':
+                this.walletUrl = 'https://cantonloop.com';
+                this.apiUrl = 'https://cantonloop.com';
+                break;
+        }
+        // More useful when developing locally
+        if (walletUrl) {
+            this.walletUrl = walletUrl;
+        }
+        if (apiUrl) {
+            this.apiUrl = apiUrl;
+        }
+    }
+    connectInProgress() {
+        return this.status === 'connecting' || this.status === 'connected';
+    }
+    async getTicket(appName, sessionId, version) {
+        const response = await fetch(`${this.apiUrl}/api/v1/.connect/pair/tickets`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                app_name: appName,
+                session_id: sessionId,
+                version: version,
+            }),
+        });
+        if (!response.ok) {
+            throw new Error('Failed to get ticket from server.');
+        }
+        return response.json();
+    }
+    async getHolding(authToken) {
+        const response = await fetch(`${this.apiUrl}/api/v1/.connect/pair/account/holding`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+            },
+        });
+        if (!response.ok) {
+            throw new Error('Failed to get holdings. ' + await response.text());
+        }
+        return response.json();
+    }
+    async getActiveContracts(authToken, params) {
+        const url = new URL(`${this.apiUrl}/api/v1/.connect/pair/account/active-contracts`);
+        if (params?.templateId) {
+            url.searchParams.append('templateId', params.templateId);
+        }
+        if (params?.interfaceId) {
+            url.searchParams.append('interfaceId', params.interfaceId);
+        }
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+            },
+        });
+        if (!response.ok) {
+            throw new Error('Failed to get active contracts.');
+        }
+        return response.json();
+    }
+    async prepareTransfer(authToken, params) {
+        const payload = {
+            recipient: params.recipient,
+            amount: params.amount,
+        };
+        if (params.instrument) {
+            if (params.instrument.instrument_admin) {
+                payload.instrument_admin = params.instrument.instrument_admin;
+            }
+            if (params.instrument.instrument_id) {
+                payload.instrument_id = params.instrument.instrument_id;
+            }
+        }
+        if (params.requested_at) {
+            payload.requested_at = params.requested_at;
+        }
+        if (params.execute_before) {
+            payload.execute_before = params.execute_before;
+        }
+        if (params.memo) {
+            payload.memo = params.memo;
+        }
+        const response = await fetch(`${this.apiUrl}/api/v1/.connect/pair/transfer`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            console.error('Failed to prepare transfer.', await response.text());
+            throw new Error('Failed to prepare transfer.');
+        }
+        const data = await response.json();
+        return data.payload;
+    }
+    async verifySession(authToken) {
+        const response = await fetch(`${this.apiUrl}/api/v1/.connect/pair/account`, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${authToken}`,
+            },
+        });
+        if (!response.ok) {
+            if (response.status === 401 || response.status === 403) {
+                throw new UnauthorizedError();
+            }
+            throw new Error(`Session verification failed with status ${response.status}.`);
+        }
+        const data = await response.json();
+        const email = data?.email;
+        if (!data?.party_id || !data?.public_key) {
+            throw new Error('Invalid session verification response.');
+        }
+        // Map fields from the response to the account object, handling camelCase and snake_case.
+        const account = {
+            party_id: data?.party_id,
+            auth_token: authToken,
+            public_key: data?.public_key,
+            email,
+            has_preapproval: data?.has_preapproval,
+            has_merge_delegation: data?.has_merge_delegation,
+            usdc_bridge_access: data?.usdc_bridge_access,
+        };
+        return account;
+    }
+    connectWebSocket(ticketId, onMessage) {
+        if (this.ws &&
+            (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) &&
+            this.ticketId !== ticketId) {
+            // When connecting to a new ticket, we need to close the existing socket first
+            this.ws.close();
+            this.ws = null;
+        }
+        // prevent opening multiple sockets for same ticket
+        if (this.status === 'connecting' || this.status === 'connected') {
+            return;
+        }
+        // set the message handler and ticket id to re-use for reconnecting
+        this.onMessageHandler = onMessage;
+        this.ticketId = ticketId;
+        this.status = 'connecting';
+        this.attachWebSocket(ticketId, onMessage);
+    }
+    reconnect() {
+        if (!this.ticketId || !this.onMessageHandler) {
+            return Promise.reject(new Error('Cannot reconnect without a known ticket.'));
+        }
+        return new Promise((resolve, reject) => {
+            let opened = false;
+            this.attachWebSocket(this.ticketId, this.onMessageHandler, () => {
+                opened = true;
+                resolve();
+            }, () => {
+                if (opened) {
+                    return;
+                }
+                reject(new Error('Failed to reconnect to ticket server.'));
+            }, () => {
+                if (opened) {
+                    return;
+                }
+                reject(new Error('Failed to reconnect to ticket server.'));
+            });
+        });
+    }
+    // exchangeApiKey is used to exchange the API key for the public key and signature to use in a server session
+    async exchangeApiKey({ publicKey, signature, epoch }) {
+        const response = await fetch(`${this.apiUrl}/api/v1/.connect/pair/apikey`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                public_key: publicKey,
+                signature: signature,
+                epoch: epoch,
+            })
+        });
+        if (!response.ok) {
+            throw new Error('Failed to get API key from server.');
+        }
+        return response.json();
+    }
+    // send transaction to v2/interactive-submisison/prepare endpoint to get the prepared transaction
+    prepareTransaction(session, params) {
+        return fetch(`${this.apiUrl}/api/v1/.connect/tickets/prepare-transaction`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${session.userApiKey}`,
+            },
+            body: JSON.stringify({
+                payload: params,
+                ticket_id: session.ticketId,
+            })
+        }).then(response => response.json());
+    }
+    // execute a signed transaction with v2/interactive-submisison/execute endpoint
+    async executeTransaction(session, params) {
+        if (!session.ticketId) {
+            throw new Error('Ticket ID is required');
+        }
+        const resp = fetch(`${this.apiUrl}/api/v1/.connect/tickets/execute-transaction`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${session.userApiKey}`,
+            },
+            body: JSON.stringify({
+                ticket_id: session.ticketId,
+                request_id: generateRequestId(),
+                command_id: params.command_id,
+                signature: params.signature,
+                transaction_data: params.transaction_data,
+            }),
+        });
+        return (await resp).json();
+    }
+    websocketUrl(ticketId) {
+        return `${this.network === 'local' ? 'ws' : 'wss'}://${this.apiUrl.replace('https://', '').replace('http://', '')}/api/v1/.connect/pair/ws/${encodeURIComponent(ticketId)}`;
+    }
+    // attachWebSocket is a helper function to setup even handler on a websocket object and assign to our ws 
+    attachWebSocket(ticketId, onMessage, onOpen, onError, onClose) {
+        const wsUrl = this.websocketUrl(ticketId);
+        const ws = new WebSocket(wsUrl);
+        ws.onmessage = onMessage;
+        ws.onopen = () => {
+            this.status = 'connected';
+            console.log('[LoopSDK] Connected to ticket server.');
+            onOpen?.();
+        };
+        ws.onclose = (event) => {
+            this.status = 'disconnected';
+            if (this.ws === ws) {
+                this.ws = null;
+            }
+            console.log('[LoopSDK] Disconnected from ticket server.');
+            onClose?.(event);
+        };
+        ws.onerror = (event) => {
+            // if it's already close, another close is a no-op
+            this.status = 'disconnected';
+            ws.close();
+            if (this.ws === ws) {
+                this.ws = null;
+            }
+            onError?.(event);
+        };
+        this.ws = ws;
+    }
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class RequestTimeoutError extends Error {
+    constructor(timeout) {
+        super(`Request timed out after ${timeout}ms.`);
+    }
+}
+export class RejectRequestError extends Error {
+    constructor() {
+        super('Request was rejected by the wallet.');
+    }
+}
+export class UnauthorizedError extends Error {
+    code;
+    constructor(code) {
+        super(code || 'Unauthorized');
+        this.code = code;
+    }
+}
+const UNAUTH_CODES = new Set(['UNAUTHENTICATED', 'UNAUTHORIZED', 'SESSION_EXPIRED', 'LOGGED_OUT']);
+export function extractErrorCode(message) {
+    if (typeof message?.error?.code === 'string' && message.error.code.length > 0) {
+        return message.error.code;
+    }
+    if (message?.type === 'unauthorized' && typeof message?.code === 'string') {
+        return message.code;
+    }
+    return null;
+}
+export function isUnauthCode(code) {
+    if (!code) {
+        return false;
+    }
+    return UNAUTH_CODES.has(code);
+}

package/dist/extensions/usdc/index.js

@@ -0,0 +1,52 @@
+export class UsdcBridge {
+    getProvider;
+    constructor(getProvider) {
+        this.getProvider = getProvider;
+    }
+    requireProvider() {
+        const provider = this.getProvider();
+        if (!provider) {
+            throw new Error('SDK not connected. Call connect() and wait for acceptance first.');
+        }
+        return provider;
+    }
+    withdrawalUSDCxToEthereum(recipient, amount, options) {
+        const provider = this.requireProvider();
+        const amountStr = typeof amount === 'number' ? amount.toString() : amount;
+        const withdrawRequest = {
+            recipient,
+            amount: amountStr,
+            reference: options?.reference,
+        };
+        return prepareUsdcWithdraw(provider.connection, provider.getAuthToken(), withdrawRequest).then((preparedPayload) => provider.submitTransaction({
+            commands: preparedPayload.commands,
+            disclosedContracts: preparedPayload.disclosedContracts,
+            packageIdSelectionPreference: preparedPayload.packageIdSelectionPreference,
+            actAs: preparedPayload.actAs,
+            readAs: preparedPayload.readAs,
+            synchronizerId: preparedPayload.synchronizerId,
+        }, { requestTimeout: options?.requestTimeout, message: options?.message }));
+    }
+}
+export async function prepareUsdcWithdraw(connection, authToken, params) {
+    const payload = {
+        recipient: params.recipient,
+        amount: params.amount,
+    };
+    if (params.reference) {
+        payload.reference = params.reference;
+    }
+    const response = await fetch(`${connection.apiUrl}/api/v1/.connect/pair/usdc/withdraw`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${authToken}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        throw new Error('Failed to prepare USDC withdrawal.');
+    }
+    const data = await response.json();
+    return data.payload;
+}

package/dist/extensions/usdc/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -2,7 +2,6 @@ var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __toESM = (mod, isNodeMode, target) => {
   target = mod != null ? __create(__getProtoOf(mod)) : {};
@@ -15,38 +14,7 @@ var __toESM = (mod, isNodeMode, target) => {
       });
   return to;
 };
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined")
-    return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 
 // node_modules/qrcode/lib/can-promise.js
 var require_can_promise = __commonJS((exports, module) => {