@bsv/sdk 1.6.9 → 1.6.11

package/docs/tutorials/first-transaction-low-level.md

@@ -0,0 +1,204 @@
+# Your First BSV Transaction (Low level)
+
+**Duration**: 15 minutes  
+**Prerequisites**: Node.js, basic TypeScript knowledge  
+
+## Learning Goals
+- Install and configure the BSV TypeScript SDK
+- Create a simple P2PKH transaction
+- Understand BSV transaction anatomy
+
+## Introduction
+
+In this tutorial, you'll learn how to create your first Bitcoin SV transaction using the TypeScript SDK. By the end, you'll understand the basic components of a BSV transaction and how to construct, sign, and broadcast one.
+
+## Step 1: Setting Up Your Environment
+
+First, create a new Node.js project and install the BSV SDK:
+
+```bash
+# Create a new directory for your project
+mkdir my-first-bsv-tx
+cd my-first-bsv-tx
+
+# Initialize a new Node.js project
+npm init -y
+
+# Install TypeScript and ts-node (TypeScript execution engine)
+npm install typescript ts-node @types/node --save-dev
+# ts-node allows you to run TypeScript files directly without compiling them first
+
+# Install the BSV SDK
+npm install @bsv/sdk
+```
+
+Create a basic TypeScript configuration file (`tsconfig.json`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "./dist"
+  }
+}
+```
+
+## Step 2: Understanding Transaction Components
+
+Before we write any code, let's understand the basic components of a Bitcoin transaction:
+
+- **Inputs**: References to previous transaction outputs that you're spending
+- **Outputs**: New UTXOs (Unspent Transaction Outputs) that define who receives the bitcoins
+- **Locking Scripts**: Scripts that determine the conditions for spending outputs
+- **Unlocking Scripts**: Scripts that satisfy the conditions in locking scripts
+
+### Additional Resources
+
+For a deeper understanding of Bitcoin transactions, check out these official resources:
+
+- [BSV Wiki: Bitcoin Transaction](https://wiki.bitcoinsv.io/index.php/Bitcoin_Transaction) - Comprehensive explanation of transaction structure
+- [BSV Wiki: Script](https://wiki.bitcoinsv.io/index.php/Script) - Detailed information about Bitcoin Script language
+- [Bitcoin Whitepaper](https://craigwright.net/bitcoin-white-paper.pdf) - Section 5 covers the original design of transactions
+- [BSV Academy: Transactions Course](https://bitcoinsv.academy/course/transactions) - In-depth course on Bitcoin transactions
+
+## Step 3: Creating Your First Transaction
+
+Create a new file called `first-transaction.ts`:
+
+```typescript
+import { PrivateKey, P2PKH, Transaction } from '@bsv/sdk'
+
+async function createTransaction() {
+  // Create a private key (in production, you'd use proper key management)
+  const privateKey = PrivateKey.fromRandom()
+  console.log(`Private key WIF: ${privateKey.toWif()}`)
+  
+  // Derive the public key and address
+  const address = privateKey.toAddress()
+  console.log(`Address: ${address.toString()}`)
+  
+  // For a real transaction, you would have a source UTXO
+  // For this example, we'll create a transaction without inputs (cannot be broadcast)
+  const tx = new Transaction()
+  
+  // Add an output
+  tx.addOutput({
+    lockingScript: new P2PKH().lock(address),
+    satoshis: 100
+  })
+  
+  // Serialize the transaction
+  const txHex = tx.toHex() // Use toHex() instead of toString()
+  console.log(`Transaction (hex): ${txHex}`)
+  
+  // Get transaction ID as a hex string
+  const txid = Buffer.from(tx.id()).toString('hex') // Convert the byte array to hex string
+  console.log(`Transaction ID: ${txid}`)
+  
+  // Display the transaction structure
+  console.log('\nTransaction Structure:')
+  console.log(`Version: ${tx.version}`)
+  console.log(`Input Count: ${tx.inputs.length}`)
+  console.log(`Output Count: ${tx.outputs.length}`)
+  
+  for (let i = 0; i < tx.outputs.length; i++) {
+    const output = tx.outputs[i]
+    console.log(`\nOutput #${i}:`)
+    console.log(`  Satoshis: ${output.satoshis}`)
+    console.log(`  Locking Script: ${output.lockingScript.toHex()}`)
+    console.log(`  Locking Script (ASM): ${output.lockingScript.toASM()}`)
+  }
+}
+
+createTransaction().catch(console.error)
+```
+
+## Step 4: Run Your Code
+
+Execute your code with the following command:
+
+```bash
+npx ts-node first-transaction.ts
+```
+
+You should see output showing your private key, address, and transaction details.
+
+## Step 5: Next Steps for Real Transactions
+
+The transaction we created in the previous step doesn't have any inputs, so it can't be broadcast to the network. It serves as a conceptual introduction to transaction structure.
+
+In the next tutorial, "[Working with Testnet Transactions (Low-Level)](./testnet-transactions-low-level.md)", you'll learn how to:
+
+1. Create a wallet specifically for the BSV testnet
+2. Obtain free testnet coins from a faucet
+3. Create transactions with real inputs and outputs
+4. Calculate transaction fees automatically
+5. Sign and broadcast real transactions to the testnet network
+
+### Preview: Transaction Structure for Real Transactions
+
+Here's a simplified preview of what a complete transaction looks like. Don't worry about understanding all the details yet - this is just to give you a sense of the structure you'll work with in the next tutorial:
+
+```typescript
+// A complete transaction typically follows this structure:
+const tx = new Transaction()
+
+// Add an input (where the money comes from)
+tx.addInput({
+  sourceTransaction: /* previous transaction containing your funds */,
+  sourceOutputIndex: /* which output from that transaction */,
+  unlockingScriptTemplate: /* script to unlock those funds */
+})
+
+// Add an output (where the money goes)
+tx.addOutput({
+  lockingScript: /* script that locks funds to recipient */,
+  satoshis: /* amount to send */
+})
+
+// Add change output (remaining funds returned to you)
+tx.addOutput({
+  lockingScript: /* script that locks funds to you */,
+  change: true // Automatically handles change amount
+})
+
+// Calculate fee and sign
+await tx.fee()
+await tx.sign()
+
+// Broadcast to the network
+const result = await tx.broadcast()
+```
+
+### Understanding Transaction Fees
+
+Bitcoin transactions require fees to be included in a block by miners. The BSV SDK simplifies fee calculation with the `fee()` method, which:
+
+- Calculates the appropriate fee based on transaction size
+- Works with the `change: true` parameter to automatically handle change outputs
+
+You'll get hands-on experience with transaction fees in the testnet tutorial.
+
+## Conclusion
+
+Congratulations! You've learned the basics of creating a BSV transaction using the TypeScript SDK. In this tutorial, you've:
+
+- Set up your development environment
+- Learned about transaction components
+- Created a simple transaction
+- Understood how to structure a complete transaction
+
+## Next Steps
+
+- Ready to try real transactions? Continue with [Working with Testnet Transactions](./testnet-transactions-low-level.md)
+- Learn about [Key Management and Cryptography](./key-management.md)
+- Explore how to [Broadcast Transactions with ARC](./transaction-broadcasting.md)
+
+## Additional Resources
+
+- [BSV Transaction Reference](../reference/transaction.md)
+- [Script Reference](../reference/script.md)
+- [Bitcoin Transaction Explorer](https://whatsonchain.com) - To view your transactions on the blockchain

package/docs/tutorials/first-transaction.md

@@ -0,0 +1,278 @@
+# Your First BSV Transaction
+
+**Duration**: 15 minutes  
+**Prerequisites**: Node.js, basic TypeScript knowledge  
+
+## Learning Goals
+- Install and configure the BSV TypeScript SDK
+- Create a simple transaction using `WalletClient` interface on the mainnet network. This approach makes it easy to build transactions by abstracting away many of the low-level details. By the end, you'll understand the basic components of a BSV transaction and how to construct, sign, and broadcast one on the BSV blockchain.
+
+> **📚 Related Concepts**: Before starting, you may want to review [Transaction Structure](../concepts/transaction-structure.md) and [Wallet Integration](../concepts/wallet-integration.md) to understand the fundamentals.
+
+## Introduction
+
+In this tutorial, you'll learn how to create your first Bitcoin SV transactions using the TypeScript SDK's `WalletClient` interface on the mainnet network. This approach makes it easy to build transactions by abstracting away many of the low-level details. By the end, you'll understand the basic components of a BSV transaction and how to construct, sign, and broadcast one on the BSV blockchain.
+
+> **💡 Try It Interactive**: Want to experiment with the code examples from this tutorial? Check out our [Interactive BSV Coding Environment](https://fast.brc.dev/) where you can run SDK code directly in your browser without any setup!
+
+## Precondition 
+
+Install a BRC-100 compliant wallet such as the [MetaNet Desktop Wallet](https://metanet.bsvb.tech/). When you install it, you'll receive a small amount of funds to play with.
+
+## Step 1: Setting Up Your Environment
+
+First, create a new Node.js project and install the BSV SDK:
+
+```bash
+# Create a new directory for your project
+mkdir my-first-bsv-tx
+cd my-first-bsv-tx
+
+# Initialize a new Node.js project
+npm init -y
+
+# Install TypeScript and ts-node (TypeScript execution engine)
+npm install typescript ts-node @types/node --save-dev
+# ts-node allows you to run TypeScript files directly without compiling them first
+
+# Install the BSV SDK
+npm install @bsv/sdk
+```
+
+Create a basic TypeScript configuration file (`tsconfig.json`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "strict": true,
+    "outDir": "./dist"
+  }
+}
+```
+
+## Step 2: Understanding Transaction Components
+
+Before we write any code, let's understand the basic components of a Bitcoin transaction:
+
+- **Inputs**: References to previous transaction outputs that you're spending
+- **Outputs**: New UTXOs (Unspent Transaction Outputs) that define who receives the bitcoins
+- **Locking Scripts**: Scripts that determine the conditions for spending outputs
+- **Unlocking Scripts**: Scripts that satisfy the conditions in locking scripts
+
+### Additional Resources
+
+For a deeper understanding of Bitcoin transactions, check out these resources:
+
+- [Bitcoin SV Protocol Specifications](https://github.com/bitcoin-sv-specs/protocol) - Official Bitcoin SV protocol specifications
+- [WhatsOnChain Explorer](https://whatsonchain.com/) - Standard block explorer for viewing BSV transactions
+- [Bitcoin Developer Reference](https://developer.bitcoin.org/reference/transactions.html) - Comprehensive explanation of transaction structure
+
+## Step 3: Your First Transactions - 3 Simple Steps
+
+Now let's create your first BSV transactions using three clean, focused steps. Each step builds on the previous one, showing you the core workflow of BSV development.
+
+We'll create three separate files to keep things organized and clear:
+
+### Example 1: Create a Simple Transaction
+
+**What you'll do**: Create your first transaction that stores a simple message on the BSV blockchain. This introduces you to the basic `createAction()` method and shows how data can be permanently stored on-chain.
+
+Create a file called `step1-simple-transaction.ts`:
+
+```typescript
+import { WalletClient, Script } from '@bsv/sdk'
+
+async function createSimpleTransaction() {
+  // Connect to user's wallet
+  const wallet = new WalletClient('auto', 'localhost')
+  
+  // Create a simple transaction with a data output
+  const response = await wallet.createAction({
+    description: 'My first BSV transaction',
+    outputs: [{
+      satoshis: 100,
+      lockingScript: Script.fromASM(`OP_RETURN ${Buffer.from('Hello BSV!').toString('hex')}`).toHex(),
+      outputDescription: 'My first data output'
+    }]
+  })
+  
+  console.log('Transaction created:', response)
+  if (response.txid) {
+    console.log(`View on WhatsOnChain: https://whatsonchain.com/tx/${response.txid}`)
+  }
+  
+  return response
+}
+
+// Run the function
+createSimpleTransaction().catch(console.error)
+```
+
+Run it as follows:
+
+```bash
+# Run the TypeScript file directly
+npx ts-node step1-simple-transaction.ts
+```
+
+
+**What's happening here:**
+- We connect to your BRC-100 wallet (like MetaNet Desktop)
+- Create a transaction with one output containing "Hello BSV!" data
+- The wallet automatically handles inputs, change, and fees
+- We get a transaction ID to view on the blockchain explorer
+
+### Example 2: Create and Store a Token
+
+**What you'll do**: Create a spendable token and organize it using wallet baskets. This shows you how to create UTXOs that can be spent later and how to use the wallet's organizational features.
+
+Create a file called `step2-create-token.ts`:
+
+```typescript
+import { WalletClient, Script } from '@bsv/sdk'
+
+async function createToken() {
+  // Connect to user's wallet
+  const wallet = new WalletClient('auto', 'localhost')
+  
+  // Create a token and store it in a specific basket
+  const response = await wallet.createAction({
+    description: 'Create my first token',
+    outputs: [{
+      satoshis: 1,
+      lockingScript: Script.fromASM('OP_NOP').toHex(),
+      basket: 'my-tokens',
+      outputDescription: 'My first token'
+    }]
+  })
+  
+  console.log('Token created:', response)
+  if (response.txid) {
+    console.log(`Token transaction: https://whatsonchain.com/tx/${response.txid}`)
+  }
+  
+  return response
+}
+
+// Run the function
+createToken().catch(console.error)
+```
+
+
+Run it as follows:
+
+```bash
+# Run the TypeScript file directly
+npx ts-node step2-create-token.ts
+```
+
+
+**What's happening here:**
+- We create a minimal token (1 satoshi with OP_NOP script)
+- Store it in a wallet basket called 'my-tokens' for organization
+- This creates a spendable output we can use later
+
+### Example 3: List and Spend Your Token
+
+**What you'll do**: Retrieve your stored token (created in the previous example) and spend it in a new transaction. This demonstrates the complete UTXO lifecycle and shows how to work with transaction inputs using the BEEF format.
+
+Create a file called `step3-spend-token.ts`:
+
+```typescript
+import { WalletClient, Script } from '@bsv/sdk'
+
+async function spendToken() {
+  // Connect to user's wallet
+  const wallet = new WalletClient('auto', 'localhost')
+  
+  // First, list our tokens
+  const tokenList = await wallet.listOutputs({
+    basket: 'my-tokens',
+    include: 'entire transactions'
+  })
+  
+  console.log('Available tokens:', tokenList.outputs.length)
+  
+  let response;
+  if (tokenList.outputs.length > 0) {
+    // Spend the first token
+    response = await wallet.createAction({
+      description: 'Spend my first token',
+      inputBEEF: tokenList.BEEF,
+      inputs: [{
+        outpoint: tokenList.outputs[0].outpoint,
+        unlockingScript: Script.fromASM('OP_TRUE').toHex(),
+        inputDescription: 'My token being spent'
+      }]
+    })
+    
+    console.log('Token spent:', response)
+    if (response.txid) {
+      console.log(`Spending transaction: https://whatsonchain.com/tx/${response.txid}`)
+    }
+  } else {
+    console.log('No tokens available to spend. Run step2-create-token.ts first!')
+    response = null;
+  }
+  
+  return response
+}
+
+// Run the function
+spendToken().catch(console.error)
+```
+
+
+Run it as follows:
+
+```bash
+# Run the TypeScript file directly
+npx ts-node step3-spend-token.ts
+```
+
+
+**What's happening here:**
+- We list tokens from our 'my-tokens' basket
+- Spend the first available token by providing its outpoint
+- Create a new output with proof that we spent the token
+- The BEEF (Blockchain Exchange Format) provides the transaction history
+
+
+
+## What You've Learned
+
+Congratulations! You've successfully created your first BSV transactions. Here's what you accomplished:
+
+### Core Concepts Mastered
+
+1. **WalletClient Usage**: Connected to your BRC-100 wallet and created transactions
+2. **Script Construction**: Used `Script.fromASM()` to create clean, readable Bitcoin scripts
+3. **Transaction Outputs**: Created both data storage and spendable token outputs
+4. **Wallet Baskets**: Organized your tokens using the basket system
+5. **UTXO Management**: Listed and spent existing outputs using BEEF format
+
+### Key WalletClient Methods
+
+- `createAction()`: Creates transactions with specified outputs and inputs
+- `listOutputs()`: Retrieves spendable outputs from wallet baskets
+- The wallet automatically handles signing, fees, and broadcasting
+
+### Script Types You Used
+
+- `OP_RETURN "data"`: Store arbitrary data on the blockchain
+- `OP_NOP`: Create simple tokens that can be spent later  
+- `OP_TRUE`: Unlock scripts that always validate (for simple spending)
+
+## Next Steps
+
+- Learn about [Key Management and Cryptography](./key-management.md)
+- Prefer lower-level control? Check out [First Transaction (Low-level API)](./first-transaction-low-level.md)
+
+## Additional Resources
+
+- [Wallet API Reference](../reference/wallet.md)
+- [BSV Wallet Protocols](https://projectbabbage.com/docs/guides/wallet/transactions)
+- [Transaction Broadcasting](https://projectbabbage.com/docs/guides/wallet/signing)