@goplausible/openclaw-algorand-plugin 1.0.2 → 1.2.0

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

@@ -0,0 +1,184 @@
+# Configuration (SDK)
+
+## API Key Tiers
+
+| Tier           | Key                                    | Rate Limit      | Use Case                                      |
+| -------------- | -------------------------------------- | --------------- | --------------------------------------------- |
+| **Free**       | `1b72df7e-1131-4449-8ce1-29b79dd3f51e` | 60 requests/min | Development, testing, low-volume integrations |
+| **Production** | Request from support@txnlab.dev        | Higher limits   | Production applications                       |
+
+The free tier key requires no registration and works immediately. The rate limit applies to all API calls (both `fetchQuote` and `fetchExecuteSwapTxns`), not just quotes.
+
+For production integrations with higher rate limits, contact support@txnlab.dev for a dedicated key.
+
+## RouterClient Options
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+const router = new RouterClient({
+  // Required
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+
+  // Optional
+  apiBaseUrl: undefined, // Override API endpoint (SDK manages defaults)
+  algodUri: undefined, // Algod node URI (default: MainNet via Nodely)
+  algodToken: undefined, // Algod node token
+  algodPort: undefined, // Algod node port (default: 443)
+  referrerAddress: undefined, // Earn 25% of swap fees
+  feeBps: undefined, // Fee in basis points (default: 10, max: 300)
+  autoOptIn: false, // Auto-detect asset opt-in needs
+  debugLevel: 'none', // Logging: 'none' | 'info' | 'debug' | 'trace'
+  middleware: [], // SwapMiddleware plugins
+})
+```
+
+## Network Configuration
+
+### MainNet (Default)
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e',
+})
+```
+
+Uses default Nodely MainNet algod endpoint.
+
+### TestNet
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  algodUri: 'https://testnet-api.4160.nodely.dev/',
+})
+```
+
+### Custom Algod Node
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  algodUri: 'http://localhost:4001',
+  algodToken:
+    'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  algodPort: 4001,
+})
+```
+
+## Slippage
+
+Slippage is a percentage tolerance on the output amount. Set per-swap, not on the client.
+
+```typescript
+const swap = await router.newSwap({
+  quote,
+  address,
+  signer,
+  slippage: 1, // 1% — receive at least 99% of quoted output
+})
+```
+
+**Recommendations:**
+
+- **Stable pairs** (ALGO/USDC): 0.5–1%
+- **Volatile pairs**: 1–3%
+- **Low liquidity**: 3–5%
+
+Slippage is verified on the **final output** of the swap, not on individual hops. This means intermediate steps can have higher variance as long as the final result is within tolerance.
+
+## Fee Configuration
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  feeBps: 15, // 0.15% output fee
+})
+```
+
+- **Default**: 10 bps (0.10%)
+- **Range**: 10–300 bps (0.10%–3.00%)
+- Fee is applied to the **output amount**
+- Additional network transaction fees apply (paid by swapper)
+
+## Referrer Address
+
+Earn 25% of swap fees by setting a referrer address:
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  referrerAddress: 'YOUR_ALGORAND_ADDRESS',
+})
+```
+
+See [fees-and-referrals.md](fees-and-referrals.md) for details on the referral program.
+
+## Auto Opt-In
+
+When `autoOptIn: true`, the SDK automatically checks if the user needs to opt into the output asset and includes the opt-in transaction in the swap group.
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  autoOptIn: true,
+})
+
+// Address is required for auto opt-in detection
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000,
+  address: activeAddress,
+})
+```
+
+## Middleware
+
+Plugins that hook into the quote and swap lifecycle:
+
+```typescript
+import { RouterClient, AutoOptOutMiddleware } from '@txnlab/haystack-router'
+
+// Built-in: auto opt-out when swapping full balance
+const autoOptOut = new AutoOptOutMiddleware({
+  excludedAssets: [31566704], // Never auto-opt-out of USDC
+})
+
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  middleware: [autoOptOut],
+})
+```
+
+See [api-reference.md](api-reference.md) for the `SwapMiddleware` interface.
+
+## Debug Logging
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  debugLevel: 'info',
+})
+```
+
+| Level   | Output                                                             |
+| ------- | ------------------------------------------------------------------ |
+| `none`  | No logging (default)                                               |
+| `info`  | High-level operations (quote fetched, swap submitted)              |
+| `debug` | Detailed flow (middleware applied, validation, status transitions) |
+| `trace` | Everything including request/response payloads                     |
+
+## Finding ASA IDs
+
+Common Algorand Standard Asset IDs:
+
+| Asset | ASA ID    |
+| ----- | --------- |
+| ALGO  | 0         |
+| USDC  | 31566704  |
+| USDt  | 312769    |
+| goBTC | 386192725 |
+| goETH | 386195940 |
+
+Look up ASA IDs on [Allo.info](https://allo.info) or [Pera Explorer](https://explorer.perawallet.app/).

package/skills/haystack-router-development/references/fees-and-referrals.md

@@ -0,0 +1,91 @@
+# Fees and Referrals
+
+## Fee Structure
+
+### Swap Fees
+
+- **Default fee**: 10 basis points (0.10%) on the **output** amount
+- **Configurable**: 10–300 bps via the `feeBps` parameter
+- **Positive slippage**: When a swap executes better than quoted, the excess is captured as additional revenue
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  feeBps: 15, // 0.15%
+})
+```
+
+### Network Fees
+
+Swappers pay all Algorand network transaction fees (min fee per transaction in the group). These are separate from the protocol output fee.
+
+### Fee Distribution
+
+| Recipient | Share |
+| --------- | ----- |
+| Protocol  | 75%   |
+| Referrer  | 25%   |
+
+## Referral Program
+
+Integrators earn **25% of swap fees** generated by their users.
+
+### Setup
+
+Pass your Algorand address as the `referrerAddress` when creating the RouterClient:
+
+```typescript
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+  referrerAddress: 'YOUR_ALGORAND_ADDRESS',
+})
+```
+
+Every swap executed through this client generates referral commissions.
+
+### How It Works
+
+1. Fees from each swap are deposited into an **escrow account** linked to your referrer address
+2. The escrow is an on-chain account **rekeyed to the protocol app** — only your address can claim from it
+3. When new assets are swapped, the escrow automatically opts into them
+4. Commissions accumulate across all assets traded
+
+### Claiming Commissions
+
+Claim accumulated commissions through the referrer dashboard:
+
+- **Dashboard**: Register and claim at the referrer portal
+- **Bulk claim**: Withdraw multiple asset commissions simultaneously
+- **Single claim**: Withdraw a specific asset, optionally closing out the position
+
+### Auto-Conversion (Optional)
+
+Optionally convert accumulated commissions to a target asset (ALGO, USDC, etc.):
+
+- **Disabled by default** — requires explicit opt-in
+- **1% convenience fee** on auto-conversion swaps
+- Runs daily when enabled
+- Select any target asset for conversion
+- Can be enabled/disabled at any time
+
+### Referral Escrow Details
+
+- Each referrer gets a unique escrow account
+- Escrow is **permanently linked** once created (cannot be unlinked)
+- The escrow is controlled by the protocol smart contract
+- Only the linked referrer address can claim funds
+- Minimum 0.257 ALGO required for escrow Minimum Balance Requirement (MBR)
+
+## Protocol Contracts
+
+### MainNet (Latest: V2.2)
+
+- **Application ID**: 3172554435
+- **Contract Address**: `ESPO2SMA5BPAAAFAN66EFNHGR3HJ63U2OYM6RJXSEP6YOBU4HJTWZG7D5A`
+
+### Security
+
+The protocol has been audited by:
+
+- **Ulam Labs** (April 2023)
+- **Vantage Point** (November 2022)

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)
+```