signet.js 0.0.1-beta.5 → 0.0.1-beta.7

package/docs/pages/chains/bitcoin/btc-rpc-adapter.mdx

@@ -0,0 +1,307 @@
+# Implementing a Bitcoin RPC Adapter
+
+This guide explains how to implement a custom RPC adapter for interacting with Bitcoin nodes or services.
+
+## Overview
+
+The `BTCRpcAdapter` provides an abstraction layer for Bitcoin-specific operations like UTXO management, balance queries, and transaction broadcasting. You might want to implement a custom adapter when:
+
+- Using a different Bitcoin node implementation
+- Integrating with a specific blockchain service
+- Adding support for custom transaction types
+- Implementing specialized UTXO selection strategies
+
+## Step-by-Step Guide
+
+### 1. Define the Required Types
+
+First, ensure you have the necessary types defined:
+
+```typescript
+interface BTCInput {
+  txid: string
+  vout: number
+  value: number
+  address: string
+  scriptPubKey: string
+}
+
+interface BTCOutput {
+  address: string
+  value: number
+}
+
+interface BTCTransaction {
+  txid: string
+  vout: Array<{
+    scriptpubkey: string
+    value: number
+  }>
+}
+```
+
+### 2. Implement the BTCRpcAdapter
+
+Create a new class that extends the `BTCRpcAdapter` abstract class:
+
+```typescript
+import { BTCRpcAdapter } from '../BTCRpcAdapter'
+import { BTCInput, BTCOutput, BTCTransaction } from '../types'
+
+export class CustomBTCAdapter extends BTCRpcAdapter {
+  constructor(
+    private readonly config: {
+      url: string
+      apiKey?: string
+    }
+  ) {
+    super()
+  }
+
+  async getBalance(address: string): Promise<number> {
+    // Implement balance fetching
+    const response = await fetch(
+      `${this.config.url}/address/${address}/balance`,
+      {
+        headers: this.getHeaders(),
+      }
+    )
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch balance: ${await response.text()}`)
+    }
+
+    const data = await response.json()
+    return data.balance // Return balance in satoshis
+  }
+
+  async getTransaction(txid: string): Promise<BTCTransaction> {
+    // Implement transaction fetching
+    const response = await fetch(`${this.config.url}/tx/${txid}`, {
+      headers: this.getHeaders(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch transaction: ${await response.text()}`)
+    }
+
+    return await response.json()
+  }
+
+  async selectUTXOs(
+    from: string,
+    outputs: BTCOutput[],
+    confirmationTarget = 6
+  ): Promise<{
+    inputs: BTCInput[]
+    outputs: BTCOutput[]
+  }> {
+    // 1. Fetch available UTXOs
+    const utxos = await this.fetchUTXOs(from)
+
+    // 2. Get current fee rate
+    const feeRate = await this.getFeeRate(confirmationTarget)
+
+    // 3. Use coinselect for UTXO selection
+    const { inputs, outputs } = coinselect(utxos, outputs, feeRate)
+
+    if (!inputs || !outputs) {
+      throw new Error('Failed to select UTXOs')
+    }
+
+    return { inputs, outputs }
+  }
+
+  async broadcastTransaction(txHex: string): Promise<string> {
+    // Implement transaction broadcasting
+    const response = await fetch(`${this.config.url}/tx`, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body: txHex,
+    })
+
+    if (!response.ok) {
+      throw new Error(
+        `Failed to broadcast transaction: ${await response.text()}`
+      )
+    }
+
+    return await response.text() // Return txid
+  }
+
+  // Helper methods
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+
+    if (this.config.apiKey) {
+      headers['Authorization'] = `Bearer ${this.config.apiKey}`
+    }
+
+    return headers
+  }
+
+  private async fetchUTXOs(address: string): Promise<BTCInput[]> {
+    const response = await fetch(`${this.config.url}/address/${address}/utxo`, {
+      headers: this.getHeaders(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch UTXOs: ${await response.text()}`)
+    }
+
+    return await response.json()
+  }
+
+  private async getFeeRate(confirmationTarget: number): Promise<number> {
+    const response = await fetch(`${this.config.url}/fees/recommended`, {
+      headers: this.getHeaders(),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch fee rate: ${await response.text()}`)
+    }
+
+    const fees = await response.json()
+    return fees[`${confirmationTarget}BlockFee`]
+  }
+}
+```
+
+### 3. Implement Error Handling
+
+Add proper error handling for your adapter:
+
+```typescript
+class BTCAdapterError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly httpStatus?: number
+  ) {
+    super(message)
+    this.name = 'BTCAdapterError'
+  }
+}
+
+// Usage in adapter methods
+private async handleResponse<T>(
+  response: Response,
+  errorContext: string
+): Promise<T> {
+  if (!response.ok) {
+    throw new BTCAdapterError(
+      `${errorContext}: ${await response.text()}`,
+      'API_ERROR',
+      response.status
+    )
+  }
+
+  return await response.json()
+}
+```
+
+### 4. Add UTXO Selection Strategy
+
+Implement a custom UTXO selection strategy if needed:
+
+```typescript
+interface UTXOSelectionStrategy {
+  select(
+    utxos: BTCInput[],
+    outputs: BTCOutput[],
+    feeRate: number
+  ): {
+    inputs: BTCInput[]
+    outputs: BTCOutput[]
+  }
+}
+
+class LargestFirstStrategy implements UTXOSelectionStrategy {
+  select(
+    utxos: BTCInput[],
+    outputs: BTCOutput[],
+    feeRate: number
+  ): {
+    inputs: BTCInput[]
+    outputs: BTCOutput[]
+  } {
+    // Sort UTXOs by value (largest first)
+    const sortedUtxos = [...utxos].sort((a, b) => b.value - a.value)
+
+    // Implement selection logic
+    // ...
+
+    return { inputs, outputs }
+  }
+}
+```
+
+## Example Usage
+
+```typescript
+// Initialize the adapter
+const btcAdapter = new CustomBTCAdapter({
+  url: 'https://api.bitcoin-service.com',
+  apiKey: 'your-api-key',
+})
+
+// Use in Bitcoin chain implementation
+const bitcoinChain = new Bitcoin({
+  network: 'mainnet',
+  contract: new ChainSignatureContract(...),
+  btcRpcAdapter: btcAdapter,
+})
+
+// Direct usage
+const balance = await btcAdapter.getBalance('bc1...')
+
+const { inputs, outputs } = await btcAdapter.selectUTXOs(
+  'bc1...',
+  [{ address: 'bc1...', value: 100000 }]
+)
+
+const txid = await btcAdapter.broadcastTransaction(signedTxHex)
+```
+
+## Testing
+
+Create comprehensive tests for your adapter:
+
+```typescript
+describe('CustomBTCAdapter', () => {
+  let adapter: CustomBTCAdapter
+  let mockFetch: jest.Mock
+
+  beforeEach(() => {
+    mockFetch = jest.fn()
+    global.fetch = mockFetch
+    adapter = new CustomBTCAdapter({
+      url: 'https://test.api',
+      apiKey: 'test-key',
+    })
+  })
+
+  describe('getBalance', () => {
+    it('should return balance in satoshis', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ balance: 100000 }),
+      })
+
+      const balance = await adapter.getBalance('bc1...')
+      expect(balance).toBe(100000)
+    })
+
+    it('should handle errors', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        text: () => Promise.resolve('API Error'),
+      })
+
+      await expect(adapter.getBalance('bc1...')).rejects.toThrow()
+    })
+  })
+})
+```

package/docs/pages/chains/cosmos.mdx

@@ -0,0 +1,181 @@
+# Cosmos Chain Implementation
+
+The Cosmos chain implementation supports Cosmos SDK-based networks (Cosmos Hub, Osmosis, etc.) with a focus on standard transactions and IBC transfers.
+
+## Configuration
+
+```ts twoslash filename="base.ts"
+// [!include ~/snippets/contract.ts]
+// ---cut---
+import { Cosmos } from 'signet.js'
+
+const cosmosChain = new Cosmos({
+  chainId: 'cosmoshub-4', // Chain ID of the target network
+  contract,
+})
+```
+
+## Methods
+
+### getBalance
+
+Gets the native token balance of an address.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const balance = await cosmosChain.getBalance('cosmos1...')
+```
+
+**Parameters:**
+
+- `address`: The Cosmos address to check
+
+**Returns:**
+
+- The balance formatted according to the chain's decimal places
+
+### deriveAddressAndPublicKey
+
+Derives a Cosmos address and public key for a given path.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { address, publicKey } = await cosmosChain.deriveAddressAndPublicKey(
+  'predecessor_id',
+  'any_string'
+)
+```
+
+**Parameters:**
+
+- `predecessor`: The ID of the signer to derive from
+- `path`: The derivation path to use
+
+**Returns:**
+
+- Object containing:
+  - `address`: The derived Cosmos address (bech32 format)
+  - `publicKey`: The corresponding compressed public key
+
+### getMPCPayloadAndTransaction
+
+Prepares a transaction for MPC signing.
+
+```ts twoslash filename="unsigned-transaction.ts"
+// [!include base.ts]
+// ---cut---
+import { CosmosTransactionRequest } from 'signet.js'
+import { MsgSend } from 'cosmjs-types/cosmos/bank/v1beta1/tx'
+
+// Create a token transfer message
+const sendMsg = {
+  typeUrl: '/cosmos.bank.v1beta1.MsgSend',
+  value: MsgSend.fromPartial({
+    fromAddress: 'cosmos1...',
+    toAddress: 'cosmos1...',
+    amount: [
+      {
+        denom: 'uatom',
+        amount: '1000000', // 1 ATOM (1,000,000 uatom)
+      },
+    ],
+  }),
+}
+
+const transactionRequest: CosmosTransactionRequest = {
+  address: 'cosmos1...',
+  publicKey: '0235a3...',
+  messages: [sendMsg],
+  memo: 'Token transfer',
+}
+
+const { transaction: unsignedTransaction, mpcPayloads } =
+  await cosmosChain.getMPCPayloadAndTransaction(transactionRequest)
+```
+
+**Parameters:**
+
+- `transactionRequest`: Transaction configuration:
+  ```ts
+  {
+    address: string      // Sender's address
+    publicKey: string    // Signer's public key
+    messages: Message[]  // Array of Cosmos SDK messages
+    memo?: string       // Optional transaction memo
+    gas?: number        // Optional gas limit (default: 200,000)
+  }
+  ```
+
+**Returns:**
+
+- Object containing:
+  - `transaction`: The unsigned transaction
+  - `mpcPayloads`: Array of payloads to be signed
+
+### addSignature
+
+Adds signatures to a transaction.
+
+```ts twoslash filename="add-signature.ts"
+// [!include unsigned-transaction.ts]
+// ---cut---
+import { RSVSignature } from 'signet.js'
+
+// Ideally it would be a request to the Sig Network Smart Contract
+const mpcSignatures: RSVSignature[] = [
+  {
+    r: '0x...',
+    s: '0x...',
+    v: 27,
+  },
+]
+
+const signedTx = cosmosChain.addSignature({
+  transaction: unsignedTransaction,
+  mpcSignatures,
+})
+```
+
+**Parameters:**
+
+- `transaction`: The unsigned transaction
+- `mpcSignatures`: Array of RSV signatures from MPC
+
+**Returns:**
+
+- The serialized signed transaction in hex format
+
+### broadcastTx
+
+Broadcasts a signed transaction to the network.
+
+```ts twoslash filename="broadcast-tx.ts"
+// [!include add-signature.ts]
+// ---cut---
+const txHash = await cosmosChain.broadcastTx(signedTx)
+```
+
+**Parameters:**
+
+- `txSerialized`: The serialized transaction in hex format
+
+**Returns:**
+
+- The transaction hash
+
+## Technical Details
+
+The implementation:
+
+- Uses `@cosmjs/stargate` for transaction handling
+- Supports SIGN_MODE_DIRECT signing
+- Uses Protobuf for message encoding
+- Supports standard Cosmos SDK messages:
+  - Bank (Send, MultiSend)
+  - Staking (Delegate, Undelegate, Redelegate)
+  - Distribution (Withdraw Rewards)
+  - IBC (Transfer)
+- Handles automatic fee calculation based on gas prices
+- Supports custom message types through the Registry

package/docs/pages/chains/evm.mdx

@@ -0,0 +1,189 @@
+# EVM Chain Implementation
+
+This implementation supports all EVM-compatible networks (Ethereum, Binance Smart Chain, Polygon, etc.).
+
+## Configuration
+
+```ts twoslash filename="base.ts"
+// [!include ~/snippets/contract.ts]
+// ---cut---
+import { EVM } from 'signet.js'
+
+// Initialize the chain
+const evmChain = new EVM({
+  rpcUrl: 'https://mainnet.infura.io/v3/YOUR-PROJECT-ID',
+  contract,
+})
+```
+
+## Methods
+
+### getBalance
+
+Gets the native token balance of an address in ETH units.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const balance = await evmChain.getBalance('0x...')
+```
+
+**Parameters:**
+
+- `address`: The Ethereum address to check
+
+**Returns:**
+
+- The balance in ETH as a string
+
+### deriveAddressAndPublicKey
+
+Derives an Ethereum address and public key from a signer ID and derivation path.
+
+```ts twoslash
+// [!include base.ts]
+// ---cut---
+const { address, publicKey } = await evmChain.deriveAddressAndPublicKey(
+  '0x...',
+  'any_string'
+)
+```
+
+**Parameters:**
+
+- `predecessor`: The ID/address of the signer requesting the signature
+- `path`: The derivation path to use
+
+**Returns:**
+
+- Object containing:
+  - `address`: The derived Ethereum address
+  - `publicKey`: The corresponding public key in SEC1 uncompressed format
+
+### getMPCPayloadAndTransaction
+
+Prepares a transaction for MPC signing.
+
+```ts twoslash filename="unsigned-transaction.ts"
+// [!include base.ts]
+// ---cut---
+import { EVMTransactionRequest } from 'signet.js'
+
+const transactionRequest: EVMTransactionRequest = {
+  to: '0x...',
+  from: '0x...',
+  value: '100000000000000000',
+  data: '0x...',
+}
+
+const { transaction: unsignedTransaction, mpcPayloads } =
+  await evmChain.getMPCPayloadAndTransaction(transactionRequest)
+```
+
+The transaction is enhanced with:
+
+- Gas estimation
+- Nonce calculation
+- Chain ID
+- EIP-1559 fee parameters
+
+### addSignature
+
+Adds a signature to an unsigned transaction.
+
+```ts twoslash filename="add-signature.ts"
+// [!include unsigned-transaction.ts]
+// ---cut---
+import { RSVSignature } from 'signet.js'
+
+// Ideally it would be a request to the Sig Network Smart Contract
+const mpcSignatures: RSVSignature[] = [
+  {
+    r: '0x...',
+    s: '0x...',
+    v: 27,
+  },
+]
+
+const txSerialized = await evmChain.addSignature({
+  transaction: unsignedTransaction,
+  mpcSignatures,
+})
+```
+
+**Parameters:**
+
+- `transaction`: The unsigned transaction
+- `mpcSignatures`: Array of RSV signatures from MPC
+
+**Returns:**
+
+- The serialized signed transaction
+
+### broadcastTx
+
+Broadcasts a signed transaction to the network.
+
+```ts twoslash filename="broadcast-tx.ts"
+// [!include add-signature.ts]
+// ---cut---
+const txHash = await evmChain.broadcastTx(txSerialized)
+```
+
+**Parameters:**
+
+- `txSerialized`: The serialized signed transaction
+
+**Returns:**
+
+- The transaction hash
+
+## Adding New EVM Chains
+
+To add support for a new EVM-compatible chain, you only need to configure the provider URL. The chain ID and network configuration are automatically retrieved from the provider.
+
+```ts twoslash
+// [!include ~/snippets/contract.ts]
+// ---cut---
+import { EVM } from 'signet.js'
+
+// For Polygon (Matic)
+const polygonChain = new EVM({
+  rpcUrl: 'https://polygon-rpc.com',
+  contract,
+})
+
+// For Binance Smart Chain
+const bscChain = new EVM({
+  rpcUrl: 'https://bsc-dataseed.binance.org',
+  contract,
+})
+
+// For Arbitrum
+const arbitrumChain = new EVM({
+  rpcUrl: 'https://arb1.arbitrum.io/rpc',
+  contract,
+})
+```
+
+## Technical Details
+
+The implementation:
+
+- Uses `ethers.js` for transaction handling and RPC communication
+- Supports both legacy and EIP-1559 transactions
+- Handles automatic nonce management
+- Supports contract interactions through ABI encoding
+- Provides automatic gas estimation and fee calculation
+- Compatible with all EVM-based networks
+- Supports ENS name resolution on networks that implement it
+- Handles transaction signing according to EIP-155
+- Supports raw transaction data for custom contract interactions
+
+## Types
+
+The following types are used on the EVM chain:
+
+```ts twoslash
+// [!include ~/../src/chains/EVM/types.ts]
+```