@goplausible/openclaw-algorand-plugin 1.1.0 → 1.3.0

package/skills/haystack-router-development/references/getting-started.md

@@ -0,0 +1,93 @@
+# Getting Started
+
+## Prerequisites
+
+- **Node.js** >= 20
+- **algosdk** 3.x (peer dependency)
+
+## Installation
+
+```bash
+npm install @txnlab/haystack-router algosdk
+```
+
+## RouterClient Initialization
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+```
+
+### With Options
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  autoOptIn: true, // Auto-detect asset opt-in needs
+  referrerAddress: 'ABC...', // Earn 25% of swap fees
+  feeBps: 15, // Fee in basis points (default: 10)
+  debugLevel: 'info', // 'none' | 'info' | 'debug' | 'trace'
+})
+```
+
+### TestNet
+
+Override the algod connection and API base URL for TestNet:
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  algodUri: 'https://testnet-api.4160.nodely.dev/',
+  // Set apiBaseUrl if using a TestNet-specific API endpoint
+})
+```
+
+## Quick Example
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+
+// Get a quote: swap 1 ALGO → USDC
+const quote = await router.newQuote({
+  fromASAID: 0, // ALGO
+  toASAID: 31566704, // USDC
+  amount: 1_000_000, // 1 ALGO in microAlgos
+  address: activeAddress,
+})
+
+console.log(`Expected output: ${quote.quote} microUSDC`)
+console.log(`USD value: $${quote.usdOut}`)
+
+// Execute the swap (use-wallet signer for browser, custom signer for Node.js)
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1, // 1% slippage tolerance
+})
+
+const result = await swap.execute()
+console.log(`Confirmed in round ${result.confirmedRound}`)
+```
+
+## Amounts and Units
+
+All amounts are in **base units** (smallest denomination):
+
+| Asset               | Decimals | 1 unit in base | Example              |
+| ------------------- | -------- | -------------- | -------------------- |
+| ALGO (ASA 0)        | 6        | 1,000,000      | `1_000_000` = 1 ALGO |
+| USDC (ASA 31566704) | 6        | 1,000,000      | `5_000_000` = 5 USDC |
+
+Convert human-readable amounts:
+
+```typescript
+const amount = BigInt(Math.floor(parseFloat(userInput) * 10 ** decimals))
+```

package/skills/haystack-router-development/references/migration.md

@@ -0,0 +1,53 @@
+# Migration from @txnlab/deflex
+
+## Package Rename
+
+```bash
+npm uninstall @txnlab/deflex
+npm install @txnlab/haystack-router
+```
+
+## Import Changes
+
+```typescript
+// Before
+import { DeflexClient } from '@txnlab/deflex'
+
+// After
+import { RouterClient } from '@txnlab/haystack-router'
+```
+
+## Class and Type Renames
+
+| Before (@txnlab/deflex) | After (@txnlab/haystack-router) |
+| ----------------------- | ------------------------------- |
+| `DeflexClient`          | `RouterClient`                  |
+| `DeflexQuote`           | `SwapQuote`                     |
+| `DeflexTransaction`     | `SwapTransaction`               |
+| `DeflexConfig`          | `Config`                        |
+| `DeflexConfigParams`    | `ConfigParams`                  |
+| `DeflexSignature`       | `Signature`                     |
+
+## API Endpoint
+
+The SDK automatically uses the updated API endpoint. No manual URL changes needed.
+
+## Functionality
+
+All functionality is identical — only naming changed. A find-and-replace of the class and type names is sufficient.
+
+### Quick Migration
+
+```bash
+# Find all files that import from @txnlab/deflex
+grep -r "@txnlab/deflex" --include="*.ts" --include="*.tsx" -l
+
+# Replace imports
+# @txnlab/deflex → @txnlab/haystack-router
+# DeflexClient → RouterClient
+# DeflexQuote → SwapQuote
+# DeflexTransaction → SwapTransaction
+# DeflexConfig → Config
+# DeflexConfigParams → ConfigParams
+# DeflexSignature → Signature
+```

package/skills/haystack-router-development/references/node-automation.md

@@ -0,0 +1,113 @@
+# Node.js Automation (SDK)
+
+When building Node.js automation scripts that integrate Haystack Router directly in application code:
+
+## Setup
+
+```bash
+npm install @txnlab/haystack-router algosdk
+```
+
+## Environment Variables
+
+```bash
+# .env
+HAYSTACK_API_KEY=1b72df7e-1131-4449-8ce1-29b79dd3f51e  # Free tier (60 requests/min)
+```
+
+## Complete Example
+
+```typescript
+import algosdk from 'algosdk'
+import { RouterClient } from '@txnlab/haystack-router'
+
+async function main() {
+  const apiKey = process.env.HAYSTACK_API_KEY!
+
+  // For application code, use use-wallet or AlgorandClient for signing
+  // For Node.js scripts, create a custom signer:
+  const account = algosdk.mnemonicToSecretKey(process.env.MNEMONIC!)
+  const address = account.addr.toString()
+
+  const signer = async (
+    txnGroup: algosdk.Transaction[],
+    indexesToSign: number[],
+  ): Promise<Uint8Array[]> => {
+    return indexesToSign.map(
+      (index) => algosdk.signTransaction(txnGroup[index], account.sk).blob,
+    )
+  }
+
+  // Initialize router
+  const router = new RouterClient({
+    apiKey,
+    autoOptIn: true,
+  })
+
+  // Get quote: 1 ALGO → USDC
+  const quote = await router.newQuote({
+    fromASAID: 0,
+    toASAID: 31566704,
+    amount: 1_000_000,
+    address,
+  })
+
+  console.log(`Expected output: ${Number(quote.quote) / 1e6} USDC`)
+  console.log(`USD value: $${quote.usdOut.toFixed(2)}`)
+
+  // Execute swap
+  const swap = await router.newSwap({
+    quote,
+    address,
+    signer,
+    slippage: 1,
+  })
+
+  const result = await swap.execute()
+  console.log(`Confirmed in round ${result.confirmedRound}`)
+  console.log(`Transaction IDs: ${result.txIds.join(', ')}`)
+
+  const summary = swap.getSummary()
+  if (summary) {
+    console.log(`Input: ${summary.inputAmount} microunits`)
+    console.log(`Output: ${summary.outputAmount} microunits`)
+    console.log(`Fees: ${summary.totalFees} microAlgos`)
+  }
+}
+
+main().catch(console.error)
+```
+
+## Tracking with Notes
+
+Attach identifiers to transactions for backend tracking:
+
+```typescript
+const swap = await router.newSwap({
+  quote,
+  address,
+  signer,
+  slippage: 1,
+  note: new TextEncoder().encode(
+    JSON.stringify({
+      orderId: 'order-123',
+      timestamp: Date.now(),
+    }),
+  ),
+})
+
+await swap.execute()
+const txId = swap.getInputTransactionId()
+console.log(`Tracked: order-123 → ${txId}`)
+```
+
+## Debug Logging
+
+Enable verbose logging for troubleshooting:
+
+```typescript
+const router = new RouterClient({
+  apiKey,
+  debugLevel: 'debug', // 'none' | 'info' | 'debug' | 'trace'
+})
+```

package/skills/haystack-router-development/references/quotes.md

@@ -0,0 +1,155 @@
+# Quotes
+
+## Getting a Quote
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+
+const quote = await router.newQuote({
+  fromASAID: 0, // ALGO
+  toASAID: 31566704, // USDC
+  amount: 1_000_000, // 1 ALGO in base units
+  address: activeAddress,
+})
+```
+
+## Parameters
+
+| Parameter           | Type               | Required | Description                                     |
+| ------------------- | ------------------ | -------- | ----------------------------------------------- |
+| `fromASAID`         | `number \| bigint` | Yes      | Input asset ID (0 = ALGO)                       |
+| `toASAID`           | `number \| bigint` | Yes      | Output asset ID                                 |
+| `amount`            | `number \| bigint` | Yes      | Amount in base units                            |
+| `type`              | `string`           | No       | `'fixed-input'` (default) or `'fixed-output'`   |
+| `address`           | `string`           | No       | User address (needed for auto opt-in detection) |
+| `maxGroupSize`      | `number`           | No       | Max transactions in group (default: 16)         |
+| `maxDepth`          | `number`           | No       | Max routing hops (default: 4)                   |
+| `optIn`             | `boolean`          | No       | Include opt-in transaction for output asset     |
+| `disabledProtocols` | `Protocol[]`       | No       | Protocols to exclude from routing               |
+
+## Quote Response (SwapQuote)
+
+`newQuote()` returns a `SwapQuote` (extends `FetchQuoteResponse`):
+
+```typescript
+quote.quote // bigint — expected output amount in base units
+quote.amount // bigint — original input amount
+quote.usdIn // number — USD value of input
+quote.usdOut // number — USD value of output
+quote.userPriceImpact // number | undefined — price impact %
+quote.marketPriceImpact // number | undefined — market price impact %
+quote.route // Route[] — routing path details
+quote.flattenedRoute // Record<string, number> — protocol split percentages
+quote.quotes // DexQuote[] — individual DEX quotes
+quote.requiredAppOptIns // number[] — app IDs needing opt-in
+quote.createdAt // number — timestamp (ms)
+quote.address // string | undefined — user address if provided
+```
+
+## Quote Types
+
+**Fixed-input** (default): Specify exact input amount, receive variable output.
+
+```typescript
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000, // Exact: send 1 ALGO
+  type: 'fixed-input',
+})
+// quote.quote = expected USDC received
+```
+
+**Fixed-output**: Specify desired output, send variable input.
+
+```typescript
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000, // Exact: receive 1 USDC
+  type: 'fixed-output',
+})
+// quote.quote = ALGO required to send
+```
+
+## Displaying Quote Data
+
+```typescript
+const fromDecimals = 6 // ALGO
+const toDecimals = 6 // USDC
+
+const outputHuman = Number(quote.quote) / 10 ** toDecimals
+const inputHuman = Number(quote.amount) / 10 ** fromDecimals
+const rate = outputHuman / inputHuman
+
+console.log(`${inputHuman} ALGO → ${outputHuman} USDC`)
+console.log(`Rate: 1 ALGO = ${rate.toFixed(4)} USDC`)
+console.log(`USD in: $${quote.usdIn.toFixed(2)}`)
+console.log(`USD out: $${quote.usdOut.toFixed(2)}`)
+
+if (quote.userPriceImpact !== undefined) {
+  console.log(`Price impact: ${quote.userPriceImpact.toFixed(2)}%`)
+}
+```
+
+## Route Details
+
+Each quote includes routing information showing how the swap is split:
+
+```typescript
+// Flattened view: protocol → percentage
+for (const [protocol, pct] of Object.entries(quote.flattenedRoute)) {
+  console.log(`${protocol}: ${pct}%`)
+}
+// e.g., "TinymanV2: 60%", "Pact: 40%"
+
+// Detailed route with hops
+for (const route of quote.route) {
+  console.log(`${route.percentage}% of swap:`)
+  for (const hop of route.path) {
+    console.log(`  ${hop.in.unit_name} → ${hop.out.unit_name} via ${hop.name}`)
+  }
+}
+```
+
+## Asset Opt-In Detection
+
+```typescript
+// Option 1: Set autoOptIn on the client
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  autoOptIn: true,
+})
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000,
+  address: activeAddress, // Required for auto opt-in
+})
+
+// Option 2: Check manually and pass optIn flag
+const needsOptIn = await router.needsAssetOptIn(activeAddress, 31566704)
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000,
+  optIn: needsOptIn,
+})
+```
+
+## Lower-Level: fetchQuote()
+
+`fetchQuote()` returns the raw `FetchQuoteResponse` without `SwapQuote` enhancements (no bigint coercion, no `createdAt`). Use `newQuote()` unless you need the raw response.
+
+```typescript
+const raw = await router.fetchQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000,
+})
+// raw.quote is string | number (not bigint)
+```

package/skills/haystack-router-development/references/react-integration.md

@@ -0,0 +1,260 @@
+# React Integration
+
+## Setup
+
+Install dependencies:
+
+```bash
+npm install @txnlab/haystack-router @txnlab/use-wallet-react algosdk
+```
+
+Wrap your app with `WalletProvider`:
+
+```tsx
+import { WalletProvider, WalletId } from '@txnlab/use-wallet-react'
+
+const walletProviders = [
+  { id: WalletId.PERA },
+  { id: WalletId.DEFLY },
+  { id: WalletId.LUTE },
+]
+
+function App() {
+  return (
+    <WalletProvider wallets={walletProviders}>
+      <SwapInterface />
+    </WalletProvider>
+  )
+}
+```
+
+## Basic Swap Component
+
+```tsx
+import { useState } from 'react'
+import { useWallet } from '@txnlab/use-wallet-react'
+import { RouterClient, type SwapQuote } from '@txnlab/haystack-router'
+
+function SwapInterface() {
+  const { activeAddress, transactionSigner } = useWallet()
+  const [amount, setAmount] = useState('')
+  const [fromAsset, setFromAsset] = useState(0) // ALGO
+  const [toAsset, setToAsset] = useState(31566704) // USDC
+  const [slippage, setSlippage] = useState('1')
+  const [quote, setQuote] = useState<SwapQuote | null>(null)
+
+  const getQuote = async () => {
+    const router = new RouterClient({
+      apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+      autoOptIn: true,
+    })
+
+    const amountInBaseUnits = BigInt(Math.floor(parseFloat(amount) * 1_000_000))
+
+    const result = await router.newQuote({
+      fromASAID: fromAsset,
+      toASAID: toAsset,
+      amount: amountInBaseUnits,
+      address: activeAddress!,
+    })
+
+    setQuote(result)
+  }
+
+  const executeSwap = async () => {
+    if (!quote || !activeAddress) return
+
+    const router = new RouterClient({
+      apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+      autoOptIn: true,
+    })
+
+    const swap = await router.newSwap({
+      quote,
+      address: activeAddress,
+      signer: transactionSigner,
+      slippage: parseFloat(slippage),
+    })
+
+    const result = await swap.execute()
+    console.log(`Confirmed in round ${result.confirmedRound}`)
+
+    setQuote(null) // Clear stale quote
+  }
+
+  return (
+    <div>
+      <input
+        type="number"
+        value={amount}
+        onChange={(e) => setAmount(e.target.value)}
+        placeholder="Amount"
+      />
+      <button onClick={getQuote} disabled={!activeAddress || !amount}>
+        Get Quote
+      </button>
+
+      {quote && (
+        <div>
+          <p>Output: {(Number(quote.quote) / 1e6).toFixed(4)} USDC</p>
+          <p>USD value: ${quote.usdOut.toFixed(2)}</p>
+          <p>
+            Route:{' '}
+            {Object.entries(quote.flattenedRoute)
+              .map(([protocol, pct]) => `${protocol}: ${pct}%`)
+              .join(', ')}
+          </p>
+          <button onClick={executeSwap}>Execute Swap</button>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+## TanStack Query Integration
+
+For production UIs, use TanStack Query for auto-refreshing quotes and better state management.
+
+```bash
+npm install @tanstack/react-query
+```
+
+```tsx
+import { useState, useEffect, useMemo } from 'react'
+import {
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import { useWallet } from '@txnlab/use-wallet-react'
+import { RouterClient, type SwapQuote } from '@txnlab/haystack-router'
+
+const queryClient = new QueryClient()
+
+function SwapWithAutoRefresh() {
+  const { activeAddress, transactionSigner } = useWallet()
+  const [amount, setAmount] = useState('')
+  const [debouncedAmount, setDebouncedAmount] = useState('')
+  const [fromAsset] = useState(0)
+  const [toAsset] = useState(31566704)
+  const [slippage] = useState(1)
+
+  // Debounce amount input (500ms)
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedAmount(amount), 500)
+    return () => clearTimeout(timer)
+  }, [amount])
+
+  const router = useMemo(
+    () =>
+      new RouterClient({
+        apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+        autoOptIn: true,
+      }),
+    [],
+  )
+
+  const isValidRequest =
+    activeAddress && debouncedAmount && parseFloat(debouncedAmount) > 0
+
+  // Auto-fetch and refresh quotes
+  const {
+    data: quote,
+    error,
+    isLoading,
+  } = useQuery({
+    queryKey: ['quote', fromAsset, toAsset, debouncedAmount, activeAddress],
+    queryFn: () =>
+      router.newQuote({
+        fromASAID: fromAsset,
+        toASAID: toAsset,
+        amount: BigInt(Math.floor(parseFloat(debouncedAmount) * 1_000_000)),
+        address: activeAddress!,
+      }),
+    enabled: !!isValidRequest,
+    refetchInterval: 15_000, // Refresh every 15 seconds
+    retry: 1,
+  })
+
+  // Swap mutation
+  const swapMutation = useMutation({
+    mutationFn: async () => {
+      if (!quote || !activeAddress) throw new Error('Missing quote or address')
+
+      const swap = await router.newSwap({
+        quote,
+        address: activeAddress,
+        signer: transactionSigner,
+        slippage,
+      })
+      return swap.execute()
+    },
+    onSuccess: (result) => {
+      console.log(`Confirmed in round ${result.confirmedRound}`)
+      queryClient.invalidateQueries({ queryKey: ['quote'] })
+    },
+  })
+
+  return (
+    <div>
+      <input
+        type="number"
+        value={amount}
+        onChange={(e) => setAmount(e.target.value)}
+        placeholder="Amount"
+      />
+
+      {isLoading && <p>Fetching quote...</p>}
+      {error && <p>Error: {(error as Error).message}</p>}
+
+      {quote && (
+        <div>
+          <p>Output: {(Number(quote.quote) / 1e6).toFixed(4)} USDC</p>
+          <p>USD: ${quote.usdOut.toFixed(2)}</p>
+          <button
+            onClick={() => swapMutation.mutate()}
+            disabled={swapMutation.isPending}
+          >
+            {swapMutation.isPending ? 'Swapping...' : 'Swap'}
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+Key patterns:
+
+- **Debounced input**: Prevent quote requests on every keystroke
+- **Auto-refresh**: `refetchInterval: 15_000` keeps quotes current
+- **Invalidation**: Clear stale quotes after a successful swap
+- **Loading/error states**: TanStack Query manages all async state
+
+## Displaying Route Details
+
+```tsx
+function RouteDisplay({ quote }: { quote: SwapQuote }) {
+  return (
+    <div>
+      <h4>Route</h4>
+      {quote.route.map((route, i) => (
+        <div key={i}>
+          <strong>{route.percentage}%</strong>
+          {route.path.map((hop, j) => (
+            <span key={j}>
+              {j > 0 && ' → '}
+              {hop.in.unit_name} → {hop.out.unit_name} ({hop.name})
+            </span>
+          ))}
+        </div>
+      ))}
+      {quote.userPriceImpact !== undefined && (
+        <p>Price impact: {quote.userPriceImpact.toFixed(2)}%</p>
+      )}
+    </div>
+  )
+}
+```