@bsv/sdk 1.9.2 → 1.9.4

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

@@ -1,205 +0,0 @@
-# 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

@@ -1,275 +0,0 @@
-# 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://desktop.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)