@lifestonelabs/tokensales 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+______________________________________________________________
+## [1.0.2] - 2026-01-30
+### Added
+- `listAvailableTickets` function to list available tickets for purchase from an active TokenSale
+- Support for `@electrum-cash/protocol` in addition to `@electrum-cash/network` for provider initialization
+
+### Changed
+- Updated README to clarify that library doesn't require `@electrum-cash/network` directly (only needed via CashScript)
+______________________________________________________________
+## [1.0.1] - 2026-01-29
+### Added
+- TokenSales cashscript contract for reference `src/artifacts/TokenSales.cash`
+______________________________________________________________
+## [1.0.0] - Initial Release
+### Added
+- `buyNFT` - Purchase a NFT from a TokenSale
+- `modifyTokenSale` - Modify TokenSale parameters (prices, endSale)
+- `burn` - Burn a TokenSale NFT and all associated NFTs
+- `addSatoshis` - Add satoshis to a minting NFT in users wallet
+- `createListing` - Create a new TokenSale listing
+- Utility functions: `parseTicketMasterCommitment`, `formatBCH`, `isTicketMaster`, `isTicket`
+- Contract address helpers: `getContractAddress`, `getTokenAddress`, `getContractAddresses`
+- WalletConnect signing helper: `createSignTransaction`

package/README.md

@@ -22,8 +22,9 @@ import {
   createSignTransaction,
   getContractAddresses 
 } from 'tokensales';
-import { Contract } from 'cashscript';
 import { ElectrumNetworkProvider } from '@electrum-cash/network';
+// OR use the high-level protocol package:
+// import { ElectrumNetworkProvider } from '@electrum-cash/protocol';
 import { SignClient } from '@walletconnect/sign-client';
 
 // Initialize provider
@@ -31,6 +32,9 @@ const provider = new ElectrumNetworkProvider('mainnet');
 
 // Note: The contract artifact is included in the library and compiled automatically
 // Functions return transaction objects that you can sign with your preferred method
+// 
+// The library accepts any ElectrumNetworkProvider instance compatible with CashScript.
+// You can use either @electrum-cash/network (low-level) or @electrum-cash/protocol (high-level).
 ```
 
 ### Purchase a Ticket
@@ -126,12 +130,27 @@ const wcTransactionObj = await createListing({
   priceType2: 2000n,
   priceType3: 0n,
   endSale: 950000,
-  adminPubKeyHash: '0000000000000000000000000000000000000000' // 40 hex chars = 20bytes
+  adminPubKeyHash: '0000000000000000000000000000000000000000' // TokenSale creator/owners pubkeyhash. Sales revenue and admin capabilities (e.g. modify, burn) are controlled by this address. 40 hex chars = 20bytes
 });
 
 // Sign and broadcast transaction (see buyNFT example above)
 ```
 
+### List Available Tickets
+
+```typescript
+import { listAvailableTickets } from 'tokensales';
+
+const availableTickets = await listAvailableTickets({
+  electrumProvider: provider,
+  categoryID: 'your-token-category-id' // Hex string of the token category
+});
+
+// Returns array of ticket UTXOs that are available for purchase
+// Throws error if no active TokenSale found or sale has ended
+console.log(`Found ${availableTickets.length} available tickets`);
+```
+
 ## API Reference
 
 ### Functions
@@ -141,13 +160,12 @@ const wcTransactionObj = await createListing({
 Purchase a ticket NFT from a TokenSale.
 
 **Parameters:**
-- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
 - `usersAddress: string` - User's Bitcoin Cash address
 - `ticketMasterUtxo: Utxo` - TokenSale UTXO
 - `ticketUtxo: Utxo` - Ticket UTXO to purchase
 - `ticketType: '01' | '02' | '03'` - Ticket type
 - `isAdmin: boolean` - Whether user is admin (uses minting NFT)
-- `contractAddress?: string` - Optional contract address override (defaults to v4)
 
 **Returns:** `Promise<WalletConnectTransactionObject>` - Transaction object ready for signing
 
@@ -156,7 +174,7 @@ Purchase a ticket NFT from a TokenSale.
 Modify TokenSale parameters (prices, endSale).
 
 **Parameters:**
-- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
 - `usersAddress: string` - User's Bitcoin Cash address
 - `tokenSaleUtxo: Utxo` - TokenSale UTXO to modify
 - `userMintingUtxo: Utxo` - User's minting NFT
@@ -164,7 +182,6 @@ Modify TokenSale parameters (prices, endSale).
 - `priceType2: number | bigint` - Price for type 2 tickets
 - `priceType3: number | bigint` - Price for type 3 tickets
 - `endSale: number` - Block height when sale ends
-- `contractAddress?: string` - Optional contract address override (defaults to v4)
 
 **Returns:** `Promise<WalletConnectTransactionObject>` - Transaction object ready for signing
 
@@ -173,12 +190,11 @@ Modify TokenSale parameters (prices, endSale).
 Burn a TokenSale NFT and all associated tickets.
 
 **Parameters:**
-- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
 - `usersAddress: string` - User's Bitcoin Cash address
 - `ticketMasterUtxo: Utxo` - TokenSale UTXO to burn (note: parameter name kept for backward compatibility)
 - `userMintingNFT: Utxo` - User's minting NFT
 - `tickets: Utxo[]` - Array of ticket UTXOs to burn
-- `contractAddress?: string` - Optional contract address override (defaults to v4)
 
 **Returns:** `Promise<WalletConnectTransactionObject>` - Transaction object ready for signing
 
@@ -187,7 +203,7 @@ Burn a TokenSale NFT and all associated tickets.
 Add satoshis to a minting NFT.
 
 **Parameters:**
-- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
 - `usersAddress: string` - User's Bitcoin Cash address
 - `userMintingNFT: Utxo` - Minting NFT to add satoshis to
 - `additionalSatoshis: bigint` - Amount of satoshis to add
@@ -199,7 +215,7 @@ Add satoshis to a minting NFT.
 Create a new TokenSale listing.
 
 **Parameters:**
-- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
 - `usersAddress: string` - User's Bitcoin Cash address
 - `userMintingNFT: Utxo` - User's minting NFT
 - `priceType1: bigint` - Price for type 1 tickets
@@ -207,11 +223,24 @@ Create a new TokenSale listing.
 - `priceType3: bigint` - Price for type 3 tickets
 - `endSale: number` - Block height when sale ends
 - `adminPubKeyHash: string` - Admin public key hash (40 hex chars)
-- `contractAddress?: string` - Optional contract address override (defaults to v4)
-- `tokenAddress?: string` - Optional token address override (defaults to v4)
 
 **Returns:** `Promise<WalletConnectTransactionObject>` - Transaction object ready for signing
 
+#### `listAvailableTickets(params: ListAvailableTicketsParams): Promise<Utxo[]>`
+
+List available tickets for purchase from an active TokenSale.
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance (from `@electrum-cash/network` or `@electrum-cash/protocol`)
+- `categoryID: string` - Token category ID (hex string) to filter tickets
+
+**Returns:** `Promise<Utxo[]>` - Array of ticket UTXOs available for purchase
+
+**Throws:**
+- Error if no TokenSale found for the category
+- Error if TokenSale has ended (current block height >= endSale block)
+- Error if TokenSale commitment cannot be parsed
+
 ### Utilities
 
 #### `compileContract(provider: ElectrumNetworkProvider, addressType?: 'p2sh32' | 'p2sh20'): Contract`

package/dist/functions/listAvailableTickets.d.ts

@@ -0,0 +1,10 @@
+import { Utxo } from 'cashscript';
+import { ListAvailableTicketsParams } from '../types';
+/**
+ * List available tickets for purchase from a TokenSale
+ * @param params - ListAvailableTicketsParams object containing all required parameters
+ * @returns Promise resolving to array of ticket UTXOs that are available for purchase
+ * @throws Error if validation fails or TokenSale is not found/active
+ */
+export declare function listAvailableTickets(params: ListAvailableTicketsParams): Promise<Utxo[]>;
+//# sourceMappingURL=listAvailableTickets.d.ts.map

package/dist/functions/listAvailableTickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listAvailableTickets.d.ts","sourceRoot":"","sources":["../../src/functions/listAvailableTickets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAA2B,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAC;AAItD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAqE9F"}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { modifyTokenSale } from './functions/modifyTokenSale';
 export { burn } from './functions/burn';
 export { addSatoshis } from './functions/addSatoshis';
 export { createListing } from './functions/createListing';
+export { listAvailableTickets } from './functions/listAvailableTickets';
 export { parseTicketMasterCommitment, formatBCH, isTicketMaster, isTicket } from './utils/ticketMaster';
 export { default as toTokenAddress } from './utils/toTokenAddress';
 export { ensureAddressPrefix, hexToUint8Array, toLittleEndianHexString } from './utils';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,2BAA2B,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGjH,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAGxE,OAAO,EAAE,2BAA2B,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGjH,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.esm.js

@@ -1453,5 +1453,61 @@ function getContractAddresses() {
     };
 }
 
-export { AddressTicketMaster, AddressTicketMasterToken, DEFAULT_CONTRACT_ADDRESSES, TICKET_LEVEL_DESCRIPTIONS, addSatoshis, burn, buyNFT, createListing, createSignTransaction, ensureAddressPrefix, formatBCH, getContractAddress, getContractAddresses, getTokenAddress, hexToUint8Array, isTicket, isTicketMaster, modifyTokenSale, parseTicketMasterCommitment, toLittleEndianHexString, toTokenAddress };
+/**
+ * List available tickets for purchase from a TokenSale
+ * @param params - ListAvailableTicketsParams object containing all required parameters
+ * @returns Promise resolving to array of ticket UTXOs that are available for purchase
+ * @throws Error if validation fails or TokenSale is not found/active
+ */
+async function listAvailableTickets(params) {
+    const { electrumProvider, categoryID } = params;
+    if (!electrumProvider) {
+        throw new Error('Electrum provider not available');
+    }
+    if (!categoryID || categoryID.length === 0) {
+        throw new Error('Category ID is required');
+    }
+    // Get the contract token address
+    const contractTokenAddress = getTokenAddress();
+    // Get all UTXOs from the contract token address
+    const contractUtxos = await electrumProvider.getUtxos(contractTokenAddress);
+    // Filter UTXOs to only those matching the categoryID
+    const categoryUtxos = contractUtxos.filter((utxo) => utxo?.token?.category === categoryID);
+    if (categoryUtxos.length === 0) {
+        return []; // No UTXOs found for this category
+    }
+    // Find the TokenSale minting NFT (capability === 'minting')
+    const tokenSaleUtxo = categoryUtxos.find((utxo) => isTicketMaster(utxo));
+    if (!tokenSaleUtxo) {
+        throw new Error(`No active TokenSale found for category ${categoryID}`);
+    }
+    // Parse the TokenSale commitment to get endSale block height
+    const commitment = tokenSaleUtxo.token?.nft?.commitment || '';
+    const tokenSaleData = parseTicketMasterCommitment(commitment);
+    if (!tokenSaleData) {
+        throw new Error('Failed to parse TokenSale commitment');
+    }
+    // Get current block height
+    // ElectrumNetworkProvider may expose getBlockHeight directly, or we need to use performRequest
+    let currentBlockHeight;
+    if (typeof electrumProvider.getBlockHeight === 'function') {
+        currentBlockHeight = await electrumProvider.getBlockHeight();
+    }
+    else if (typeof electrumProvider.performRequest === 'function') {
+        const header = await electrumProvider.performRequest('blockchain.headers.subscribe');
+        currentBlockHeight = header?.height || header;
+    }
+    else {
+        throw new Error('Unable to get block height from provider');
+    }
+    // Check if sale is active (currentBlockHeight < endSale)
+    if (currentBlockHeight >= tokenSaleData.endSale) {
+        throw new Error(`TokenSale has ended. Current block: ${currentBlockHeight}, End sale block: ${tokenSaleData.endSale}`);
+    }
+    // Filter to only ticket UTXOs (capability === 'none')
+    const availableTickets = categoryUtxos.filter((utxo) => isTicket(utxo, categoryID));
+    return availableTickets;
+}
+
+export { AddressTicketMaster, AddressTicketMasterToken, DEFAULT_CONTRACT_ADDRESSES, TICKET_LEVEL_DESCRIPTIONS, addSatoshis, burn, buyNFT, createListing, createSignTransaction, ensureAddressPrefix, formatBCH, getContractAddress, getContractAddresses, getTokenAddress, hexToUint8Array, isTicket, isTicketMaster, listAvailableTickets, modifyTokenSale, parseTicketMasterCommitment, toLittleEndianHexString, toTokenAddress };
 //# sourceMappingURL=index.esm.js.map