@lifestonelabs/tokensales 1.0.0

package/README.md

@@ -0,0 +1,285 @@
+# TokenSales Library
+
+A TypeScript library for interacting with TokenSales contracts on Bitcoin Cash. This library provides a clean, framework-agnostic API for building and signing transactions that interact with TokenSales smart contracts.
+
+## Installation
+
+```bash
+npm install tokensales
+```
+
+## Signing Transactions
+
+This library returns transaction objects with empty user input signatures. You can use WalletConnect, or any other signing method you prefer. The library includes an optional `createSignTransaction` helper for WalletConnect, but you're free to use your own signing implementation.
+
+## Usage
+
+### Setup
+
+```typescript
+import { 
+  buyNFT, 
+  createSignTransaction,
+  getContractAddresses 
+} from 'tokensales';
+import { Contract } from 'cashscript';
+import { ElectrumNetworkProvider } from '@electrum-cash/network';
+import { SignClient } from '@walletconnect/sign-client';
+
+// Initialize provider
+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
+```
+
+### Purchase a Ticket
+
+```typescript
+import { buyNFT } from 'tokensales';
+
+const wcTransactionObj = await buyNFT({
+  electrumProvider: provider,
+  usersAddress: 'bitcoincash:...',
+  ticketMasterUtxo: tokenSaleUtxo, // TokenSale UTXO
+  ticketUtxo: ticketUtxo,
+  ticketType: '01', // '01', '02', or '03'
+  isAdmin: false
+});
+
+// Sign the transaction with your preferred method (WalletConnect, etc.)
+// Example with WalletConnect:
+// const signClient = await SignClient.init({ ... });
+// const result = await signClient.request({
+//   chainId: 'bch:mainnet',
+//   topic: session.topic,
+//   request: {
+//     method: 'bch_signTransaction',
+//     params: JSON.parse(stringify(wcTransactionObj))
+//   }
+// });
+
+// Broadcast transaction
+// await provider.sendRawTransaction(result.signedTransaction);
+```
+
+### Modify TokenSale
+
+```typescript
+import { modifyTokenSale } from 'tokensales';
+
+const wcTransactionObj = await modifyTokenSale({
+  electrumProvider: provider,
+  usersAddress: 'bitcoincash:...',
+  tokenSaleUtxo: tokenSaleUtxo,
+  userMintingUtxo: userMintingUtxo,
+  priceType1: 1000n,
+  priceType2: 2000n,
+  priceType3: 0n,
+  endSale: 950000
+});
+
+// Sign and broadcast transaction (see buyNFT example above)
+```
+
+### Burn TokenSale and Tickets
+
+```typescript
+import { burn } from 'tokensales';
+
+const wcTransactionObj = await burn({
+  electrumProvider: provider,
+  usersAddress: 'bitcoincash:...',
+  ticketMasterUtxo: tokenSaleUtxo, // TokenSale UTXO
+  userMintingNFT: userMintingNFT,
+  tickets: ticketsArray // Array of ticket UTXOs to burn
+});
+
+// Sign and broadcast transaction (see buyNFT example above)
+```
+
+### Add Satoshis to Minting NFT
+
+```typescript
+import { addSatoshis } from 'tokensales';
+
+const wcTransactionObj = await addSatoshis({
+  electrumProvider: provider,
+  usersAddress: 'bitcoincash:...',
+  userMintingNFT: userMintingNFT,
+  additionalSatoshis: 10000n
+});
+
+// Sign and broadcast transaction (see buyNFT example above)
+```
+
+### Create TokenSale Listing
+
+```typescript
+import { createListing } from 'tokensales';
+
+const wcTransactionObj = await createListing({
+  electrumProvider: provider,
+  usersAddress: 'bitcoincash:...',
+  userMintingNFT: userMintingNFT,
+  priceType1: 1000n,
+  priceType2: 2000n,
+  priceType3: 0n,
+  endSale: 950000,
+  adminPubKeyHash: '0000000000000000000000000000000000000000' // 40 hex chars = 20bytes
+});
+
+// Sign and broadcast transaction (see buyNFT example above)
+```
+
+## API Reference
+
+### Functions
+
+#### `buyNFT(params: BuyNFTParams): Promise<WalletConnectTransactionObject>`
+
+Purchase a ticket NFT from a TokenSale.
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `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
+
+#### `modifyTokenSale(params: ModifyTokenSaleParams): Promise<WalletConnectTransactionObject>`
+
+Modify TokenSale parameters (prices, endSale).
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `usersAddress: string` - User's Bitcoin Cash address
+- `tokenSaleUtxo: Utxo` - TokenSale UTXO to modify
+- `userMintingUtxo: Utxo` - User's minting NFT
+- `priceType1: number | bigint` - Price for type 1 tickets
+- `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
+
+#### `burn(params: BurnParams): Promise<WalletConnectTransactionObject>`
+
+Burn a TokenSale NFT and all associated tickets.
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `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
+
+#### `addSatoshis(params: AddSatoshisParams): Promise<WalletConnectTransactionObject>`
+
+Add satoshis to a minting NFT.
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `usersAddress: string` - User's Bitcoin Cash address
+- `userMintingNFT: Utxo` - Minting NFT to add satoshis to
+- `additionalSatoshis: bigint` - Amount of satoshis to add
+
+**Returns:** `Promise<WalletConnectTransactionObject>` - Transaction object ready for signing
+
+#### `createListing(params: CreateListingParams): Promise<WalletConnectTransactionObject>`
+
+Create a new TokenSale listing.
+
+**Parameters:**
+- `electrumProvider: ElectrumNetworkProvider` - Electrum provider instance
+- `usersAddress: string` - User's Bitcoin Cash address
+- `userMintingNFT: Utxo` - User's minting NFT
+- `priceType1: bigint` - Price for type 1 tickets
+- `priceType2: bigint` - Price for type 2 tickets
+- `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
+
+### Utilities
+
+#### `compileContract(provider: ElectrumNetworkProvider, addressType?: 'p2sh32' | 'p2sh20'): Contract`
+
+Compiles the TokenSales contract using the included artifact. This is called automatically by the transaction functions, but can be used directly if needed.
+
+#### `createSignTransaction(signClient: any, connectedChain?: string): SignTransactionFunction`
+
+**Optional helper** - Creates a WalletConnect-compatible sign transaction function. This is provided as a convenience, but you can use any signing method you prefer.
+
+#### `parseTicketMasterCommitment(commitment: string): TicketMasterData | null`
+
+Parses a TokenSale commitment string to extract sale data.
+
+#### `formatBCH(satoshis: bigint | number | string): string`
+
+Formats satoshis to BCH string with 8 decimal places.
+
+#### `toTokenAddress(address: string): string`
+
+Converts a regular Bitcoin Cash address to its token address equivalent.
+
+### Contract Addresses
+
+#### `getContractAddress(): string`
+
+Gets the TokenSales contract address.
+
+#### `getTokenAddress(): string`
+
+Gets the TokenSales token address.
+
+#### `getContractAddresses(): { contract: string; token: string }`
+
+Gets both contract and token addresses.
+
+#### `AddressTicketMaster: string`
+
+Direct export of the TokenSales contract address.
+
+#### `AddressTicketMasterToken: string`
+
+Direct export of the TokenSales token address.
+
+## Error Handling
+
+All functions throw errors instead of using callbacks. Make sure to wrap function calls in try-catch blocks:
+
+```typescript
+try {
+  const wcTransactionObj = await buyNFT(params);
+  // Sign transaction with your preferred method
+  // Then broadcast: await provider.sendRawTransaction(signedTx);
+} catch (error) {
+  console.error('Transaction building failed:', error);
+  // Handle error appropriately
+}
+```
+
+## TypeScript Support
+
+This library is written in TypeScript and includes full type definitions. All types are exported and can be imported:
+
+```typescript
+import type { BuyNFTParams, WalletConnectTransactionObject } from 'tokensales';
+```
+
+## License
+
+MIT
+

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+export declare const DEFAULT_CONTRACT_ADDRESSES: {
+    readonly contract: "bitcoincash:pvh0yat7d2r9nf228fpns3mypydvstq9arftt9qlmma42xeq2eryszkdd99zq";
+    readonly token: "bitcoincash:rvh0yat7d2r9nf228fpns3mypydvstq9arftt9qlmma42xeq2eryss93vuymt";
+};
+/**
+ * Get contract address
+ * @returns Contract address
+ */
+export declare function getContractAddress(): string;
+/**
+ * Get token address
+ * @returns Token address
+ */
+export declare function getTokenAddress(): string;
+/**
+ * Get contract addresses
+ * @returns Object with contract and token addresses
+ */
+export declare function getContractAddresses(): {
+    contract: string;
+    token: string;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB;;;EAKnC"}

package/dist/constants/values.d.ts

@@ -0,0 +1,17 @@
+export declare const AddressTicketMaster = "bitcoincash:pvh0yat7d2r9nf228fpns3mypydvstq9arftt9qlmma42xeq2eryszkdd99zq";
+export declare const AddressTicketMasterToken = "bitcoincash:rvh0yat7d2r9nf228fpns3mypydvstq9arftt9qlmma42xeq2eryss93vuymt";
+export declare const TICKET_LEVEL_DESCRIPTIONS: {
+    '01': {
+        name: string;
+        description: string;
+    };
+    '02': {
+        name: string;
+        description: string;
+    };
+    '03': {
+        name: string;
+        description: string;
+    };
+};
+//# sourceMappingURL=values.d.ts.map

package/dist/constants/values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../../src/constants/values.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,mBAAmB,8EAA8E,CAAC;AAC/G,eAAO,MAAM,wBAAwB,8EAA8E,CAAC;AAGpH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;CAarC,CAAC"}

package/dist/functions/addSatoshis.d.ts

@@ -0,0 +1,9 @@
+import { AddSatoshisParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Add satoshis to a minting NFT
+ * @param params - AddSatoshisParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function addSatoshis(params: AddSatoshisParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=addSatoshis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"addSatoshis.d.ts","sourceRoot":"","sources":["../../src/functions/addSatoshis.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAG7E;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAyJpG"}

package/dist/functions/burn.d.ts

@@ -0,0 +1,9 @@
+import { BurnParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Burn a TicketMaster NFT and all associated tickets
+ * @param params - BurnParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function burn(params: BurnParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=burn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"burn.d.ts","sourceRoot":"","sources":["../../src/functions/burn.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAItE;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAkLtF"}

package/dist/functions/buyNFT.d.ts

@@ -0,0 +1,9 @@
+import { BuyNFTParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Purchase a ticket NFT from a TicketMaster
+ * @param params - BuyNFTParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function buyNFT(params: BuyNFTParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=buyNFT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buyNFT.d.ts","sourceRoot":"","sources":["../../src/functions/buyNFT.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAIxE;;;;;GAKG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAoT1F"}

package/dist/functions/createListing.d.ts

@@ -0,0 +1,9 @@
+import { CreateListingParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Create a new TicketMaster listing
+ * @param params - CreateListingParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function createListing(params: CreateListingParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=createListing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createListing.d.ts","sourceRoot":"","sources":["../../src/functions/createListing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAK/E;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,8BAA8B,CAAC,CA0JxG"}

package/dist/functions/modifyTicketMaster.d.ts

@@ -0,0 +1,9 @@
+import { ModifyTicketMasterParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Modify TicketMaster parameters (prices, endSale)
+ * @param params - ModifyTicketMasterParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function modifyTicketMaster(params: ModifyTicketMasterParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=modifyTicketMaster.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modifyTicketMaster.d.ts","sourceRoot":"","sources":["../../src/functions/modifyTicketMaster.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAIpF;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAkLlH"}

package/dist/functions/modifyTokenSale.d.ts

@@ -0,0 +1,9 @@
+import { ModifyTokenSaleParams, WalletConnectTransactionObject } from '../types';
+/**
+ * Modify TokenSale parameters (prices, endSale)
+ * @param params - ModifyTokenSaleParams object containing all required parameters
+ * @returns Promise resolving to WalletConnectTransactionObject ready for signing
+ * @throws Error if validation fails or transaction building fails
+ */
+export declare function modifyTokenSale(params: ModifyTokenSaleParams): Promise<WalletConnectTransactionObject>;
+//# sourceMappingURL=modifyTokenSale.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"modifyTokenSale.d.ts","sourceRoot":"","sources":["../../src/functions/modifyTokenSale.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,UAAU,CAAC;AAIjF;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAkL5G"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TokenSales Library
+ * A TypeScript library for interacting with TokenSales contracts on Bitcoin Cash
+ */
+export { buyNFT } from './functions/buyNFT';
+export { modifyTokenSale } from './functions/modifyTokenSale';
+export { burn } from './functions/burn';
+export { addSatoshis } from './functions/addSatoshis';
+export { createListing } from './functions/createListing';
+export { parseTicketMasterCommitment, formatBCH, isTicketMaster, isTicket } from './utils/ticketMaster';
+export { default as toTokenAddress } from './utils/toTokenAddress';
+export { ensureAddressPrefix, hexToUint8Array, toLittleEndianHexString } from './utils';
+export { createSignTransaction } from './utils/signTransaction';
+export * from './types';
+export { DEFAULT_CONTRACT_ADDRESSES, getContractAddresses, getContractAddress, getTokenAddress } from './config';
+export { AddressTicketMaster, AddressTicketMasterToken, TICKET_LEVEL_DESCRIPTIONS } from './constants/values';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}