@bigmi/react 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.4.5](https://github.com/lifinance/bigmi/compare/v0.4.4...v0.4.5) (2025-08-27)
+
+### [0.4.4](https://github.com/lifinance/bigmi/compare/v0.4.3...v0.4.4) (2025-08-18)
+
 ### [0.4.3](https://github.com/lifinance/bigmi/compare/v0.4.2...v0.4.3) (2025-07-31)
 
 

package/README.md

@@ -31,38 +31,33 @@ Bigmi is modularized into several packages, each suited to different use cases:
 ```sh
 pnpm add @bigmi/react
 ```
+
 ```sh
 pnpm add @bigmi/core
 ```
+
 ```sh
 pnpm add @bigmi/client
 ```
 
 ## Getting Started
 
-Here is an example of a basic usage:
+### Node.js
 
-```tsx
-import { useConfig } from '@bigmi/react'
+How to setup Bigmi on the backend with Node.js:
+
+```typescript
+// main.ts
 import {
-  type UTXOSchema,
+  createClient,
   bitcoin,
-  getBalance,
-  getBlockCount,
+  blockchair,
   sendUTXOTransaction,
   waitForTransaction,
-  createClient, 
-  fallback, 
-  rpcSchema
-  ankr,
-  blockchair,
-  blockcypher,
-  mempool
+  getBalance,
 } from '@bigmi/core'
-import { useAccount } from '@bigmi/react'
-
 
-// Create a public client for interactions with the Bitcoin
+// Create a client for Bitcoin mainnet
 const publicClient = createClient({
   chain: bitcoin,
   rpcSchema: rpcSchema<UTXOSchema>(),
@@ -103,23 +98,359 @@ const transaction = await waitForTransaction(publicClient, {
 });
 
 console.log('Transaction confirmed:', transaction);
+ 
+```
+
+### React
+
+Simple bigmi setup with a react app:
+
+```typescript
+// App.tsx
+
+import { bitcoin, http, createClient } from '@bigmi/core'
+import { BigmiProvider, createConfig } from '@bigmi/react'
+import { binance, xverse, phantom } from '@bigmi/client'
+
+const chainId  = bitcoin.id
+
+// Create bigmi config object
+const config = createConfig({
+    chains: [bitcoin],
+    connectors: [binance({chainId}), xverse({chainId}), phantom({chainId})],
+    client: ({ chain }) => createClient({ chain, transport: http() }),
+    ssr: true // If using Next.js or SSR
+})
+
+
+function App() {
+  return (
+    // Wrap your application with the necessary providers:
+    <BigmiProvider config={config}>
+      <YourApp />
+    </BigmiProvider>
+  )
+}
+```
+
+```typescript
+// YourApp.tsx
+
+// Import the hooks from bigmi/react library
+import { useAccount, useBalance, useConnect } from '@bigmi/react'
+
+const { address, isConnected } = useAccount()
+const { balance } = useBalance()
+const { connect } = useConnect()
+
+function YourApp() {
+  return (
+    <div>
+      {isConnected ? (
+        <p>Connected: {address}: {balance}BTC</p>
+      ) : (
+        <button onClick={connect}>Connect Wallet</button>
+      )}
+    </div>
+  )
+}
+```
+
+## Creating Bitcoin Transactions
+
+While Bigmi excels at blockchain data retrieval and transaction broadcasting, it doesn't include transaction creation functions. For generating valid transaction hex, we recommend using **bitcoinjs-lib** (which Bigmi already depends on).
+
+### Basic Transaction Creation
+
+Here's how to create a Bitcoin transaction using bitcoinjs-lib with Bigmi:
+
+```typescript
+import * as bitcoin from 'bitcoinjs-lib';
+import { 
+  createClient, 
+  getUTXOs, 
+  sendUTXOTransaction, 
+  waitForTransaction,
+  getBlockStats,
+  getBlockCount
+} from '@bigmi/core';
+
+async function createAndSendTransaction(
+  client: Client,
+  fromAddress: string,
+  toAddress: string,
+  amount: number, // in satoshis
+  privateKey: Buffer
+) {
+  // 1. Get UTXOs for the address using Bigmi
+  const utxos = await getUTXOs(client, { address: fromAddress });
+  
+  // 2. Create a new transaction using bitcoinjs-lib
+  const psbt = new bitcoin.Psbt();
+  
+  // 3. Add inputs from UTXOs
+  let inputValue = 0;
+  const estimatedFee = 1000; // You should calculate this properly
+  
+  for (const utxo of utxos) {
+    psbt.addInput({
+      hash: utxo.txId,
+      index: utxo.vout,
+      witnessUtxo: {
+        script: Buffer.from(utxo.scriptHex, 'hex'),
+        value: utxo.value,
+      },
+    });
+    inputValue += utxo.value;
+    if (inputValue >= amount + estimatedFee) break;
+  }
+  
+  // 4. Add recipient output
+  psbt.addOutput({
+    address: toAddress,
+    value: amount,
+  });
+  
+  // 5. Add change output if needed
+  const change = inputValue - amount - estimatedFee;
+  if (change > 546) { // Dust threshold
+    psbt.addOutput({
+      address: fromAddress,
+      value: change,
+    });
+  }
+  
+  // 6. Sign the transaction
+  const keyPair = bitcoin.ECPair.fromPrivateKey(privateKey);
+  psbt.signAllInputs(keyPair);
+  psbt.finalizeAllInputs();
+  
+  // 7. Get the raw transaction hex
+  const rawTx = psbt.extractTransaction().toHex();
+  
+  // 8. Broadcast using Bigmi
+  const txId = await sendUTXOTransaction(client, { hex: rawTx });
+  
+  // 9. Wait for confirmation using Bigmi
+  const confirmedTx = await waitForTransaction(client, {
+    txId,
+    txHex: rawTx,
+    senderAddress: fromAddress,
+    confirmations: 1,
+  });
+  
+  return confirmedTx;
+}
+```
+
+### Fee Estimation
+
+Proper fee estimation is crucial for transaction confirmation:
+
+```typescript
+async function estimateFee(
+  client: Client,
+  numInputs: number,
+  numOutputs: number
+): Promise<number> {
+  // Get recent block stats for fee estimation
+  const blockHeight = await getBlockCount(client);
+  const blockStats = await getBlockStats(client, {
+    blockNumber: blockHeight,
+    stats: ['avgfeerate']
+  });
+  
+  // Estimate transaction size
+  // P2WPKH: ~68 bytes per input, ~31 bytes per output, ~10 bytes overhead
+  const estimatedSize = (numInputs * 68) + (numOutputs * 31) + 10;
+  
+  // Calculate fee (satoshis per byte * size)
+  const feeRate = blockStats.avgfeerate || 1; // fallback to 1 sat/byte
+  return Math.ceil(feeRate * estimatedSize);
+}
+```
+
+### Complete Example with Error Handling
+
+```typescript
+import * as bitcoin from 'bitcoinjs-lib';
+import { createClient, getBalance, getUTXOs, sendUTXOTransaction, waitForTransaction } from '@bigmi/core';
+
+async function safeSendBitcoin(
+  client: Client,
+  fromAddress: string,
+  toAddress: string,
+  amount: number,
+  privateKey: Buffer
+) {
+  try {
+    // Check balance
+    const balance = await getBalance(client, { address: fromAddress });
+    if (balance < amount + 1000) {
+      throw new Error('Insufficient balance');
+    }
+    
+    // Get UTXOs
+    const utxos = await getUTXOs(client, {
+      address: fromAddress,
+      minValue: amount + 1000,
+    });
+    
+    if (utxos.length === 0) {
+      throw new Error('No UTXOs available');
+    }
+    
+    // Create transaction
+    const psbt = new bitcoin.Psbt();
+    
+    let totalInput = 0;
+    for (const utxo of utxos) {
+      psbt.addInput({
+        hash: utxo.txId,
+        index: utxo.vout,
+        witnessUtxo: {
+          script: Buffer.from(utxo.scriptHex, 'hex'),
+          value: utxo.value,
+        },
+      });
+      totalInput += utxo.value;
+    }
+    
+    // Add outputs
+    psbt.addOutput({
+      address: toAddress,
+      value: amount,
+    });
+    
+    // Calculate fee and change
+    const fee = await estimateFee(client, utxos.length, 2);
+    const change = totalInput - amount - fee;
+    
+    if (change < 0) {
+      throw new Error('Insufficient funds for fee');
+    }
+    
+    if (change > 546) { // Dust threshold
+      psbt.addOutput({
+        address: fromAddress,
+        value: change,
+      });
+    }
+    
+    // Sign and finalize
+    const keyPair = bitcoin.ECPair.fromPrivateKey(privateKey);
+    psbt.signAllInputs(keyPair);
+    psbt.finalizeAllInputs();
+    
+    // Get transaction hex
+    const txHex = psbt.extractTransaction().toHex();
+    
+    // Broadcast with Bigmi
+    const txId = await sendUTXOTransaction(client, { hex: txHex });
+    
+    // Wait for confirmation
+    const confirmed = await waitForTransaction(client, {
+      txId,
+      txHex,
+      senderAddress: fromAddress,
+      confirmations: 1,
+    });
+    
+    return {
+      txId,
+      fee,
+      confirmed,
+    };
+    
+  } catch (error) {
+    console.error('Transaction failed:', error);
+    throw error;
+  }
+}
+```
 
-// Getting account information inside the React application
-const bigmiConfig = useConfig()
-const account = useAccount()
+### Working with Different Address Types
+
+```typescript
+import { getAddressInfo } from '@bigmi/core';
+
+function createInputForUTXO(utxo: UTXO, addressInfo: AddressInfo) {
+  const input: any = {
+    hash: utxo.txId,
+    index: utxo.vout,
+  };
+  
+  switch (addressInfo.type) {
+    case 'p2wpkh':
+    case 'p2wsh':
+      // Witness UTXOs for SegWit
+      input.witnessUtxo = {
+        script: Buffer.from(utxo.scriptHex, 'hex'),
+        value: utxo.value,
+      };
+      break;
+    case 'p2pkh':
+    case 'p2sh':
+      // Need full transaction for legacy
+      input.nonWitnessUtxo = Buffer.from(fullTransactionHex, 'hex');
+      break;
+  }
+  
+  return input;
+}
+```
 
-console.log('Bitcoin account address:', account.address);
+### RBF (Replace-By-Fee) Support
+
+Create transactions with RBF enabled for fee bumping:
+
+```typescript
+const psbt = new bitcoin.Psbt();
+
+// Add inputs with RBF sequence
+for (const utxo of utxos) {
+  psbt.addInput({
+    hash: utxo.txId,
+    index: utxo.vout,
+    sequence: 0xfffffffd, // RBF enabled
+    witnessUtxo: {
+      script: Buffer.from(utxo.scriptHex, 'hex'),
+      value: utxo.value,
+    },
+  });
+}
 ```
 
+### Alternative Libraries
+
+While we recommend bitcoinjs-lib, you can also use:
+- **@scure/btc-signer** - Modern, audited Bitcoin transaction library
+- **bitcore-lib** - Alternative to bitcoinjs-lib
+- **bcoin** - Full Bitcoin implementation
+
+### Security Best Practices
+
+1. **Never expose private keys** in client-side code
+2. **Use hardware wallets** for production applications
+3. **Validate all inputs** before creating transactions
+4. **Test on testnet** before mainnet deployment
+5. **Implement proper error handling** for all edge cases
+
 ## Examples
 
-We are working on more examples to showcase Bigmi's capabilities. Stay tuned!
+- [See Node.js examples](./docs/core/examples.md)
+- [See React examples](./docs/react/examples.md)
 
-In the meantime, explore the [LI.FI Widget](https://github.com/lifinance/widget) and [LI.FI SDK](https://github.com/lifinance/sdk) for inspiration.
+You can explore the [LI.FI Widget](https://github.com/lifinance/widget) and [LI.FI SDK](https://github.com/lifinance/sdk) for detailed production examples.
 
 ## Documentation
 
-Detailed documentation is coming soon. For now, refer to the source code and type definitions for guidance.
+- [Learn more about Configuration](./docs/core/config.md)
+- [See Core Docs](./docs/core/index.md)
+- [See Client Docs](./docs/client/index.md)
+- [See React Docs](./docs/react/index.md)
+
+- [Want to add support for your wallet?](./docs/client/connectors.md)
 
 ## Support
 

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 export declare const name = "@bigmi/react";
-export declare const version = "0.4.3";
+export declare const version = "0.4.5";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const name = '@bigmi/react';
-export const version = '0.4.3';
+export const version = '0.4.5';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigmi/react",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "React primitives for Bitcoin apps.",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -29,8 +29,8 @@
     "hooks"
   ],
   "dependencies": {
-    "@bigmi/client": "^0.4.3",
-    "@bigmi/core": "^0.4.3"
+    "@bigmi/client": "^0.4.5",
+    "@bigmi/core": "^0.4.5"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.68.0",

package/package.json.tmp

@@ -1,6 +1,6 @@
 {
   "name": "@bigmi/react",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "React primitives for Bitcoin apps.",
   "type": "module",
   "main": "./src/index.ts",
@@ -47,11 +47,11 @@
     "@bigmi/core": "workspace:^"
   },
   "devDependencies": {
-    "cpy-cli": "^5.0.0",
+    "cpy-cli": "^6.0.0",
     "madge": "^8.0.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
-    "typescript": "^5.7.3"
+    "typescript": "^5.9.2"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.68.0",

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@bigmi/react'
-export const version = '0.4.3'
+export const version = '0.4.5'