@goplausible/openclaw-algorand-plugin 1.1.0 → 1.2.0

package/openclaw.plugin.json

@@ -2,14 +2,16 @@
   "id": "openclaw-algorand-plugin",
   "name": "Algorand Integration",
   "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",
     "skills/algorand-python",
     "skills/algorand-interaction",
     "skills/algorand-x402-typescript",
-    "skills/algorand-x402-python"
+    "skills/algorand-x402-python",
+    "skills/haystack-router-development",
+    "skills/haystack-router-interaction"
   ],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/openclaw-algorand-plugin",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "publishConfig": {
     "access": "public"
   },

package/skills/algorand-interaction/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: algorand-interaction
-description: Interact with Algorand blockchain via the Algorand MCP server — wallet operations, ALGO/ASA transactions, smart contracts, account info, NFD lookups, atomic groups, Tinyman swaps, TEAL compilation, knowledge base. Use when user asks about Algorand wallet, balances, sending ALGO or tokens, asset opt-in, transactions, NFD names, DEX swaps, smart contracts, or account details.
+description: Interact with Algorand blockchain via the Algorand MCP server — wallet operations, ALGO/ASA transactions, smart contracts, account info, NFD lookups, atomic groups, Tinyman swaps, Haystack Router DEX-aggregated swaps, TEAL compilation, knowledge base. Use when user asks about Algorand wallet, balances, sending ALGO or tokens, asset opt-in, transactions, NFD names, DEX swaps, smart contracts, or account details.
 ---
 
 # Algorand MCP Interaction
 
-Interact with Algorand blockchain through the Algorand MCP server (99 tools across 11 categories).
+Interact with Algorand blockchain through the Algorand MCP server (101+ tools across 12 categories).
 
 ## Key Characteristics
 
@@ -160,6 +160,8 @@ For atomic (all-or-nothing) multi-transaction groups:
 
 **Tinyman DEX** (9): `api_tinyman_get_pool`, `api_tinyman_get_pool_analytics`, `api_tinyman_get_pool_creation_quote`, `api_tinyman_get_liquidity_quote`, `api_tinyman_get_remove_liquidity_quote`, `api_tinyman_get_swap_quote`, `api_tinyman_get_asset_optin_quote`, `api_tinyman_get_validator_optin_quote`, `api_tinyman_get_validator_optout_quote`
 
+**Haystack Router** (3): `api_haystack_get_swap_quote`, `api_haystack_execute_swap`, `api_haystack_needs_optin` — DEX-aggregated swaps across Tinyman V2, Pact, Folks with optimal routing. See the **haystack-router-interaction** skill for detailed workflows and reference docs.
+
 **ARC-26 URI** (1): `generate_algorand_uri`
 
 **Knowledge Base** (1): `get_knowledge_doc`

package/skills/algorand-interaction/references/algorand-mcp.md

@@ -14,8 +14,9 @@
 7. [Indexer API Tools](#indexer-api-tools)
 8. [NFDomains API Tools](#nfdomains-api-tools)
 9. [Tinyman DEX API Tools](#tinyman-dex-api-tools)
-10. [ARC-26 URI Tools](#arc-26-uri-tools)
-11. [Knowledge Base Tools](#knowledge-base-tools)
+10. [Haystack Router Tools](#haystack-router-tools)
+11. [ARC-26 URI Tools](#arc-26-uri-tools)
+12. [Knowledge Base Tools](#knowledge-base-tools)
 
 ---
 
@@ -691,6 +692,52 @@ Decentralized exchange operations on Tinyman AMM.
 
 ---
 
+## Haystack Router Tools
+
+DEX-aggregated swaps across Tinyman V2, Pact, and Folks with smart order routing. For detailed workflows and the full SDK guide, see the **haystack-router-interaction** and **haystack-router-development** skills.
+
+### api_haystack_get_swap_quote
+- **Purpose**: Get an optimized swap quote across multiple DEXes without executing
+- **Parameters**:
+```json
+{
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "type": "fixed-input",
+  "address": "optional — enables opt-in detection",
+  "maxGroupSize": 16,
+  "maxDepth": 4,
+  "network": "mainnet"
+}
+```
+- **Returns**: `expectedOutput`, `inputAmount`, `usdIn`, `usdOut`, `userPriceImpact`, `route`, `flattenedRoute`, `requiredAppOptIns`, `protocolFees`
+
+### api_haystack_execute_swap
+- **Purpose**: All-in-one swap: quote → sign (via wallet) → submit → confirm. Enforces wallet spending limits.
+- **Parameters**:
+```json
+{
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "slippage": 1,
+  "type": "fixed-input",
+  "note": "optional text note",
+  "maxGroupSize": 16,
+  "maxDepth": 4,
+  "network": "mainnet"
+}
+```
+- **Returns**: `status`, `confirmedRound`, `txIds`, `signer`, `nickname`, quote details, `summary` (inputAmount, outputAmount, totalFees, transactionCount)
+
+### api_haystack_needs_optin
+- **Purpose**: Check if an address needs to opt into an asset before swapping
+- **Parameters**: `{ "address": "ALGO_ADDRESS", "assetId": 31566704, "network": "mainnet" }`
+- **Returns**: `{ address, assetId, needsOptIn: true/false, network }`
+
+---
+
 ## ARC-26 URI Tools
 
 ### generate_algorand_uri

package/skills/algorand-interaction/references/examples-algorand-mcp.md

@@ -398,6 +398,55 @@ api_tinyman_get_pool {
 
 ---
 
+## Haystack Router Swap (DEX-Aggregated)
+
+Best-price swap across multiple DEXes (Tinyman V2, Pact, Folks). For detailed reference, see the **haystack-router-interaction** skill.
+
+### Step 1: Check wallet
+```
+wallet_get_info { "network": "mainnet" }
+```
+
+### Step 2: Check opt-in (if swapping to an ASA)
+```
+api_haystack_needs_optin {
+  "address": "[wallet_address]",
+  "assetId": 31566704,
+  "network": "mainnet"
+}
+```
+If `needsOptIn: true`:
+```
+wallet_optin_asset { "assetId": 31566704, "network": "mainnet" }
+```
+
+### Step 3: Get a quote (show user before executing)
+```
+api_haystack_get_swap_quote {
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "type": "fixed-input",
+  "address": "[wallet_address]",
+  "network": "mainnet"
+}
+```
+> Present to user: expected output, USD values, route, price impact.
+
+### Step 4: Execute swap (after user confirms)
+```
+api_haystack_execute_swap {
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "slippage": 1,
+  "network": "mainnet"
+}
+```
+> Signs via wallet, submits, and confirms atomically. Returns confirmed round and tx IDs.
+
+---
+
 ## Using the Knowledge Base
 
 ### Get a specific document

package/skills/haystack-router-development/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: haystack-router-development
+description: Comprehensive guide for building applications with Haystack Router SDK (@txnlab/haystack-router) — a DEX aggregator and smart order routing protocol on Algorand. Use when developing swap UIs with React and use-wallet, writing Node.js automation scripts, integrating RouterClient for quotes and swaps, or working with the SDK API surface, middleware, fees, and referral program. Strong triggers include haystack router, @txnlab/haystack-router, RouterClient, DEX aggregator, swap UI, swap React, newQuote, newSwap, deflex migration, haystack SDK, swap routing, best price swap.
+---
+
+# Haystack Router (Development)
+
+This is the parent skill for building applications that integrate the `@txnlab/haystack-router` SDK — React swap UIs, Node.js automation scripts, custom signing flows, middleware, and direct RouterClient usage. No Algorand MCP tools are involved.
+
+> **Want to execute swaps** through the Algorand MCP server instead of building an app? Use the **haystack-router-interaction** skill — it provides Algorand MCP tools for quoting, swapping, and opt-in checking with wallet-based signing.
+> **Need Algorand blockchain interaction guidance?** See the **algorand-interaction** skill for wallet setup, transaction workflows, and MCP tool reference.
+
+Haystack Router is a DEX aggregator and smart order routing protocol on Algorand. It finds optimal swap routes across multiple DEXes (Tinyman V2, Pact, Folks) and LST protocols (tALGO, xALGO), then executes them atomically through on-chain smart contracts.
+
+## Package
+
+`@txnlab/haystack-router` — TypeScript SDK for DEX-aggregated swaps. Requires `algosdk` (v3+) as a peer dependency.
+
+```bash
+npm install @txnlab/haystack-router algosdk
+```
+
+**API key required.** A free tier key is available for immediate use — see [configuration.md](references/configuration.md) for details.
+
+## SDK Core Flow
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+// 1. Initialize
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+
+// 2. Get a quote
+const quote = await router.newQuote({
+  fromASAID: 0, // ALGO
+  toASAID: 31566704, // USDC
+  amount: 1_000_000, // 1 ALGO (base units)
+  address: activeAddress,
+})
+
+// 3. 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%
+})
+const result = await swap.execute()
+```
+
+The SDK is the **only** supported integration path. Do not call the API directly.
+
+## Key Concepts
+
+- **Amounts** are always in base units (microAlgos for ALGO, smallest unit for ASAs)
+- **ASA IDs**: 0 = ALGO, 31566704 = USDC, etc.
+- **Quote types**: `fixed-input` (default) — specify input amount; `fixed-output` — specify desired output
+- **Slippage**: Percentage tolerance on output (e.g., 1 = 1%). Applied to the final output, not individual hops
+- **Routing**: Supports multi-hop and parallel (combo) swaps for optimal pricing
+- **Middleware**: Plugin system for custom pre/post-swap transactions (e.g., auto opt-out)
+
+## Reference Files
+
+Read the appropriate file based on the task:
+
+| Task                                    | Reference                                               |
+| --------------------------------------- | ------------------------------------------------------- |
+| Install SDK, initialize RouterClient    | [getting-started.md](references/getting-started.md)     |
+| Get swap quotes, display pricing        | [quotes.md](references/quotes.md)                       |
+| Execute swaps with SDK signing          | [swaps.md](references/swaps.md)                         |
+| Build React swap UI with use-wallet     | [react-integration.md](references/react-integration.md) |
+| Automate swaps via Node.js scripts      | [node-automation.md](references/node-automation.md)     |
+| RouterClient config, middleware, debug  | [configuration.md](references/configuration.md)         |
+| Fee structure, referral program         | [fees-and-referrals.md](references/fees-and-referrals.md) |
+| Full API surface and types              | [api-reference.md](references/api-reference.md)         |
+| Migrate from @txnlab/deflex             | [migration.md](references/migration.md)                 |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the topic `.md`** file for step-by-step guidance
+3. **For MCP-based swaps** (no SDK), see the `haystack-router-interaction` skill
+4. **For general Algorand development**, see `algorand-development`, `algorand-typescript`, or `algorand-python` skills

package/skills/haystack-router-development/references/api-reference.md

@@ -0,0 +1,381 @@
+# API Reference
+
+## Table of Contents
+
+- [RouterClient](#routerclient)
+- [SwapComposer](#swapcomposer)
+- [SwapMiddleware](#swapmiddleware)
+- [Types](#types)
+
+## RouterClient
+
+### Constructor
+
+```typescript
+new RouterClient(config: ConfigParams & { middleware?: SwapMiddleware[] })
+```
+
+**ConfigParams:**
+
+| Property          | Type               | Default        | Description                              |
+| ----------------- | ------------------ | -------------- | ---------------------------------------- |
+| `apiKey`          | `string`           | —              | **Required.** API key                    |
+| `apiBaseUrl`      | `string`           | SDK default    | API endpoint override                    |
+| `algodUri`        | `string`           | MainNet Nodely | Algod node URI                           |
+| `algodToken`      | `string`           | `''`           | Algod node token                         |
+| `algodPort`       | `string \| number` | `443`          | Algod node port                          |
+| `referrerAddress` | `string`           | —              | Earn 25% of swap fees                    |
+| `feeBps`          | `number`           | `10`           | Fee in basis points (10–300)             |
+| `autoOptIn`       | `boolean`          | `false`        | Auto-detect asset opt-in                 |
+| `debugLevel`      | `string`           | `'none'`       | `'none' \| 'info' \| 'debug' \| 'trace'` |
+
+### newQuote()
+
+```typescript
+async newQuote(params: FetchQuoteParams): Promise<SwapQuote>
+```
+
+Get an optimized swap quote with enhanced types (bigint coercion, timestamps).
+
+### fetchQuote()
+
+```typescript
+async fetchQuote(params: FetchQuoteParams): Promise<FetchQuoteResponse>
+```
+
+Get a raw swap quote without SwapQuote enhancements.
+
+### newSwap()
+
+```typescript
+async newSwap(config: {
+  quote: SwapQuote | FetchQuoteResponse
+  address: string
+  signer: TransactionSigner | SignerFunction
+  slippage: number
+  note?: Uint8Array
+}): Promise<SwapComposer>
+```
+
+Create a swap composer for building and executing the swap transaction group.
+
+### needsAssetOptIn()
+
+```typescript
+async needsAssetOptIn(address: string, assetId: number | bigint): Promise<boolean>
+```
+
+Check if an address needs to opt into an asset. Always returns `false` for ALGO (ASA 0).
+
+### fetchSwapTransactions()
+
+```typescript
+async fetchSwapTransactions(params: FetchSwapTxnsParams): Promise<FetchSwapTxnsResponse>
+```
+
+Low-level: fetch executable swap transactions. Typically called internally by `newSwap()`.
+
+---
+
+## SwapComposer
+
+Returned by `router.newSwap()`. Builder pattern for transaction groups.
+
+### execute()
+
+```typescript
+async execute(waitRounds?: number): Promise<{
+  confirmedRound: bigint
+  txIds: string[]
+  methodResults: ABIResult[]
+}>
+```
+
+Sign, submit, and wait for confirmation. `waitRounds` defaults to 10.
+
+### buildGroup()
+
+```typescript
+buildGroup(): TransactionWithSigner[]
+```
+
+Finalize the transaction group and assign group IDs.
+
+### sign()
+
+```typescript
+async sign(): Promise<Uint8Array[]>
+```
+
+Sign all transactions. Auto-adds swap transactions if not already added.
+
+### submit()
+
+```typescript
+async submit(): Promise<string[]>
+```
+
+Sign and submit without waiting for confirmation. Returns transaction IDs.
+
+### addTransaction()
+
+```typescript
+addTransaction(transaction: Transaction, signer?: TransactionSigner): this
+```
+
+Add a custom transaction to the group. Chainable. Must be called before `buildGroup()`.
+
+### addMethodCall()
+
+```typescript
+addMethodCall(methodCall: MethodCall, signer?: TransactionSigner): this
+```
+
+Add an ABI method call to the group. Chainable.
+
+### addSwapTransactions()
+
+```typescript
+async addSwapTransactions(): Promise<this>
+```
+
+Manually add swap transactions (including middleware hooks and app opt-ins). Called automatically by `execute()` if not called explicitly.
+
+### getSummary()
+
+```typescript
+getSummary(): SwapSummary | undefined
+```
+
+Get exact swap amounts after execution. Only available after `execute()`.
+
+### getInputTransactionId()
+
+```typescript
+getInputTransactionId(): string | undefined
+```
+
+Get the user-signed input transaction ID. Available after `buildGroup()`.
+
+### getStatus()
+
+```typescript
+getStatus(): SwapComposerStatus
+```
+
+Returns: `BUILDING` (0) → `BUILT` (1) → `SIGNED` (2) → `SUBMITTED` (3) → `COMMITTED` (4)
+
+### count()
+
+```typescript
+count(): number
+```
+
+Number of transactions in the group.
+
+---
+
+## SwapMiddleware
+
+Interface for plugins that hook into the quote and swap lifecycle.
+
+```typescript
+interface SwapMiddleware {
+  readonly name: string
+  readonly version: string
+
+  shouldApply(context: QuoteContext): Promise<boolean>
+  adjustQuoteParams?(params: FetchQuoteParams): Promise<FetchQuoteParams>
+  beforeSwap?(context: SwapContext): Promise<TransactionWithSigner[]>
+  afterSwap?(context: SwapContext): Promise<TransactionWithSigner[]>
+}
+```
+
+### Built-in: AutoOptOutMiddleware
+
+Automatically opts out of assets when swapping full balance.
+
+```typescript
+import { AutoOptOutMiddleware } from '@txnlab/haystack-router'
+
+const middleware = new AutoOptOutMiddleware({
+  excludedAssets?: readonly (number | bigint)[]  // Assets to never auto-opt-out
+})
+```
+
+### QuoteContext
+
+```typescript
+interface QuoteContext {
+  fromASAID: bigint
+  toASAID: bigint
+  amount: bigint
+  type: QuoteType
+  address?: string
+  algodClient: Algodv2
+}
+```
+
+### SwapContext
+
+```typescript
+interface SwapContext {
+  quote: SwapQuote
+  address: string
+  algodClient: Algodv2
+  suggestedParams: SuggestedParams
+  fromASAID: bigint
+  toASAID: bigint
+  signer: TransactionSigner
+}
+```
+
+---
+
+## Types
+
+### FetchQuoteParams
+
+```typescript
+interface FetchQuoteParams {
+  fromASAID: bigint | number
+  toASAID: bigint | number
+  amount: bigint | number
+  type?: 'fixed-input' | 'fixed-output' // Default: 'fixed-input'
+  address?: string | null
+  disabledProtocols?: readonly Protocol[]
+  maxGroupSize?: number // Default: 16
+  maxDepth?: number // Default: 4
+  optIn?: boolean
+}
+```
+
+### FetchQuoteResponse
+
+```typescript
+interface FetchQuoteResponse {
+  quote: string | number
+  profit: Profit // { amount: number, asa: Asset }
+  priceBaseline: number
+  userPriceImpact?: number
+  marketPriceImpact?: number
+  usdIn: number
+  usdOut: number
+  route: Route[]
+  flattenedRoute: Record<string, number>
+  quotes: DexQuote[]
+  requiredAppOptIns: number[]
+  txnPayload: TxnPayload | null
+  protocolFees: Record<string, number>
+  fromASAID: number
+  toASAID: number
+  type: string
+}
+```
+
+### SwapQuote
+
+```typescript
+type SwapQuote = FetchQuoteResponse & {
+  quote: bigint // Coerced to bigint
+  amount: bigint // Original request amount
+  address?: string
+  createdAt: number // Timestamp (ms)
+}
+```
+
+### SwapSummary
+
+```typescript
+interface SwapSummary {
+  inputAssetId: bigint
+  outputAssetId: bigint
+  inputAmount: bigint
+  outputAmount: bigint
+  type: QuoteType
+  totalFees: bigint // microAlgos
+  transactionCount: number
+  inputTxnId: string
+  outputTxnId: string
+  inputSender: string
+  outputSender: string
+}
+```
+
+### SwapTransaction
+
+```typescript
+interface SwapTransaction {
+  data: string // Base64-encoded transaction
+  group: string // Group ID
+  logicSigBlob: unknown | false
+  signature: Signature | false
+}
+```
+
+### SignerFunction
+
+```typescript
+type SignerFunction = (
+  txnGroup: Transaction[],
+  indexesToSign: number[],
+) => Promise<(Uint8Array | null)[]>
+```
+
+Supports two return patterns:
+
+- `Uint8Array[]` matching `indexesToSign` length (Pera/Defly)
+- `(Uint8Array | null)[]` matching full group length (Lute/ARC-1)
+
+### Route and PathElement
+
+```typescript
+interface Route {
+  percentage: number
+  path: PathElement[]
+}
+
+interface PathElement {
+  name: string // Protocol name + fee tier
+  class: string[][]
+  in: Asset
+  out: Asset
+}
+```
+
+### Asset
+
+```typescript
+interface Asset {
+  id: number
+  decimals: number
+  unit_name: string
+  name: string
+  price_algo: number
+  price_usd: number
+}
+```
+
+### Protocol
+
+```typescript
+enum Protocol {
+  TinymanV2 = 'TinymanV2'
+  Algofi = 'Algofi'
+  Algomint = 'Algomint'
+  Pact = 'Pact'
+  Folks = 'Folks'
+  TAlgo = 'TAlgo'
+}
+```
+
+### Constants
+
+```typescript
+const DEFAULT_FEE_BPS = 10 // 0.10%
+const MAX_FEE_BPS = 300 // 3.00%
+const DEFAULT_MAX_GROUP_SIZE = 16
+const DEFAULT_MAX_DEPTH = 4
+const DEFAULT_AUTO_OPT_IN = false
+const DEFAULT_CONFIRMATION_ROUNDS = 10
+```