add new example scripts to 'transactions'

dominant-strategies · Feb 4, 2025 · 7303c2c · 7303c2c
1 parent 3770ccf
commit 7303c2c
Show file tree

Hide file tree

Showing 6 changed files with 416 additions and 113 deletions.
diff --git a/examples/transactions/qihdwallet-aggregate.js b/examples/transactions/qihdwallet-aggregate.js
@@ -0,0 +1,99 @@
+const {
+	JsonRpcProvider,
+	Mnemonic,
+	QiHDWallet,
+	Zone,
+} = require('../../lib/commonjs/quais');
+require('dotenv').config();
+
+/**
+ * Qi HD Wallet UTXO Aggregation Example
+ * 
+ * This script demonstrates how to aggregate multiple UTXOs into larger denominations
+ * in a QiHDWallet. It implements QIP-7 specifications for UTXO management and 
+ * optimization of wallet holdings.
+ * 
+ * The script demonstrates:
+ * 1. Creating and connecting a QiHDWallet to a provider
+ * 2. Scanning the wallet for available UTXOs in a specific zone
+ * 3. Displaying wallet addresses and current UTXO distribution
+ * 4. Attempting to aggregate smaller denomination UTXOs into larger ones
+ * 5. Verifying the aggregation results
+ * 
+ * Usage:
+ * First, set up your .env file with:
+ * MNEMONIC="your twelve word mnemonic phrase here"
+ * RPC_URL="your Quai node RPC endpoint"
+ * 
+ * Then run:
+ * ```
+ * node qihdwallet-aggregate.js
+ * ```
+ * 
+ * The script will output:
+ * - Wallet addresses (both external and change)
+ * - Initial balance and UTXO distribution
+ * - Aggregation transaction details
+ * - Final balance and updated UTXO distribution
+ * 
+ * Note: This example uses the Cyprus1 zone for demonstration. The aggregation
+ * process follows QIP-7 specifications for UTXO management, attempting to combine
+ * smaller denominations into larger ones when possible. The transaction will fail
+ * if no beneficial aggregation is possible with the current UTXO set.
+ */
+
+async function main() {
+    // Create provider
+	const options =  {usePathing: false};
+    const provider = new JsonRpcProvider(process.env.RPC_URL, undefined, options);
+
+    // Create wallet and connect to provider
+    console.log(process.env.RPC_URL)
+    const aliceMnemonic = Mnemonic.fromPhrase(process.env.MNEMONIC);
+    const aliceWallet = QiHDWallet.fromMnemonic(aliceMnemonic);
+    aliceWallet.connect(provider);
+
+	// Scan Alice wallet
+	console.log("...scanning alice wallet");
+	await aliceWallet.scan(Zone.Cyprus1);
+
+	// log alice change wallet addresses
+	console.log("Alice change wallet addresses: ", aliceWallet.getChangeAddressesForZone(Zone.Cyprus1).map(a => a.address));
+	// log alice external wallet addresses
+	console.log("Alice external wallet addresses: ", aliceWallet.getAddressesForZone(Zone.Cyprus1).map(a => a.address));
+
+	// Get Alice initial balance
+	console.log("...getting alice initial balance");
+	const aliceInitialBalance = await aliceWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Alice initial balance: ", aliceInitialBalance);
+
+	// log Alice outpoints
+	console.log("Alice outpoints: ", JSON.stringify(aliceWallet.getOutpoints(Zone.Cyprus1), null, 2));
+
+	// Send Qi
+	console.log("...aggregating alice balance");
+	const tx = await aliceWallet.aggregate(Zone.Cyprus1);
+	console.log("... Alice transaction sent. Waiting for receipt...");
+
+	// Wait for tx to be mined
+	const txReceipt = await tx.wait();
+	console.log("Alice's transaction receipt (block number): ", txReceipt.blockNumber);
+
+	// Get Alice final balance
+	console.log("...getting alice final balance");
+	const aliceFinalBalance = await aliceWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Alice final balance: ", aliceFinalBalance);
+
+	// sync Alice wallet and log outpoints
+	console.log("...syncing alice wallet and logging outpoints");
+	await aliceWallet.scan(Zone.Cyprus1);
+	console.log("Alice outpoints: ", JSON.stringify(aliceWallet.getOutpoints(Zone.Cyprus1), null, 2));
+
+}
+
+main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
diff --git a/examples/transactions/qihdwallet-convert-to-quai.js b/examples/transactions/qihdwallet-convert-to-quai.js
@@ -0,0 +1,102 @@
+const {
+	JsonRpcProvider,
+	Mnemonic,
+	QiHDWallet,
+	QuaiHDWallet,
+	Zone,
+} = require('../../lib/commonjs/quais');
+require('dotenv').config();
+
+/**
+ * Qi to Quai Conversion Example
+ * 
+ * This script demonstrates how to convert Qi (UTXO-based) tokens to Quai (EVM-based) tokens
+ * using QiHDWallet. It implements QIP-7 specifications for UTXO management and cross-ledger
+ * conversion between Qi and Quai ledgers.
+ * 
+ * The script demonstrates:
+ * 1. Creating both Qi and Quai HD wallets from the same mnemonic
+ * 2. Scanning the Qi wallet for available UTXOs in a specific zone
+ * 3. Displaying wallet addresses and current UTXO distribution
+ * 4. Converting a specified amount of Qi tokens to Quai tokens
+ * 5. Verifying the conversion results in both ledgers
+ * 
+ * Usage:
+ * First, set up your .env file with:
+ * MNEMONIC="your twelve word mnemonic phrase here"
+ * RPC_URL="your Quai node RPC endpoint"
+ * 
+ * Then run:
+ * ```
+ * node qihdwallet-convert-to-quai.js
+ * ```
+ * 
+ * The script will output:
+ * - Qi and Quai wallet addresses
+ * - Initial Qi balance and UTXO distribution
+ * - Conversion transaction details
+ * - Final Quai balance after conversion
+ * 
+ * Note: This example uses the Cyprus1 zone for demonstration. The conversion
+ * process follows QIP-7 specifications for cross-ledger operations, allowing
+ * users to move value between Qi (UTXO) and Quai (EVM) ledgers within the
+ * same zone. The transaction will fail if insufficient UTXOs are available
+ * for the requested conversion amount.
+ */
+
+async function main() {
+    // Create provider
+	const options =  {usePathing: false};
+    const provider = new JsonRpcProvider(process.env.RPC_URL, undefined, options);
+
+    // Create wallet and connect to provider
+    console.log(process.env.RPC_URL)
+    const aliceMnemonic =Mnemonic.fromPhrase(process.env.MNEMONIC);
+    const aliceQiWallet =QiHDWallet.fromMnemonic(aliceMnemonic);
+    aliceQiWallet.connect(provider);
+
+	const aliceQuaiWallet =QuaiHDWallet.fromMnemonic(aliceMnemonic);
+	aliceQuaiWallet.connect(provider);
+	// get alice quai address
+	const aliceQuaiAddressInfo = aliceQuaiWallet.getNextAddressSync(0,Zone.Cyprus1);
+	console.log("Alice Quai address: ", aliceQuaiAddressInfo.address);
+
+	// Scan Alice wallet
+	console.log("...scanning alice wallet");
+	await aliceQiWallet.scan(Zone.Cyprus1);
+
+	// log alice change wallet addresses
+	console.log("Alice change wallet addresses: ", aliceQiWallet.getChangeAddressesForZone(Zone.Cyprus1).map(a => a.address));
+	// log alice external wallet addresses
+	console.log("Alice external wallet addresses: ", aliceQiWallet.getAddressesForZone(Zone.Cyprus1).map(a => a.address));
+
+	// Get Alice initial balance
+	console.log("...getting alice initial balance");
+	const aliceInitialQiBalance = await aliceQiWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Alice initial Qi balance: ", aliceInitialQiBalance);
+
+	// log Alice outpoints
+	console.log("Alice outpoints: ", JSON.stringify(aliceQiWallet.getOutpoints(Zone.Cyprus1), null, 2));
+
+	const amountToConvert = 100000;
+	console.log(`...converting ${amountToConvert} Qi to Quai address ${aliceQuaiAddressInfo.address}`);
+
+	const tx = await aliceQiWallet.convertToQuai(aliceQuaiAddressInfo.address, amountToConvert);
+	console.log("... Alice transaction sent. Waiting for receipt...");
+
+	// Wait for tx to be mined
+	const txReceipt = await tx.wait();
+	console.log("Alice's transaction receipt (block number): ", txReceipt.blockNumber);
+
+	// Get Alice updated Quai balance
+	const aliceUpdatedQuaiBalance = await provider.getBalance(aliceQuaiAddressInfo.address);
+	console.log("Alice updated Quai balance: ", aliceUpdatedQuaiBalance);
+
+}
+
+main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
diff --git a/examples/transactions/qihdwallet-sendTransaction.js b/examples/transactions/qihdwallet-sendTransaction.js
@@ -0,0 +1,124 @@
+const {
+	JsonRpcProvider,
+	Mnemonic,
+	QiHDWallet,
+	Zone,
+} = require('../../lib/commonjs/quais');
+require('dotenv').config();
+
+/**
+ * Qi HD Wallet Transaction Example
+ * 
+ * This script demonstrates how to perform UTXO-based transactions using QiHDWallet
+ * between two parties (Alice and Bob) on the Quai network. It implements BIP-0047
+ * payment codes for secure address generation and QIP-7 for UTXO transactions.
+ * 
+ * The script demonstrates:
+ * 1. Creating QiHDWallets for both sender (Alice) and receiver (Bob)
+ * 2. Generating and exchanging payment codes between parties
+ * 3. Opening payment channels using BIP-0047
+ * 4. Scanning wallets for available UTXOs
+ * 5. Sending Qi tokens from Alice to Bob using payment codes
+ * 
+ * Usage:
+ * First, set up your .env file with:
+ * MNEMONIC="sender's twelve word mnemonic phrase here"
+ * RPC_URL="your Quai node RPC endpoint"
+ * 
+ * Then run:
+ * ```
+ * node qihdwallet-sendTransaction.js
+ * ```
+ * 
+ * The script will output:
+ * - Payment codes for both Alice and Bob
+ * - Wallet addresses for both parties
+ * - Initial balances
+ * - Transaction details and confirmation
+ * 
+ * Note: This example uses the Cyprus1 zone for demonstration. The QiHDWallet
+ * implements UTXO-based transactions as specified in QIP-7, with privacy features
+ * from BIP-0047 payment codes.
+ */
+
+async function main() {
+    // Create provider
+	const options =  {usePathing: false};
+    const provider = new JsonRpcProvider(process.env.RPC_URL, undefined, options);
+
+    // Create wallet and connect to provider
+    console.log(process.env.RPC_URL)
+    const aliceMnemonic = Mnemonic.fromPhrase(process.env.MNEMONIC);
+    const aliceWallet = QiHDWallet.fromMnemonic(aliceMnemonic);
+    aliceWallet.connect(provider);
+
+    // Get Alice payment code
+    const alicePaymentCode = aliceWallet.getPaymentCode(0);
+    console.log("Alice payment code: ", alicePaymentCode);
+
+	// Create Bob wallet
+	const BOB_MNEMONIC = "innocent perfect bus miss prevent night oval position aspect nut angle usage expose grace juice";
+	const bobMnemonic = Mnemonic.fromPhrase(BOB_MNEMONIC);
+    const bobWallet = QiHDWallet.fromMnemonic(bobMnemonic);
+    bobWallet.connect(provider);
+
+	// Get Bob payment code
+	const bobPaymentCode = bobWallet.getPaymentCode(0);
+	console.log("Bob payment code: ", bobPaymentCode);
+
+	// Open channel
+	aliceWallet.openChannel(bobPaymentCode);
+	bobWallet.openChannel(alicePaymentCode);
+
+	// Scan Alice wallet
+	console.log("...scanning alice wallet");
+	await aliceWallet.scan(Zone.Cyprus1);
+
+	// log alice change wallet addresses
+	console.log("Alice change wallet addresses: ", aliceWallet.getChangeAddressesForZone(Zone.Cyprus1).map(a => a.address));
+	// log alice external wallet addresses
+	console.log("Alice external wallet addresses: ", aliceWallet.getAddressesForZone(Zone.Cyprus1).map(a => a.address));
+
+	// // Scan Bob wallet
+	console.log("...scanning bob wallet");
+	await bobWallet.scan(Zone.Cyprus1);
+
+	// Get Alice initial balance
+	console.log("...getting alice initial balance");
+	const aliceInitialBalance = await aliceWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Alice initial balance: ", aliceInitialBalance);
+
+	// Get Bob initial balance
+	console.log("...getting bob initial balance");
+	const bobInitialBalance = await bobWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Bob initial balance: ", bobInitialBalance);
+
+	// log Alice outpoints
+	console.log("Alice outpoints: ", JSON.stringify(aliceWallet.getOutpoints(Zone.Cyprus1), null, 2));
+
+	// Send Qi
+	const amountToSendToBob = 15000000;
+	console.log(`...sending ${amountToSendToBob} qit to Bob`);
+	const tx = await aliceWallet.sendTransaction(bobPaymentCode, amountToSendToBob, Zone.Cyprus1, Zone.Cyprus1);
+	console.log("... Alice transaction sent. Waiting for receipt...");
+
+	// Wait for tx to be mined
+	const txReceipt = await tx.wait();
+	console.log("Alice's transaction receipt received. Block number: ", txReceipt.blockNumber);
+
+	// Scan Bob wallet
+	console.log("...scanning bob wallet");
+	await bobWallet.scan(Zone.Cyprus1);
+
+	// Get Bob final balance
+	console.log("...getting bob final balance");
+	const bobFinalBalance = await bobWallet.getBalanceForZone(Zone.Cyprus1);
+	console.log("Bob final balance: ", bobFinalBalance);
+}
+
+main()
+    .then(() => process.exit(0))
+    .catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });