@temple-digital-group/temple-canton-js 1.0.39-beta.2 → 1.0.39-beta.4

package/README.md

@@ -245,21 +245,7 @@ const result = await withdrawFunds({
 });
 ```
 
-### 7. Emergency Withdraw
-
-Cancels ALL orders, rolls back pending settlements, and withdraws everything immediately.
-
-```javascript
-import { emergencyWithdrawFunds } from "@temple-digital-group/temple-canton-js";
-
-const result = await emergencyWithdrawFunds({
-	allocationId: "allocation-contract-id",
-	sender: partyId,
-	assetId: "USDCx",
-});
-```
-
-### 8. Withdraw Delegation
+### 7. Withdraw Delegation
 
 Archives the user's delegation contract. The user must re-onboard to trade again.
 
@@ -273,8 +259,6 @@ await withdrawDelegation();
 await withdrawDelegation(delegationContractId, partyId);
 ```
 
-## Wallet Balances
-
 ### Get User Balances
 
 ```javascript
@@ -307,24 +291,7 @@ Each entry in the returned array contains:
 }
 ```
 
-## Legacy Order Creation
 
-> `createOrderProposal` is the legacy on-ledger order creation method. For v2 trading, use `createOrderRequest` instead.
-
-```javascript
-import { createOrderProposal } from "@temple-digital-group/temple-canton-js";
-
-const result = await createOrderProposal({
-	party: partyId,
-	symbol: "CC/USDCx",
-	side: "Buy",
-	quantity: "100",
-	pricePerUnit: "1.5",
-	expiration: new Date(Date.now() + 3600000).toISOString(),
-	userId: auth0UserId,
-	orderType: "limit",
-});
-```
 
 ### Merge Holdings
 
@@ -403,14 +370,6 @@ const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
 | `splitAmuletHoldingForParty(party, outputQuantity)`                                        |          | Split an Amulet holding        |
 | `unlockLockedAmulets(party)`                                                               |          | Unlock locked Amulet holdings  |
 
-### Legacy Orders (On-Ledger)
-
-| Function                              | Provider | Description                 |
-| ------------------------------------- | -------- | --------------------------- |
-| `createOrderProposal(orderArguments)` | **W**    | Create an order proposal    |
-| `getOrderProposalsForParty(party)`    |          | Get pending order proposals |
-| `getOrdersForParty(party)`            |          | Get active orders           |
-
 ### Temple REST API
 
 > These functions call the Temple REST API. Pass `API_EMAIL`/`API_PASSWORD` in `initialize()`, or call `login()` directly — tokens are stored and auto-refreshed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temple-digital-group/temple-canton-js",
-  "version": "1.0.39-beta.2",
+  "version": "1.0.39-beta.4",
   "description": "JavaScript library for interacting with Temple Canton blockchain",
   "type": "module",
   "main": "index.js",

package/src/canton/index.js

@@ -3264,14 +3264,17 @@ export async function depositFunds(opts, returnCommand = false) {
  * @param {string} opts.allocationId - The contract ID of the allocation to withdraw.
  * @param {string} opts.sender       - The party that created the allocation (controller of Withdraw).
  * @param {string} opts.assetId      - Instrument symbol (e.g. "USDCx", "Amulet") – used to resolve the registry/scan URL.
+ * @param {object} [opts.disclosures]    - Pre-fetched Amulet disclosures (from /api/amulet/disclosures). Required for Amulet when no Scan API or ledger access.
+ * @param {string} [opts.userId]         - Temple user ID. Falls back to wallet adapter → AUTH0_USER_ID → "temple".
  * @param {boolean} [returnCommand=false] - If true, returns { command, endpoint } instead of executing.
  * @returns {Promise<Object|null>} Ledger API response (or { error } on failure).
  */
-export async function emergencyWithdrawFunds(opts, returnCommand = false) {
-	const { allocationId, sender, assetId } = opts;
+export async function finalizeWithdrawFunds(opts, returnCommand = false) {
+	const { allocationId, sender: senderOpt, assetId, disclosures, userId } = opts;
+	const sender = getAdapterPartyId() ?? senderOpt ?? config.VALIDATOR_USER_PARTY_ID;
 
 	if (!allocationId || !sender || !assetId) {
-		const msg = "emergencyWithdrawFunds: allocationId, sender, and assetId are required";
+		const msg = "finalizeWithdrawFunds: allocationId, sender, and assetId are required";
 		console.error(msg);
 		return { error: msg };
 	}
@@ -3287,7 +3290,7 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 		if (isAmulet) {
 			const amuletCtx = await resolveAmuletContext({ investor: sender, holdingIds: [], transferAmount: 0 });
 			if (!amuletCtx) {
-				const msg = "emergencyWithdrawFunds: failed to resolve Amulet context from ledger";
+				const msg = "finalizeWithdrawFunds: failed to resolve Amulet context from ledger";
 				console.error(msg);
 				return { error: msg };
 			}
@@ -3349,14 +3352,44 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 				disclosedContracts.push({ templateId: null, contractId: allocFactory.contractCid, createdEventBlob: allocFactory.disclosureCid, synchronizerId: allocFactory.synchronizerId });
 			}
 		}
-	} else {
+	} 
+	else if (isAmulet && !config.VALIDATOR_SCAN_API_URL) {
+		// Amulet via disclosures (FE/proxy path — no Scan API access)
+		// Use pre-fetched disclosures if provided, otherwise fetch from API
+		const factoryData = disclosures?.disclosures || disclosures || null;
+		let resolvedData = factoryData;
+
+		if (!resolvedData?.choiceContext) {
+			const disclosuresResult = await getDisclosures(sender);
+			resolvedData = disclosuresResult?.disclosures;
+			if (disclosuresResult?.error || !resolvedData?.choiceContext) {
+				const detail = disclosuresResult?.message || disclosuresResult?.error || "missing choiceContext in response";
+				const msg = `finalizeWithdrawFunds: failed to resolve Amulet disclosures: ${detail}`;
+				console.error(msg);
+				return { error: msg };
+			}
+		}
+
+		choiceContextData = resolvedData.choiceContext.choiceContextData || {};
+		// Ensure expire-lock is present (required by Allocation_Withdraw but not always in API response)
+		if (choiceContextData.values && !choiceContextData.values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock]) {
+			choiceContextData.values[DEFAULT_AMULET_CONTEXT_KEYS.expireLock] = { tag: "AV_Bool", value: true };
+		}
+		disclosedContracts = (resolvedData.choiceContext.disclosedContracts || []).map((dc) => ({
+			templateId: dc.templateId,
+			contractId: dc.contractId,
+			createdEventBlob: dc.createdEventBlob,
+			synchronizerId: dc.synchronizerId,
+		}));
+	}
+	else {
 		// Remote: fetch choice context from Scan API / Registry API
 		let baseUrl;
 		let contextHeaders = {};
 
 		if (isAmulet) {
 			if (!config.VALIDATOR_SCAN_API_URL) {
-				const msg = "emergencyWithdrawFunds: VALIDATOR_SCAN_API_URL is required for Amulet allocations";
+				const msg = "finalizeWithdrawFunds: VALIDATOR_SCAN_API_URL is required for Amulet allocations";
 				console.error(msg);
 				return { error: msg };
 			}
@@ -3368,7 +3401,7 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 			const registryAPI = networkContracts?.registryAPI;
 
 			if (!registryAPI) {
-				const msg = `emergencyWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
+				const msg = `finalizeWithdrawFunds: no registryAPI defined for ${assetId} on ${config.NETWORK}`;
 				console.error(msg);
 				return { error: msg };
 			}
@@ -3389,7 +3422,7 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 			contextData = contextResponse.data;
 		} catch (error) {
 			const detail = error.response?.data ? JSON.stringify(error.response.data) : error.message;
-			const msg = `emergencyWithdrawFunds: error fetching withdraw context from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
+			const msg = `finalizeWithdrawFunds: error fetching withdraw context from ${isAmulet ? "Scan API" : "Registry API"}: ${detail}`;
 			console.error(msg);
 			return { error: msg };
 		}
@@ -3421,7 +3454,7 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 			},
 		],
 		commandId: randomUUID(),
-		userId: config.AUTH0_USER_ID || "temple",
+		userId: userId || getUserId() || config.AUTH0_USER_ID || "temple",
 		applicationId: "temple",
 		actAs: [sender],
 		disclosedContracts: disclosedContracts,
@@ -3435,6 +3468,17 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 		return { command, endpoint };
 	}
 
+	// Auto-submit via wallet adapter if available
+	if (getWalletAdapter()) {
+		try {
+			return await submitCommand(command);
+		} catch (error) {
+			const msg = `finalizeWithdrawFunds: wallet adapter submission failed: ${error.message}`;
+			console.error(msg);
+			return { error: msg };
+		}
+	}
+
 	const headers = await buildHeaders();
 	try {
 		const response = await axios.post(endpoint, command, { headers });
@@ -3442,7 +3486,7 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
 	} catch (error) {
 		const errorData = error?.response?.data;
 		const errorDetail = errorData ? JSON.stringify(errorData, null, 2) : error.message;
-		const msg = `emergencyWithdrawFunds: error submitting command: ${errorDetail}`;
+		const msg = `finalizeWithdrawFunds: error submitting command: ${errorDetail}`;
 		console.error(msg);
 		return { error: msg };
 	}
@@ -3454,17 +3498,26 @@ export async function emergencyWithdrawFunds(opts, returnCommand = false) {
  * High-level withdrawal flow:
  * 1. Creates a withdrawal request via the backend API.
  * 2. Polls the request status until it is no longer "pending".
+ * 3. Exercises Allocation_Withdraw on the allocation contract to release holdings back to the user.
  *
  * @param {Object} opts
  * @param {string} opts.asset_id - Asset identifier (e.g. "USDCx", "Amulet").
  * @param {string|number} opts.amount - Amount to withdraw.
  * @param {number} [opts.pollIntervalMs=2000] - How often to poll (ms).
  * @param {number} [opts.maxPollAttempts=30]  - Max polling attempts before giving up.
- * @returns {Promise<Object>} Final withdrawal status, or { error }.
+ * @param {boolean} [returnCommand=false] - If true, returns { command, endpoint } for the Allocation_Withdraw step instead of executing.
+ * @returns {Promise<Object>} Allocation_Withdraw result, or { error }.
  */
-export async function withdrawFunds(opts) {
+export async function withdrawFunds(opts, returnCommand = false) {
 	const { asset_id, amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
 
+	const sender = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
+	if (!sender) {
+		const msg = "withdrawFunds: sender party is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID.";
+		console.error(msg);
+		return { error: msg };
+	}
+
 	// 1. Submit the withdrawal request
 	const createResult = await createWithdrawalRequest(asset_id, amount);
 	if (createResult?.error) {
@@ -3481,6 +3534,7 @@ export async function withdrawFunds(opts) {
 	console.log(`withdrawFunds: withdrawal request ${requestId} submitted, polling for status...`);
 
 	// 2. Poll until status is "ready" and allocation_cid is available
+	let allocationCid = null;
 	for (let attempt = 1; attempt <= maxPollAttempts; attempt++) {
 		await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
 
@@ -3495,10 +3549,11 @@ export async function withdrawFunds(opts) {
 			return status;
 		}
 
-		// Ready with an allocation_cid the FE can act on
+		// Ready with an allocation_cid — proceed to withdraw
 		if (status.status === "ready" && status.allocation_cid) {
 			console.log(`withdrawFunds: request ${requestId} ready — allocation_cid: ${status.allocation_cid}`);
-			return status;
+			allocationCid = status.allocation_cid;
+			break;
 		}
 
 		if (attempt % 5 === 0) {
@@ -3506,9 +3561,24 @@ export async function withdrawFunds(opts) {
 		}
 	}
 
-	const msg = `withdrawFunds: request ${requestId} not ready after ${maxPollAttempts} attempts`;
-	console.error(msg);
-	return { error: msg, request_id: requestId };
+	if (!allocationCid) {
+		const msg = `withdrawFunds: request ${requestId} not ready after ${maxPollAttempts} attempts`;
+		console.error(msg);
+		return { error: msg, request_id: requestId };
+	}
+
+	// 3. Exercise Allocation_Withdraw to release held funds back to the user
+	console.log(`withdrawFunds: exercising Allocation_Withdraw on ${allocationCid}...`);
+	const assetId = asset_id === "CC" ? "Amulet" : asset_id;
+	const withdrawResult = await finalizeWithdrawFunds({ allocationId: allocationCid, sender, assetId }, returnCommand);
+
+	if (withdrawResult?.error) {
+		console.error(`withdrawFunds: Allocation_Withdraw failed for request ${requestId}: ${withdrawResult.error}`);
+		return { error: withdrawResult.error, request_id: requestId, allocation_cid: allocationCid };
+	}
+
+	console.log(`withdrawFunds: withdrawal complete for request ${requestId}`);
+	return { ...withdrawResult, request_id: requestId, allocation_cid: allocationCid };
 }
 
 // ─── Onboarding & Delegation ─────────────────────────────────────────────────
@@ -3561,6 +3631,8 @@ export async function onboardUser(user = {}, returnCommand = false) {
 		actAs: [user.partyId],
 	};
 
+	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
+
 	if (returnCommand) {
 		return { command, endpoint };
 	}
@@ -3575,8 +3647,6 @@ export async function onboardUser(user = {}, returnCommand = false) {
 			return { error: msg };
 		}
 	}
-
-	const endpoint = `${config.VALIDATOR_API_URL}/v2/commands/submit-and-wait`;
 	const headers = await buildHeaders();
 	try {
 		const response = await axios.post(endpoint, command, { headers });