@temple-digital-group/temple-canton-js 1.0.30

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Temple Digital Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# Temple Canton JS
+
+JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports Amulet, USDCx, and CBTC tokens on the Canton network.
+
+## Installation
+
+```bash
+npm install @temple-digital-group/temple-canton-js
+```
+
+## Configuration
+
+There are three ways to use the SDK depending on your environment:
+
+### 1. Browser with Custom Validator
+
+For browser apps connecting to your own validator. Requires `initializeConfig()` with your validator URLs and a pre-authenticated JWT token.
+
+```javascript
+import { initializeConfig } from '@temple-digital-group/temple-canton-js';
+
+initializeConfig({
+  NETWORK: 'mainnet',
+  VALIDATOR_API_URL: 'https://your-validator-url',
+  VALIDATOR_SCAN_API_URL: 'https://your-scan-api-url',
+  TEMPLE_PARTY_ID: 'your-temple-party-id',
+  VALIDATOR_DSO_PARTY_ID: 'your-dso-party-id',
+  JWT_TOKEN: 'your-jwt-token',
+  VALIDATOR_USER_PARTY_ID: 'your-user-party-id'
+});
+```
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `NETWORK` | Yes | `mainnet`, `testnet`, or `localhost` |
+| `VALIDATOR_API_URL` | Yes | Base URL of the Canton validator ledger API |
+| `VALIDATOR_SCAN_API_URL` | Yes | Base URL of the Canton Scan API |
+| `TEMPLE_PARTY_ID` | Yes | Temple's party ID on the network |
+| `VALIDATOR_DSO_PARTY_ID` | Yes | The DSO (Decentralized Synchronizer Operator) party ID |
+| `JWT_TOKEN` | Yes | Pre-authenticated JWT token for ledger API calls |
+| `VALIDATOR_USER_PARTY_ID` | Yes | The user's party ID on the network |
+
+### 2. Browser with Wallet Provider
+
+For browser apps using a wallet (e.g., Loop Wallet). Requires `initializeConfig()` with base network config only. Use `returnCommand = true` to get the command back for the wallet to sign.
+
+```javascript
+import { initializeConfig, createOrderProposal } from '@temple-digital-group/temple-canton-js';
+
+initializeConfig({
+  NETWORK: 'mainnet',
+  TEMPLE_PARTY_ID: 'your-temple-party-id',
+  VALIDATOR_DSO_PARTY_ID: 'your-dso-party-id'
+});
+
+// returnCommand=true returns the command for the wallet to sign
+const command = await createOrderProposal(orderArgs, true, walletProvider);
+const result = await walletProvider.signAndSubmit(command);
+```
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `NETWORK` | Yes | `mainnet`, `testnet`, or `localhost` |
+| `TEMPLE_PARTY_ID` | Yes | Temple's party ID on the network |
+| `VALIDATOR_DSO_PARTY_ID` | Yes | The DSO (Decentralized Synchronizer Operator) party ID |
+
+### 3. Node.js / Server-Side
+
+For server-side applications. Uses environment variables directly — no `initializeConfig()` call needed. Create a `.env` file:
+
+```env
+NETWORK=mainnet
+VALIDATOR_API_URL=https://your-validator-url
+VALIDATOR_SCAN_API_URL=https://your-scan-api-url
+TEMPLE_PARTY_ID=your-temple-party-id
+VALIDATOR_DSO_PARTY_ID=your-dso-party-id
+
+AUTH0_TOKEN_URL=https://your-auth0-domain.auth0.com/oauth/token
+AUTH0_USER_ID=your-auth0-user-id
+AUTH0_CLIENT_ID=your-client-id
+AUTH0_CLIENT_SECRET=your-client-secret
+AUTH0_AUDIENCE=https://your-audience
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `NETWORK` | Yes | `mainnet`, `testnet`, or `localhost` |
+| `VALIDATOR_API_URL` | Yes | Base URL of the Canton validator ledger API |
+| `VALIDATOR_SCAN_API_URL` | Yes | Base URL of the Canton Scan API |
+| `TEMPLE_PARTY_ID` | Yes | Temple's party ID on the network |
+| `VALIDATOR_DSO_PARTY_ID` | Yes | The DSO (Decentralized Synchronizer Operator) party ID |
+| `AUTH0_TOKEN_URL` | Yes | Auth0 OAuth token endpoint |
+| `AUTH0_CLIENT_ID` | Yes | Auth0 application client ID |
+| `AUTH0_CLIENT_SECRET` | Yes | Auth0 application client secret |
+| `AUTH0_AUDIENCE` | Yes | Auth0 API audience identifier |
+| `AUTH0_USER_ID` | Yes | Auth0 user ID for the service account |
+
+The SDK fetches and caches JWT tokens automatically via Auth0.
+
+You can also call `initializeConfig()` in Node.js to override specific environment variables at runtime. For example, if a frontend passes a JWT token to your server:
+
+```javascript
+import { initializeConfig, getUserBalances } from '@temple-digital-group/temple-canton-js';
+
+// .env provides base config (NETWORK, VALIDATOR_API_URL, etc.)
+// Override with a token received from the frontend
+initializeConfig({ JWT_TOKEN: tokenFromFrontend });
+
+const balances = await getUserBalances(partyId);
+```
+
+Runtime config values take precedence over environment variables.
+
+
+## Supported Instruments
+
+| Asset   | Type    | Networks          |
+|---------|---------|-------------------|
+| Amulet  | Amulet  | testnet, mainnet  |
+| USDCx   | Utility | testnet, mainnet  |
+| CBTC    | Utility | testnet, mainnet  |
+
+## Supported Trading Pairs
+
+- `Amulet/USDCx`
+- `CBTC/USDCx`
+
+## Usage
+
+### Get User Balances
+
+```javascript
+import { getUserBalances } from '@temple-digital-group/temple-canton-js';
+
+const balances = await getUserBalances(partyId);
+```
+
+### Create an Order
+
+```javascript
+import { createOrderProposal } from '@temple-digital-group/temple-canton-js';
+
+const result = await createOrderProposal({
+  party: partyId,
+  symbol: 'Amulet/USDCx',
+  side: 'Buy',
+  quantity: '100',
+  pricePerUnit: '1.5',
+  expiration: new Date(Date.now() + 3600000).toISOString(),
+  userId: auth0UserId,
+  orderType: 'limit'
+});
+```
+
+### Get Orders and Proposals
+
+```javascript
+import { getOrdersForParty, getOrderProposalsForParty } from '@temple-digital-group/temple-canton-js';
+
+const orders = await getOrdersForParty(partyId);
+const proposals = await getOrderProposalsForParty(partyId);
+```
+
+### Merge Holdings
+
+```javascript
+import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty } from '@temple-digital-group/temple-canton-js';
+
+await mergeAmuletHoldingsForParty(partyId);
+await mergeUtilityHoldingsForParty(partyId, 'USDCx');
+```
+
+## API Reference
+
+> Functions marked with **W** support a wallet provider parameter. All other functions require a custom validator (ledger access via `VALIDATOR_API_URL` and `JWT_TOKEN`).
+
+### Configuration
+
+| Function | Description |
+|----------|-------------|
+| `initializeConfig(config)` | Initialize the library with a runtime config object |
+| `getConfigValue(key)` | Get a config value from runtime config or environment |
+
+### Authentication
+
+| Function | Description |
+|----------|-------------|
+| `getJWTToken()` | Get Auth0 JWT access token (cached with auto-refresh) |
+
+### Instrument Catalog
+
+These functions are synchronous and work in all environments (no ledger or provider needed).
+
+| Function | Description |
+|----------|-------------|
+| `resolveInstrumentDefinition(assetId)` | Look up an instrument definition from the catalog |
+| `getInstrumentRegistrar(assetId)` | Get the registrar party for a utility instrument |
+| `getSupportedTradingPairs()` | Get the list of supported trading pairs |
+| `getInstrumentCatalog()` | Get the full instrument catalog |
+| `checkAmuletContext(baseAsset, quoteAsset, side)` | Check if an order requires Amulet context |
+
+### Holdings
+
+| Function | Provider | Description |
+|----------|----------|-------------|
+| `getAmuletHoldingsForParty(party)` | **W** | Get Amulet holdings |
+| `getUtilityHoldingsForParty(party)` | **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 |
+
+### Orders
+
+| Function | Provider | Description |
+|----------|----------|-------------|
+| `createOrderProposal(orderArguments)` | **W** | Create an order proposal |
+| `getOrderProposalsForParty(party)` | | Get pending order proposals |
+| `getOrdersForParty(party)` | | Get active orders |
+
+### Holding Operations
+
+| Function | Description |
+|----------|-------------|
+| `mergeAmuletHoldingsForParty(party)` | Merge Amulet holdings into one |
+| `mergeUtilityHoldingsForParty(party, utilityAsset)` | Merge utility holdings into one |
+| `splitAmuletHoldingForParty(party, outputQuantity)` | Split an Amulet holding |
+| `unlockLockedAmulets(party)` | Unlock locked Amulet holdings |
+
+### Ledger Queries
+
+| Function | Description |
+|----------|-------------|
+| `getTransferFactory(investor, admin, amount, holdingIds)` | Get transfer factory from Scan API |
+| `getAmuletDisclosures(party)` | Get Amulet disclosure contracts |
+| `getAmuletRules(dso)` | Get AmuletRules contract |
+| `getExternalAmuletRules(dso)` | Get ExternalPartyAmuletRules contract |
+| `getFeaturedAppRight()` | Get FeaturedAppRight contract |
+| `getOpenMiningRounds(dso)` | Get open mining rounds |
+| `getCandidateMiningRoundContract(dso)` | Get a currently-open mining round |
+| `getUtilityInstrumentConfigurations()` | Get utility instrument configurations |
+| `getUtilityAllocationFactory()` | Get utility allocation factory |
+| `getUtilitySenderCredentials(sender)` | Get sender credentials |
+| `createUtilityCredential(holder, registrar)` | Create a utility credential |
+
+### Deprecated
+
+| Function | Description |
+|----------|-------------|
+| ~~`cancelOrders(party, orderContractIds, assetType)`~~ | Batch cancel orders (deprecated) |
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,9 @@
+// Export Canton client functions
+export * from './src/canton/index.js';
+
+// Export Auth0 utilities
+export { getJWTToken } from './src/auth0/index.js';
+
+// Export configuration
+export * from './src/config/index.js';
+

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@temple-digital-group/temple-canton-js",
+  "version": "1.0.30",
+  "description": "JavaScript library for interacting with Temple Canton blockchain",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Temple-Digital-Group/temple-canton-js.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "kakashigr <augegr@gmail.com>",
+  "keywords": [
+    "canton",
+    "blockchain",
+    "daml",
+    "splice",
+    "amulet",
+    "ledger",
+    "trading",
+    "temple"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "axios": "^1.13.1",
+    "dotenv": "^17.2.3"
+  }
+}

package/src/auth0/index.js

@@ -0,0 +1,50 @@
+import config from "../config/index.js";
+import axios from "axios";
+
+let jwtToken = null;
+let tokenExpiryTime = null;
+
+/**
+ * Get an Auth0 JWT access token with automatic caching and refresh.
+ * Tokens are cached and reused until they expire (with a 60-second buffer).
+ * Requires AUTH0_TOKEN_URL, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, and AUTH0_AUDIENCE to be configured.
+ * @returns {Promise<string|null>} The JWT access token, or null on failure
+ */
+export async function getJWTToken() {
+	// Return cached token if not expired
+	if (jwtToken != null && tokenExpiryTime != null) {
+		// Check if expired (with 60 second buffer to avoid edge cases)
+		const isExpired = Date.now() >= tokenExpiryTime - 60000;
+		if (!isExpired) {
+			return jwtToken.access_token;
+		}
+	}
+	const encodedParams = new URLSearchParams();
+	encodedParams.set("grant_type", config.AUTH0_GRANT_TYPE);
+	encodedParams.set("client_id", config.AUTH0_CLIENT_ID);
+	encodedParams.set("client_secret", config.AUTH0_CLIENT_SECRET);
+	encodedParams.set("audience", config.AUTH0_AUDIENCE);
+	encodedParams.set("scope", config.AUTH0_SCOPE);
+
+	const options = {
+		method: "POST",
+		url: config.AUTH0_TOKEN_URL,
+		headers: {
+			"content-type": "application/x-www-form-urlencoded",
+		},
+		data: encodedParams,
+	};
+
+	try {
+		const { data } = await axios.request(options);
+		jwtToken = data;
+		// Calculate expiry time: current time + expires_in (in seconds) * 1000 (to convert to milliseconds)
+		tokenExpiryTime = Date.now() + data.expires_in * 1000;
+		return jwtToken.access_token;
+	} catch (error) {
+		console.error(error);
+		tokenExpiryTime = null;
+		jwtToken = null;
+		return null;
+	}
+}