@temple-digital-group/temple-canton-js 1.0.35 → 1.0.36

package/README.md

@@ -98,9 +98,34 @@ const command = await createOrderProposal(orderArgs, true, walletProvider);
 ```javascript
 import { getUserBalances } from '@temple-digital-group/temple-canton-js';
 
+// Custom Validator
 const balances = await getUserBalances(partyId);
+
+// Wallet Provider
+const balances = await getUserBalances(partyId, walletProvider);
 ```
 
+Each entry in the returned array contains:
+
+```javascript
+{
+  asset: 'USDCx',              // Catalog symbol
+  total_balance: 170.5,        // Unlocked + locked combined
+  available_balance: 150.5,    // Unlocked balance (usable for orders)
+  locked_balance: 20.0,        // Locked balance
+  dso: null,                   // DSO party (Amulet only)
+  registrar: '...',            // Registrar party (utility tokens)
+  operator: '...',             // Operator party
+  provider: '...',             // Provider party
+  merge_warning: true,         // true if multiple unlocked holdings exist
+  holdings: [...],             // Unlocked holding contracts
+  locked_holdings: [...],      // Locked holding contracts
+  utilityContext: { ... }      // CIP-56 context (null when using wallet provider)
+}
+```
+
+> **Note:** `utilityContext` is only resolved when using a custom validator (ledger API access). When using a wallet provider, it will be `null`.
+
 ### Create an Order
 
 ```javascript
@@ -187,11 +212,11 @@ These functions are synchronous and work in all environments (no ledger or provi
 
 | Function | Provider | Description |
 |----------|----------|-------------|
-| `getAmuletHoldingsForParty(party)` | **W** | Get Amulet holdings |
-| `getUtilityHoldingsForParty(party)` | **W** | Get utility token holdings |
+| `getAmuletHoldingsForParty(party, returnCommand, provider)` | **W** | Get Amulet holdings |
+| `getLockedAmuletHoldingsForParty(party, returnCommand, provider)` | **W** | Get locked Amulet holdings |
+| `getUtilityHoldingsForParty(party, returnCommand, provider)` | **W** | Get utility token holdings |
 | `getCandidateHoldingForOrderCreation(party, isAmulet, quantity, assetId)` | **W** | Find a holding suitable for an order |
-| `getUserBalances(party)` | | Get all balances for a party, grouped by asset |
-| `getLockedAmuletHoldingsForParty(party)` | | Get locked Amulet holdings |
+| `getUserBalances(party, provider)` | **W** | Get all balances grouped by asset (Amulet, locked Amulet, and utility) |
 
 ### Orders
 

package/package.json

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

package/src/canton/index.js

@@ -26,6 +26,7 @@ import {
 	InstrumentKindAmulet,
 	RegistrarInternalScheme,
 	instrumentCatalog,
+	instrumentIdToSymbol,
 	supportedTradingPairs,
 	supportedSymbols
 } from "./instrumentCatalog.js";
@@ -1943,12 +1944,26 @@ export async function getAmuletHoldingsForParty(party, returnCommand = false, pr
 }
 
 /**
- * Get locked Amulet holdings for a party from the ledger.
+ * Get locked Amulet holdings for a party from the ledger or a provider.
  * @param {string} party - The party ID
  * @param {boolean} [returnCommand=false] - If true, returns the raw command/endpoint instead of executing
+ * @param {Object|null} [provider=null] - Optional external provider to use instead of ledger API
  * @returns {Promise<Object|null>} Locked holdings data, or null on failure
  */
-export async function getLockedAmuletHoldingsForParty(party, returnCommand = false) {
+export async function getLockedAmuletHoldingsForParty(party, returnCommand = false, provider = null) {
+	// When using provider, skip ledger API calls entirely
+	if (provider) {
+		const args = {
+			templateId: '#splice-amulet:Splice.Amulet:LockedAmulet'
+		};
+		try {
+			return await provider.getActiveContracts(args);
+		} catch (error) {
+			console.error(`Error fetching locked Amulet holdings via provider: ${error}`);
+			return null;
+		}
+	}
+
 	const ledgerEnd = await getLedgerEnd();
 	if (ledgerEnd === null) {
 		console.error(
@@ -3857,20 +3872,21 @@ export async function unlockLockedAmulets(party, returnCommand = false) {
  * Get all balances for a party, grouped by asset type.
  * Returns Amulet, locked Amulet, and utility token holdings with totals.
  * @param {string} party - The party ID
+ * @param {Object|null} [provider=null] - Optional wallet provider to use instead of ledger API
  * @returns {Promise<Object>} Balances grouped by registrar and asset, each with total_balance, holdings, etc.
  */
-export async function getUserBalances(party) {
-	// Get all supported instrument IDs from the catalog
-	const supportedInstruments = new Set(Object.keys(instrumentCatalog));
-
+export async function getUserBalances(party, provider = null) {
 	const promises = [
-		getAmuletHoldingsForParty(party),
-		getLockedAmuletHoldingsForParty(party),
-		getUtilityHoldingsForParty(party)
+		getAmuletHoldingsForParty(party, false, provider),
+		getLockedAmuletHoldingsForParty(party, false, provider),
+		getUtilityHoldingsForParty(party, false, provider)
 	];
 	
 	const [amuletHoldings, lockedAmuletHoldings, utilityHoldings] = await Promise.all(promises);
 
+	// Get all supported instrument IDs from the catalog
+	const supportedInstruments = new Set(Object.keys(instrumentCatalog));
+
 	// Structure: assetsByKey[registrar][asset] = { ... }
 	const assetsByKey = {};
 
@@ -3881,8 +3897,8 @@ export async function getUserBalances(party) {
 		}
 		if (!assetsByKey[key][asset]) {
 			assetsByKey[key][asset] = {
-				total_balance: 0,
-				total_locked_balance: 0,
+				available_balance: 0,
+				locked_balance: 0,
 				holdings: [],
 				locked_holdings: [],
 				registrar: metadata.registrar || null,
@@ -3905,19 +3921,16 @@ export async function getUserBalances(party) {
 		const synchronizerId = holdingData.contractEntry?.JsActiveContract?.synchronizerId || null;
 		const disclosure = createdEvent.createdEventBlob || null;
 
-		// Only include if Amulet is a supported instrument
-		if (!supportedInstruments.has("Amulet")) continue;
-
 		const catalogEntry = instrumentCatalog["Amulet"];
 		const key = dso; // For Amulet, use DSO as the key
 		const entry = initAssetEntry(key, "Amulet", {
-			registrar: catalogEntry.registrar || dso,
+			registrar: catalogEntry?.registrar || dso,
 			dso: dso,
-			operator: catalogEntry.operator,
-			provider: catalogEntry.provider
+			operator: catalogEntry?.operator || null,
+			provider: catalogEntry?.provider || null
 		});
 
-		entry.total_balance += quantity;
+		entry.available_balance += quantity;
 		entry.holdings.push({
 			contractId: createdEvent.contractId,
 			quantity: quantity,
@@ -3931,7 +3944,7 @@ export async function getUserBalances(party) {
 	for (const holdingData of lockedAmuletHoldings || []) {
 		const createdEvent = holdingData.contractEntry?.JsActiveContract?.createdEvent;
 		if (!createdEvent) continue;
-		
+
 		const quantity = parseFloat(createdEvent.createArgument?.amulet?.amount?.initialAmount || 0);
 		const dso = createdEvent.createArgument?.amulet?.dso || "Unknown DSO";
 		const synchronizerId = holdingData.contractEntry?.JsActiveContract?.synchronizerId || null;
@@ -3939,19 +3952,16 @@ export async function getUserBalances(party) {
 		const lockHolder = createdEvent.createArgument?.lock?.holders?.[0] || null;
 		const lockExpiry = createdEvent.createArgument?.lock?.expiresAt || null;
 
-		// Only include if Amulet is a supported instrument
-		if (!supportedInstruments.has("Amulet")) continue;
-
 		const catalogEntry = instrumentCatalog["Amulet"];
 		const key = dso;
 		const entry = initAssetEntry(key, "Amulet", {
-			registrar: catalogEntry.registrar || dso,
+			registrar: catalogEntry?.registrar || dso,
 			dso: dso,
-			operator: catalogEntry.operator,
-			provider: catalogEntry.provider
+			operator: catalogEntry?.operator || null,
+			provider: catalogEntry?.provider || null
 		});
 
-		entry.total_locked_balance += quantity;
+		entry.locked_balance += quantity;
 		entry.locked_holdings.push({
 			contractId: createdEvent.contractId,
 			quantity: quantity,
@@ -3970,11 +3980,16 @@ export async function getUserBalances(party) {
 		
 		const quantity = parseFloat(createdEvent.createArgument?.amount || 0);
 		let asset = createdEvent.createArgument?.instrument?.id || "Unknown Utility";
+		// Resolve on-chain instrument ID to catalog symbol (e.g. UUID -> "SBC")
+		asset = instrumentIdToSymbol[asset] || asset;
 		// Normalize "Amulet" utility tokens to "tAmulet" to distinguish from native Amulet
 		if (asset === "Amulet") {
 			asset = "tAmulet";
 		}
-		
+
+		// Only include supported instruments
+		if (!supportedInstruments.has(asset)) continue;
+
 		const registrar = createdEvent.createArgument?.instrument?.source || "Unknown Registrar";
 		const synchronizerId = holdingData.contractEntry?.JsActiveContract?.synchronizerId || null;
 		const disclosure = createdEvent.createdEventBlob || null;
@@ -3985,9 +4000,6 @@ export async function getUserBalances(party) {
 		const lockHolder = lockData?.holders?.[0] || null;
 		const lockExpiry = lockData?.expiresAt || null;
 
-		// Only include if this is a supported instrument
-		if (!supportedInstruments.has(asset)) continue;
-
 		const catalogEntry = instrumentCatalog[asset];
 		const key = registrar;
 		const entry = initAssetEntry(key, asset, {
@@ -3998,7 +4010,7 @@ export async function getUserBalances(party) {
 		});
 
 		if (isLocked) {
-			entry.total_locked_balance += quantity;
+			entry.locked_balance += quantity;
 			entry.locked_holdings.push({
 				contractId: createdEvent.contractId,
 				quantity: quantity,
@@ -4009,7 +4021,7 @@ export async function getUserBalances(party) {
 				lockExpiry
 			});
 		} else {
-			entry.total_balance += quantity;
+			entry.available_balance += quantity;
 			entry.holdings.push({
 				contractId: createdEvent.contractId,
 				quantity: quantity,
@@ -4020,49 +4032,53 @@ export async function getUserBalances(party) {
 		}
 	}
 
-	// Resolve utility contexts for non-Amulet assets
-	const utilityContextPromises = new Map();
-	for (const key of Object.keys(assetsByKey)) {
-		for (const asset of Object.keys(assetsByKey[key])) {
-			if (asset === "Amulet") {
-				continue;
-			}
-			const assetEntry = assetsByKey[key][asset];
-			if (assetEntry.utilityContext) {
-				continue;
-			}
-			const registrar = assetEntry.registrar || key;
-			const cacheKey = `${registrar || "*"}::${asset}`;
-			if (!utilityContextPromises.has(cacheKey)) {
-				utilityContextPromises.set(cacheKey, resolveUtilityCip56Context({
-					party,
-					registrar,
-					utilityAsset: asset
-				}));
+	// Only resolve utility contexts when NOT using a wallet provider
+	// (resolveUtilityCip56Context requires ledger API access)
+	if (!provider) {
+		// Resolve utility contexts for non-Amulet assets
+		const utilityContextPromises = new Map();
+		for (const key of Object.keys(assetsByKey)) {
+			for (const asset of Object.keys(assetsByKey[key])) {
+				if (asset === "Amulet") {
+					continue;
+				}
+				const assetEntry = assetsByKey[key][asset];
+				if (assetEntry.utilityContext) {
+					continue;
+				}
+				const registrar = assetEntry.registrar || key;
+				const cacheKey = `${registrar || "*"}::${asset}`;
+				if (!utilityContextPromises.has(cacheKey)) {
+					utilityContextPromises.set(cacheKey, resolveUtilityCip56Context({
+						party,
+						registrar,
+						utilityAsset: asset
+					}));
+				}
 			}
 		}
-	}
 
-	// Await all utility context promises
-	for (const [key, promise] of utilityContextPromises.entries()) {
-		utilityContextPromises.set(key, await promise);
-	}
+		// Await all utility context promises
+		for (const [key, promise] of utilityContextPromises.entries()) {
+			utilityContextPromises.set(key, await promise);
+		}
 
-	// Assign utility contexts
-	for (const key of Object.keys(assetsByKey)) {
-		for (const asset of Object.keys(assetsByKey[key])) {
-			if (asset === "Amulet") {
-				continue;
-			}
-			const assetEntry = assetsByKey[key][asset];
-			if (assetEntry.utilityContext) {
-				continue;
-			}
-			const registrar = assetEntry.registrar || key;
-			const cacheKey = `${registrar || "*"}::${asset}`;
-			assetEntry.utilityContext = utilityContextPromises.get(cacheKey) || null;
-			if (!assetEntry.registrar && assetEntry.utilityContext?.registrar) {
-				assetEntry.registrar = assetEntry.utilityContext.registrar;
+		// Assign utility contexts
+		for (const key of Object.keys(assetsByKey)) {
+			for (const asset of Object.keys(assetsByKey[key])) {
+				if (asset === "Amulet") {
+					continue;
+				}
+				const assetEntry = assetsByKey[key][asset];
+				if (assetEntry.utilityContext) {
+					continue;
+				}
+				const registrar = assetEntry.registrar || key;
+				const cacheKey = `${registrar || "*"}::${asset}`;
+				assetEntry.utilityContext = utilityContextPromises.get(cacheKey) || null;
+				if (!assetEntry.registrar && assetEntry.utilityContext?.registrar) {
+					assetEntry.registrar = assetEntry.utilityContext.registrar;
+				}
 			}
 		}
 	}
@@ -4074,8 +4090,9 @@ export async function getUserBalances(party) {
 			const assetEntry = assetsByKey[key][asset];
 			balances.push({
 				asset: asset,
-				total_balance: assetEntry.total_balance,
-				total_locked_balance: assetEntry.total_locked_balance,
+				total_balance: assetEntry.available_balance + assetEntry.locked_balance,
+				available_balance: assetEntry.available_balance,
+				locked_balance: assetEntry.locked_balance,
 				dso: assetEntry.dso,
 				registrar: assetEntry.registrar,
 				operator: assetEntry.operator,

package/src/canton/instrumentCatalog.js

@@ -132,9 +132,32 @@ export const instrumentCatalog = {
 				eventBlob: "CgMyLjESigcKRQBctH85ukdhXkql3QKxd2PMDtoDCHrmye6OOOgsE0YqrsoREiAtJTdNPPLAo2qNBxCDbU4BocW3NHP0W2qBACxdqoygyxITdXRpbGl0eS1yZWdpc3RyeS12MBqLAQpAZWQ3M2Q1YjlhYjcxNzMzM2YzZGJkMTIyZGU3YmUzMTU2ZjhiZjI2MTRhNjczNjBjM2RkNjFmYzAxMzUxMzNmYRIHVXRpbGl0eRIIUmVnaXN0cnkSAlYwEg1Db25maWd1cmF0aW9uEglBcHBSZXdhcmQaFkFwcFJld2FyZENvbmZpZ3VyYXRpb24iqgNqpwMKbApqOmhhdXRoMF8wMDdjNjY0MzUzOGYyZWFkZDNlNTczZGQwNWI5OjoxMjIwNWJjYzEwNmVmYTBlYWE3ZjE4ZGM0OTFlNWM2ZjVmYjliMGNjNjhkYzExMGFlNjZmNGVkNjQ2NzQ3NWQ3Yzc4ZQpWClQ6UmNidGMtbmV0d29yazo6MTIyMDVhZjNiOTQ5YTA0Nzc2ZmM0OGNkY2MwNWEwNjBmNmJkYTJlNDcwNjMyOTM1ZjM3NWQxMDQ5YTg1NDZhM2IyNjIK3gEK2wFq2AEKTQpLOklEU086OjEyMjBiMTQzMWVmMjE3MzQyZGI0NGQ1MTZiYjliZWZkZTgwMmJlN2Q4ODk5NjM3ZDI5MDg5NWZhNTg4ODBmMTlhY2NjCoYBCoMBaoABCmwKajpoYXV0aDBfMDA3YzY3ZGM3YzRhZmJmNWJjMzdmOTgwNWUzMTo6MTIyMDViY2MxMDZlZmEwZWFhN2YxOGRjNDkxZTVjNmY1ZmI5YjBjYzY4ZGMxMTBhZTY2ZjRlZDY0Njc0NzVkN2M3OGUKEAoOMgwwLjIwMDAwMDAwMDAqaGF1dGgwXzAwN2M2NjQzNTM4ZjJlYWRkM2U1NzNkZDA1Yjk6OjEyMjA1YmNjMTA2ZWZhMGVhYTdmMThkYzQ5MWU1YzZmNWZiOWIwY2M2OGRjMTEwYWU2NmY0ZWQ2NDY3NDc1ZDdjNzhlMlJjYnRjLW5ldHdvcms6OjEyMjA1YWYzYjk0OWEwNDc3NmZjNDhjZGNjMDVhMDYwZjZiZGEyZTQ3MDYzMjkzNWYzNzVkMTA0OWE4NTQ2YTNiMjYyOSqKuWddQgYAQioKJgokCAESIP6u2ZhXB5fXuwvdDvhv+mn6JPF20D2scQdCh/yRSuNsEB4="
 			}
 		}
-	}
+	},
+
+	// SBC (Stablecoin) -- used for balance reporting, but not a tradable instrument itself
+	"SBC": {
+		id: "f29bdd7a-1469-498a-ba2a-796bf5387b31",
+		scheme: RegistrarInternalScheme,
+		kind: InstrumentKindUtility,
+		disclosureURL: null,
+		requireCredentials: false,
+		mainnet: {
+			synchronizerId: "global-domain::1220b1431ef217342db44d516bb9befde802be7d8899637d290895fa58880f19accc",
+			registrar: "party-28dc4516-b5ca-44ff-86c7-2107e90a6807::1220b8301e18aa8a401d6e34e6c20f8b0243183c514373bca8f1b6b9270246341a9e",
+			operator: "auth0_007c6643538f2eadd3e573dd05b9::12205bcc106efa0eaa7f18dc491e5c6f5fb9b0cc68dc110ae66f4ed6467475d7c78e",
+			provider: "party-28dc4516-b5ca-44ff-86c7-2107e90a6807::1220b8301e18aa8a401d6e34e6c20f8b0243183c514373bca8f1b6b9270246341a9e",
+		}
+	},
 };
 
+// Reverse lookup: maps on-chain instrument IDs to catalog keys
+// (for instruments where the on-chain ID differs from the catalog key, e.g. UUID -> "SBC")
+export const instrumentIdToSymbol = Object.fromEntries(
+	Object.entries(instrumentCatalog)
+		.filter(([key, entry]) => entry.id && entry.id !== key)
+		.map(([key, entry]) => [entry.id, key])
+);
+
 // Supported trading pairs (like Go's supportedTradingPairs)
 export const supportedTradingPairs = [
 	{ baseAsset: "Amulet", quoteAsset: "USDCx" },