emblem-vault-sdk 2.9.1 → 2.10.0

package/docs/index.html

@@ -122,7 +122,8 @@
             let contract = window.curatedContracts[index];
             let template = contract.generateCreateTemplate(contract)
             template.chainId = 1
-            template.toAddress = document.getElementById('ethAddress').value;
+            let toAddr = document.getElementById('toAddress').value;
+            template.toAddress = toAddr ? toAddr : document.getElementById('ethAddress').value;
             template.fromAddress = document.getElementById('ethAddress').value;
             window.contract = contract;
             window.template = template;
@@ -204,6 +205,8 @@
     </script>
     <input type="text" id="ethAddress" placeholder="Enter ETH Address" oninput="localStorage.setItem('ethAddress', this.value)" value="">
 
+    <input type="text" id="toAddress" placeholder="To Address (optional)" oninput="localStorage.setItem('toAddress', this.value)" value="">
+
     <input type="checkbox" id="hideNotMintableCheckbox" checked onchange="generateDropdown(window.curatedContracts)">
     <label for="hideNotMintableCheckbox">Hide Not Mintable</label>
 
@@ -243,6 +246,9 @@
         <a href="steps.html" target="_blank">Full Create / Mint : Demo</a>
     </div>
     
-    <script>document.getElementById('ethAddress').value = localStorage.getItem('ethAddress');</script>
+    <script>
+        document.getElementById('ethAddress').value = localStorage.getItem('ethAddress');
+        document.getElementById('toAddress').value = localStorage.getItem('toAddress');
+    </script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emblem-vault-sdk",
-  "version": "2.9.1",
+  "version": "2.10.0",
   "description": "Emblem Vault Software Development Kit",
   "main": "dist/index.js",
   "scripts": {
@@ -12,7 +12,7 @@
     "test:browser": "JEST_ENV=browser jest",
     "test:all": "npm run test:node && npm run test:browser",
     "build": "tsc",
-    "postbuild": "node ./script/version.js && mv dist/index.d.ts types/index.d.ts && mv dist/types.d.ts types/types.d.ts && mv dist/utils.d.ts types/utils.d.ts && mv dist/derive.d.ts types/derive.d.ts",
+    "postbuild": "node ./script/version.js && mv dist/index.d.ts types/index.d.ts && mv dist/types.d.ts types/types.d.ts && mv dist/utils.d.ts types/utils.d.ts && mv dist/derive.d.ts types/derive.d.ts && mv dist/constants.d.ts types/constants.d.ts && mv dist/evm-operations.d.ts types/evm-operations.d.ts && mv dist/signing-messages.d.ts types/signing-messages.d.ts && mv dist/vault-utils.d.ts types/vault-utils.d.ts",
     "bundle": "npm run build && browserify dist/index.js -o dist/bundle.js && cp dist/bundle.js docs/bundle.js",
     "watch": "onchange 'src/*.ts' -- npm run bundle"
   },
@@ -24,6 +24,7 @@
     "@types/crypto-js": "^4.2.2",
     "@types/jest": "^29.5.11",
     "browserify": "^17.0.0",
+    "esmify": "^2.1.1",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "jest-puppeteer": "^9.0.2",
@@ -44,6 +45,7 @@
     "bitcore-mnemonic": "^10.0.23",
     "crypto-js": "^4.2.0",
     "ethereumjs-util": "^7.1.5",
+    "ethers": "^5.7.2",
     "install": "^0.13.0",
     "npm": "^10.4.0",
     "sats-connect": "^1.4.1",
@@ -54,4 +56,4 @@
   "engines": {
     "node": ">=20.5.1"
   }
-}
+}

package/readme.md

@@ -8,6 +8,7 @@ The Emblem Vault SDK is a JavaScript library that provides functionality for int
 - [Fetching Curated Contracts](#fetching-curated-contracts)
 - [Creating a Vault](#creating-a-vault)
 - [Refreshing Vault Balance](#refreshing-vault-balance)
+- [Fetching Vaults by Type](#fetching-vaults-by-type)
 - [Validating Mintability](#validating-mintability)
 - [Performing a Mint](#performing-a-mint)
 - [Utility Functions](#utility-functions)
@@ -88,6 +89,37 @@ To refresh the balance of a vault, use the refreshBalance method:
 ```javascript
 vaultBalance = await sdk.refreshBalance(vaultData.tokenId, updateLogCallback);
 ```
+
+## Fetching Vaults by Type
+To fetch vaults owned by an address, use the `fetchVaultsOfType` method:
+
+```javascript
+// Fetch all vaults (returns full array)
+const vaults = await sdk.fetchVaultsOfType('created', '0xYourAddress');
+
+// Vault types: "vaulted", "unvaulted", "created"
+```
+
+### Pagination Support
+For large collections, use pagination to fetch vaults in pages:
+
+```javascript
+// Fetch a specific page (returns { data, pagination } object)
+const result = await sdk.fetchVaultsOfType('created', '0xYourAddress', { page: 1, limit: 100 });
+
+console.log(result.data);       // Array of vaults for this page
+console.log(result.pagination); // { page: 1, limit: 100, total: 500, totalPages: 5 }
+```
+
+### Fetching All Vaults with Progress
+To automatically fetch all pages with progress tracking:
+
+```javascript
+const allVaults = await sdk.fetchAllVaultsOfType('created', '0xYourAddress', (page, totalPages, total) => {
+    console.log(`Fetched page ${page}/${totalPages} (${total} total vaults)`);
+});
+```
+
 ## Validating Mintability
 To validate if a vault is mintable, use the allowed method of the curated contract object:
 

package/src/constants.ts

@@ -0,0 +1,47 @@
+// ============================================================================
+// Supported Chains
+// ============================================================================
+
+export const ETHEREUM_MAINNET_CHAIN_ID = 1;
+export const POLYGON_MAINNET_CHAIN_ID = 137;
+export const SOLANA_CHAIN_IDENTIFIER = 'solana';
+
+export type ChainType = 'evm' | 'solana';
+
+export interface ChainConfig {
+    type: ChainType;
+    name: string;
+    handlerContract?: string;
+    unvaultingContract?: string;
+}
+
+export const SUPPORTED_CHAINS: Record<number | string, ChainConfig> = {
+    [ETHEREUM_MAINNET_CHAIN_ID]: {
+        type: 'evm',
+        name: 'Ethereum Mainnet',
+        handlerContract: '0x23859b51117dbFBcdEf5b757028B18d7759a4460',
+        unvaultingContract: '0x214C964bBd3640971E111d3a994CbB89b296a9ad',
+    },
+    [POLYGON_MAINNET_CHAIN_ID]: {
+        type: 'evm',
+        name: 'Polygon Mainnet',
+        handlerContract: '0x23859b51117dbFBcdEf5b757028B18d7759a4460',
+        unvaultingContract: '0x214C964bBd3640971E111d3a994CbB89b296a9ad',
+    },
+};
+
+// ============================================================================
+// Contract Addresses (default to Ethereum mainnet)
+// ============================================================================
+
+export const HANDLER_CONTRACT_ADDRESS = '0x23859b51117dbFBcdEf5b757028B18d7759a4460';
+export const UNVAULTING_DIAMOND_ADDRESS = '0x214C964bBd3640971E111d3a994CbB89b296a9ad';
+export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+// ============================================================================
+// API Endpoints
+// ============================================================================
+
+export const EMBLEM_API_V2 = 'https://v2.emblemvault.io';
+export const EMBLEM_API_2 = 'https://api2.emblemvault.io';
+export const TORUS_SIGNER_API = 'https://tor-us-signer-coval.vercel.app';

package/src/evm-operations.ts

@@ -0,0 +1,391 @@
+import type {
+    EvmSigner,
+    EmblemVaultClient,
+    ProgressCallback,
+    MintResult,
+    ClaimResult,
+    RemoteMintSignature,
+    RemoteUnvaultSignature,
+    MetaData,
+    SdkContext,
+} from './types';
+
+import {
+    ZERO_ADDRESS,
+    EMBLEM_API_2,
+    TORUS_SIGNER_API,
+} from './constants';
+
+import {
+    buildMintMessage,
+    buildClaimMessage,
+    buildUnvaultMessage,
+    buildDeleteMessage,
+} from './signing-messages';
+
+import {
+    getHandlerContractAddress,
+    getUnvaultingContractAddress,
+} from './vault-utils';
+
+import { fetchData, parseBigIntValue } from './utils';
+
+const EVM_RPC_URLS: Record<number, string> = {
+    1: 'https://eth.llamarpc.com',
+    137: 'https://polygon-rpc.com',
+};
+
+function getEvmRpcUrl(chainId: number): string {
+    return EVM_RPC_URLS[chainId] || EVM_RPC_URLS[1];
+}
+
+export async function performMintEvm(
+    ctx: SdkContext,
+    client: EmblemVaultClient,
+    tokenId: string,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<MintResult> {
+    callback?.('Initializing EVM signer...');
+    const { ethers } = await import('ethers');
+    const provider = new ethers.providers.JsonRpcProvider(getEvmRpcUrl(chainId));
+    const wallet = await client.toEthersWallet(provider);
+    wallet.setChainId?.(chainId);
+
+    callback?.('Signing mint request...');
+    const mintMessage = buildMintMessage(tokenId);
+    const mintRequestSig = await wallet.signMessage(mintMessage);
+
+    callback?.('Getting remote mint signature...');
+    const remoteMintSig = await requestRemoteMintSignature(ctx, tokenId, mintRequestSig, chainId);
+
+    callback?.('Submitting mint transaction...');
+    const txHash = await submitMintTransaction(wallet, remoteMintSig, chainId, callback);
+
+    callback?.('Mint complete!', { txHash });
+    return { txHash, tokenId, chainId };
+}
+
+export async function performClaimEvm(
+    ctx: SdkContext,
+    client: EmblemVaultClient,
+    tokenId: string,
+    chainId: number,
+    metadata: MetaData,
+    claimIdentifier: string,
+    vaultIsV2: boolean,
+    needsOnChainUnvault: boolean,
+    callback?: ProgressCallback
+): Promise<ClaimResult> {
+    callback?.('Initializing EVM signer...');
+    const { ethers } = await import('ethers');
+    const provider = new ethers.providers.JsonRpcProvider(getEvmRpcUrl(chainId));
+    const wallet = await client.toEthersWallet(provider);
+    wallet.setChainId?.(chainId);
+
+    // Determine if vault needs on-chain claim/unvault before getting keys
+    // For minted vaults (live=true, status=unclaimed), we must claim on-chain first
+    const isMinted = metadata.live === true || metadata.status === 'unclaimed';
+    const isAlreadyClaimed = metadata.status === 'claimed' || Boolean(metadata.claimedBy);
+    
+    if (isMinted && !isAlreadyClaimed) {
+        if (needsOnChainUnvault) {
+            // V2 vault: use unvaultWithSignedPrice
+            await performOnChainUnvault(
+                ctx,
+                wallet,
+                tokenId,
+                claimIdentifier,
+                metadata.collectionAddress,
+                chainId,
+                callback
+            );
+        } else {
+            // Non-V2 vault: use handler's claim function
+            const targetContractAddress = metadata.targetContract?.[chainId] || metadata.collectionAddress;
+            if (targetContractAddress) {
+                callback?.('Performing on-chain claim...');
+                await performLegacyClaim(wallet, targetContractAddress, claimIdentifier, chainId, callback);
+            }
+        }
+    }
+
+    callback?.('Signing claim message...');
+    const claimMessage = buildClaimMessage(claimIdentifier, vaultIsV2);
+    const signature = await wallet.signMessage(claimMessage);
+
+    callback?.('Requesting claim token...');
+    const jwt = await requestClaimToken(tokenId, signature, chainId);
+
+    callback?.('Requesting remote key...');
+    const decryptionKeys = await ctx.requestRemoteKey(tokenId, jwt, callback);
+    if (!decryptionKeys) {
+        throw new Error('Failed to get decryption key');
+    }
+
+    callback?.('Decrypting vault keys...');
+    return await ctx.decryptVaultKeys(tokenId, decryptionKeys, callback);
+}
+
+export async function deleteVaultEvm(
+    client: EmblemVaultClient,
+    tokenId: string,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<boolean> {
+    callback?.('Initializing EVM signer...');
+    const wallet = await client.toEthersWallet(null);
+    wallet.setChainId?.(chainId);
+
+    callback?.('Signing delete message...');
+    const deleteMessage = buildDeleteMessage(tokenId);
+    const signature = await wallet.signMessage(deleteMessage);
+
+    callback?.('Deleting vault...');
+    const response = await fetch(`${EMBLEM_API_2}/v2/delete`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            service: 'evmetadata',
+        },
+        body: JSON.stringify({
+            tokenId,
+            signature,
+            chainId: chainId.toString(),
+        }),
+    });
+
+    if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new Error(errorData.message || 'Failed to delete vault');
+    }
+
+    callback?.('Vault deleted successfully');
+    return true;
+}
+
+async function requestRemoteMintSignature(
+    ctx: SdkContext,
+    tokenId: string,
+    signature: string,
+    chainId: number
+): Promise<RemoteMintSignature> {
+    const url = `${ctx.baseUrl}/mint-curated`;
+    const remoteMintResponse = await fetchData(
+        url,
+        ctx.apiKey,
+        'POST',
+        {
+            method: 'buyWithSignedPrice',
+            tokenId,
+            signature,
+            chainId: chainId.toString(),
+        }
+    );
+
+    // Handle both 'error' and 'err' fields (API inconsistency)
+    const errorMsg = remoteMintResponse.error || remoteMintResponse.err;
+    if (errorMsg) {
+        const message = typeof errorMsg === 'string'
+            ? errorMsg
+            : errorMsg.msg || errorMsg.message || JSON.stringify(errorMsg);
+        throw new Error(message);
+    }
+
+    return remoteMintResponse as RemoteMintSignature;
+}
+
+async function submitMintTransaction(
+    wallet: EvmSigner,
+    remoteMintSig: RemoteMintSignature,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<string> {
+    const { ethers } = await import('ethers');
+
+    const handlerAddress = getHandlerContractAddress(chainId);
+    const priceBigInt = parseBigIntValue(remoteMintSig._price);
+
+    const iface = new ethers.utils.Interface([
+        'function buyWithSignedPrice(address _nftAddress, address _payment, uint256 _price, address _to, uint256 _tokenId, uint256 _nonce, bytes _signature, bytes serialNumber, uint256 _amount) payable'
+    ]);
+
+    const data = iface.encodeFunctionData('buyWithSignedPrice', [
+        remoteMintSig._nftAddress,
+        ZERO_ADDRESS,
+        priceBigInt,
+        remoteMintSig._to,
+        parseBigIntValue(remoteMintSig._tokenId),
+        parseBigIntValue(remoteMintSig._nonce),
+        remoteMintSig._signature,
+        remoteMintSig.serialNumber,
+        BigInt(1),
+    ]);
+
+    const tx = await wallet.sendTransaction({
+        to: handlerAddress,
+        data,
+        value: priceBigInt,
+    });
+
+    callback?.('Waiting for confirmation...', { txHash: tx.hash });
+    await tx.wait();
+
+    return tx.hash;
+}
+
+async function performOnChainUnvault(
+    ctx: SdkContext,
+    wallet: EvmSigner,
+    tokenId: string,
+    claimIdentifier: string,
+    nftAddress: string | undefined,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<void> {
+    callback?.('Signing unvault request...');
+    // Sign with tokenId to match server expectation (server verifies "Unvault: " + req.body.tokenId)
+    const unvaultMessage = buildUnvaultMessage(tokenId);
+    const unvaultSignature = await wallet.signMessage(unvaultMessage);
+
+    callback?.('Requesting remote unvault signature...');
+    const remoteUnvaultSig = await requestRemoteUnvaultSignature(ctx, tokenId, unvaultSignature, chainId);
+
+    callback?.('Submitting on-chain unvault transaction...');
+    await submitUnvaultTransaction(wallet, remoteUnvaultSig, nftAddress, chainId, callback);
+
+    callback?.('On-chain unvault complete, retrieving keys...');
+}
+
+/**
+ * Perform legacy claim by calling the handler contract's claim function
+ * This is for non-V2 vaults that don't use signed price unvaulting
+ */
+async function performLegacyClaim(
+    wallet: EvmSigner,
+    targetContractAddress: string,
+    tokenId: string,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<void> {
+    const { ethers } = await import('ethers');
+    
+    // Handler contract ABI for claim function
+    const HANDLER_CLAIM_ABI = [
+        'function claim(address _nftAddress, uint256 _tokenId) external'
+    ];
+    
+    const handlerAddress = getHandlerContractAddress(chainId);
+    const iface = new ethers.utils.Interface(HANDLER_CLAIM_ABI);
+    
+    const data = iface.encodeFunctionData('claim', [
+        targetContractAddress,
+        BigInt(tokenId),
+    ]);
+
+    callback?.('Submitting claim transaction...');
+    const tx = await wallet.sendTransaction({
+        to: handlerAddress,
+        data,
+    });
+
+    callback?.('Waiting for claim confirmation...', { txHash: tx.hash });
+    await tx.wait();
+    
+    callback?.('On-chain claim complete!');
+}
+
+async function requestRemoteUnvaultSignature(
+    ctx: SdkContext,
+    tokenId: string,
+    signature: string,
+    chainId: number
+): Promise<RemoteUnvaultSignature> {
+    const response = await fetch(`${ctx.baseUrl}/unvault-curated`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            method: 'unvaultWithSignedPrice',
+            tokenId,
+            signature,
+            chainId: chainId.toString(),
+        }),
+    });
+
+    const remoteUnvaultSig = await response.json() as RemoteUnvaultSignature;
+
+    if (!remoteUnvaultSig?.success) {
+        throw new Error(
+            remoteUnvaultSig?.msg || remoteUnvaultSig?.err || 'Failed to get remote unvault signature'
+        );
+    }
+
+    return remoteUnvaultSig;
+}
+
+async function submitUnvaultTransaction(
+    wallet: EvmSigner,
+    remoteUnvaultSig: RemoteUnvaultSignature,
+    nftAddress: string | undefined,
+    chainId: number,
+    callback?: ProgressCallback
+): Promise<string> {
+    const { ethers } = await import('ethers');
+
+    const unvaultingAddress = getUnvaultingContractAddress(chainId);
+    const nftAddressToUse = nftAddress || remoteUnvaultSig._nftAddress;
+    const tokenId = parseBigIntValue(remoteUnvaultSig._tokenId);
+    const nonce = parseBigIntValue(remoteUnvaultSig._nonce);
+    const price = parseBigIntValue(remoteUnvaultSig._price);
+    const timestamp = parseBigIntValue(remoteUnvaultSig._timestamp);
+
+    const iface = new ethers.utils.Interface([
+        'function unvaultWithSignedPrice(address _nftAddress, uint256 _tokenId, uint256 _nonce, address _payment, uint256 _price, bytes _signature, uint256 _timestamp) payable'
+    ]);
+
+    const data = iface.encodeFunctionData('unvaultWithSignedPrice', [
+        nftAddressToUse,
+        tokenId,
+        nonce,
+        ZERO_ADDRESS,
+        price,
+        remoteUnvaultSig._signature,
+        timestamp,
+    ]);
+
+    const tx = await wallet.sendTransaction({
+        to: unvaultingAddress,
+        data,
+        value: price,
+    });
+
+    callback?.('Waiting for unvault confirmation...', { txHash: tx.hash });
+    await tx.wait();
+
+    return tx.hash;
+}
+
+async function requestClaimToken(
+    tokenId: string,
+    signature: string,
+    chainId: number
+): Promise<{ token: string }> {
+    const response = await fetch(`${TORUS_SIGNER_API}/sign`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            chainid: chainId.toString(),
+        },
+        body: JSON.stringify({ signature, tokenId }),
+    });
+
+    const jwt = await response.json();
+
+    if (!jwt || jwt.success === false) {
+        throw new Error(
+            jwt?.debug ? `Claim failed: ${JSON.stringify(jwt.debug)}` : 'Failed to get claim token'
+        );
+    }
+
+    return jwt;
+}