@goplausible/openclaw-algorand-plugin 1.1.0 → 1.3.0

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

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)