@symmetry-hq/sdk 1.0.8 → 1.0.9

package/LICENSE

@@ -0,0 +1,41 @@
+Business Source License 1.1
+
+Licensor:  Symmetry Protocol
+Licensed Work:  @symmetry-hq/sdk
+Change Date:  None
+Change License:  None
+
+Additional Use Grant
+
+You may use the Licensed Work in production, including for commercial purposes,
+to build applications, services, and products that integrate with the Symmetry
+Protocol.
+
+You may NOT use the Licensed Work to create a competing SDK, library, or
+protocol infrastructure that replicates or substitutes the functionality of the
+Licensed Work or the Symmetry Protocol.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Except for the Additional Use Grant and the right of non-production use, all
+rights in the Licensed Work remain exclusively with the Licensor.
+
+If the Licensor specifies a Change Date, the Licensed Work will be made
+available under the Change License on the Change Date. No Change Date has been
+specified for this Licensed Work.
+
+Notice
+
+Business Source License 1.1 is not an Open Source license. However, the
+Licensed Work may eventually be made available under an Open Source License, as
+stated in this License.
+
+For the full text of the Business Source License 1.1, see:
+https://mariadb.com/bsl11/
+
+Copyright (c) 2026 Symmetry Protocol. All rights reserved.

package/README.md

@@ -0,0 +1,742 @@
+# @symmetry-hq/sdk
+
+TypeScript SDK for the **Symmetry V3** protocol on Solana — on-chain infrastructure for creating and managing multi-token vaults with automated rebalancing, oracle-based pricing, and permissionless keeper execution.
+
+[Documentation](https://docs.symmetry.fi) | [LLMs.txt](https://docs.symmetry.fi/llms.txt) | [App](https://beta.symmetry.fi) | [Discord](https://discord.gg/Bvgt87KTJB)
+
+Have questions or need help integrating? [Join our Discord](https://discord.gg/Bvgt87KTJB).
+
+## Installation
+
+```bash
+npm install @symmetry-hq/sdk
+```
+
+### Peer Dependencies
+
+```bash
+npm install @solana/web3.js @coral-xyz/anchor
+```
+
+## Quick Start
+
+```typescript
+import { Connection } from "@solana/web3.js";
+import { SymmetryCore } from "@symmetry-hq/sdk";
+
+const connection = new Connection("https://api.mainnet-beta.solana.com");
+const sdk = new SymmetryCore({
+  connection,
+  network: "mainnet",
+  priorityFee: 50_000, // optional, micro-lamports (default: 25,000)
+});
+
+// Fetch all vaults
+const vaults = await sdk.fetchAllVaults();
+
+// Fetch a single vault and load its price
+let vault = await sdk.fetchVault("<VAULT_PUBKEY>");
+vault = await sdk.loadVaultPrice(vault);
+console.log(vault.formatted);
+```
+
+## Core Concepts
+
+### Vaults
+
+A vault is an on-chain account that holds a configurable set of SPL tokens with target weights. Each vault:
+
+- Holds multiple SPL tokens with individually configurable target weights
+- Mints its own SPL token — vault token holders have proportional ownership of the underlying tokens
+- Supports multi-source oracle pricing (Pyth, Raydium CPMM; Raydium CLMM and Switchboard are currently disabled) with configurable aggregation
+- Has a flexible fee structure (deposit, withdrawal, management, performance) split across creator, host platform, managers, and protocol. Management and performance fees are currently disabled at the protocol level.
+- Supports up to 100 tokens, 10 managers, and 4 oracle sources per token
+
+### Intents
+
+All configuration changes to a vault go through an **intent system**. An intent is an on-chain change request — editing fees, metadata, token composition, weights, etc. — with optional time-locks and bounty incentives for keepers to execute them.
+
+### Rebalance Intents
+
+Deposits, withdrawals, and periodic rebalances are processed through the same on-chain flow. They progress through a multi-step auction:
+
+1. **Deposit tokens** — user contributes tokens to the vault
+2. **Lock deposits** — freezes contributions and starts the process
+3. **Price updates** — oracle prices are refreshed on-chain
+4. **Auction** — keepers execute flash swaps to settle the vault toward target weights
+5. **Mint / Redeem** — vault tokens are minted (deposits) or underlying tokens are released (withdrawals)
+6. **Claim bounty** — keepers collect their rewards
+
+### Keepers
+
+Keepers are off-chain agents that monitor the protocol, execute pending tasks (intents, price updates, auctions), and earn bounties. All keeper operations are permissionless — developers can build custom keeper bots using the SDK's transaction-building methods. The SDK also ships with `KeeperMonitor` and `RebalanceHandler` as reference implementations that work out of the box.
+
+---
+
+## API Reference
+
+### Constructor
+
+```typescript
+const sdk = new SymmetryCore({
+  connection: Connection,     // Solana RPC connection
+  network: "devnet" | "mainnet",
+  priorityFee?: number,       // compute unit price in micro-lamports (default: 25,000)
+});
+```
+
+### Configuration
+
+#### `setPriorityFee(priorityFee: number): void`
+
+Updates the priority fee for all subsequent transactions.
+
+#### `fetchGlobalConfig(): Promise<GlobalConfig>`
+
+Returns the protocol-wide configuration account (fee limits, bounty settings, rebalance parameters).
+
+---
+
+### Fetching Vaults
+
+#### `fetchVault(vaultPubkey: string): Promise<Vault>`
+
+Fetch a single vault by its account public key.
+
+#### `fetchMultipleVaults(vaultPubkeys: string[]): Promise<Map<string, Vault>>`
+
+Batch-fetch multiple vaults. Returns a map keyed by public key.
+
+#### `fetchAllVaults(filter?: VaultFilter): Promise<Vault[]>`
+
+Fetch all vaults on-chain with an optional role filter:
+
+```typescript
+type VaultFilter = {
+  type: "creator" | "host" | "manager";
+  pubkey: string;
+};
+```
+
+#### `fetchCreatedVaults(creatorPubkey: string): Promise<Vault[]>`
+
+Fetch vaults created by a specific public key.
+
+#### `fetchHostedVaults(hostPubkey: string): Promise<Vault[]>`
+
+Fetch vaults hosted by a specific public key.
+
+#### `fetchManagedVaults(managerPubkey: string): Promise<Vault[]>`
+
+Fetch vaults managed by a specific public key.
+
+#### `fetchVaultsFromMints(mints: string[]): Promise<Map<string, Vault>>`
+
+Look up vaults by their SPL token mint addresses. Returns a map keyed by mint.
+
+#### `deriveVaultsByMints(mints: string[]): Promise<Map<string, string>>`
+
+Derive vault account addresses from mint addresses without RPC calls. Returns a mint-to-pubkey map.
+
+#### `loadVaultPrice(vault: Vault): Promise<Vault>`
+
+Loads live oracle prices for all tokens in the vault, computes the vault's total value, and returns the updated object.
+
+---
+
+### Fetching Intents
+
+#### `fetchIntent(intentPubkey: string): Promise<Intent>`
+
+Fetch a single intent by its public key.
+
+#### `fetchMultipleIntents(intentPubkeys: string[]): Promise<Map<string, Intent>>`
+
+Batch-fetch multiple intents.
+
+#### `fetchAllIntents(filter?: IntentFilter): Promise<Intent[]>`
+
+Fetch all intents with an optional filter:
+
+```typescript
+type IntentFilter = {
+  type: "manager" | "vault";
+  pubkey: string;
+};
+```
+
+#### `fetchCreatedIntents(creatorPubkey: string): Promise<Intent[]>`
+
+Fetch intents created by a specific manager.
+
+#### `fetchVaultIntents(vaultPubkey: string): Promise<Intent[]>`
+
+Fetch all intents for a specific vault.
+
+---
+
+### Fetching Rebalance Intents
+
+#### `fetchRebalanceIntent(pubkey: string): Promise<UIRebalanceIntent>`
+
+Fetch a single rebalance intent.
+
+#### `fetchMultipleRebalanceIntents(pubkeys: string[]): Promise<Map<string, UIRebalanceIntent>>`
+
+Batch-fetch multiple rebalance intents.
+
+#### `fetchAllRebalanceIntents(filter?: RebalanceIntentFilter): Promise<UIRebalanceIntent[]>`
+
+Fetch all rebalance intents with an optional filter:
+
+```typescript
+type RebalanceIntentFilter = {
+  type: "owner" | "vault";
+  pubkey: string;
+};
+```
+
+#### `fetchOwnerRebalanceIntents(ownerPubkey: string): Promise<UIRebalanceIntent[]>`
+
+Fetch rebalance intents owned by a specific public key.
+
+#### `fetchVaultRebalanceIntents(vaultPubkey: string): Promise<UIRebalanceIntent[]>`
+
+Fetch rebalance intents for a specific vault.
+
+---
+
+### Fetching Fee Accounts
+
+#### `fetchWithdrawVaultFees(pubkey: string): Promise<WithdrawVaultFees>`
+
+Fetch a single fee withdrawal account.
+
+#### `fetchMultipleWithdrawVaultFees(pubkeys: string[]): Promise<Map<string, WithdrawVaultFees>>`
+
+Batch-fetch multiple fee withdrawal accounts.
+
+#### `fetchAllWithdrawVaultFees(filter?: WithdrawVaultFeesFilter): Promise<WithdrawVaultFees[]>`
+
+Fetch all fee withdrawal accounts with an optional filter:
+
+```typescript
+type WithdrawVaultFeesFilter = {
+  type: "vault" | "manager" | "creator" | "host" | "symmetry";
+  pubkey: string;
+};
+```
+
+Convenience methods: `fetchVaultWithdrawVaultFees`, `fetchManagerWithdrawVaultFees`, `fetchCreatorWithdrawVaultFees`, `fetchHostWithdrawVaultFees`, `fetchSymmetryWithdrawVaultFees`.
+
+---
+
+### Creating Vaults
+
+#### `createVaultTx(params): Promise<VaultCreationTx>`
+
+Creates a new vault. Returns the vault's token mint, account address, and the transaction payload.
+
+The `metadata_uri` is a URL (max 200 chars) pointing to a JSON file describing the vault. It should contain `name` (vault token name), `symbol` (vault token ticker), `description` (vault description), `image` (token image/icon URL), and `cover` (vault cover image URL). You can add any extra fields for your own integrations (social links, website, etc.):
+```json
+{
+  "name": "My Vault",
+  "symbol": "MVT",
+  "description": "A multi-token vault.",
+  "image": "https://arweave.net/token-image-url",
+  "cover": "https://arweave.net/cover-image-url"
+}
+```
+
+```typescript
+const result = await sdk.createVaultTx({
+  creator: wallet.publicKey.toBase58(),
+  start_price: "1.0",    // initial price in USDC
+  name: "My Vault",
+  symbol: "MVT",
+  metadata_uri: "https://arweave.net/your-metadata-json",  // URL to JSON with name, symbol, description, image, cover
+  host_platform_params: {            // optional
+    host_pubkey: "<HOST_PUBKEY>",
+    host_deposit_fee_bps: 10,        // 0.1%
+    host_withdraw_fee_bps: 10,
+    host_management_fee_bps: 0,      // currently disabled in global config
+    host_performance_fee_bps: 0,     // currently disabled in global config
+  },
+});
+
+console.log("Vault mint:", result.mint);
+console.log("Vault account:", result.vault);
+
+await sdk.signAndSendTxPayloadBatchSequence({
+  txPayloadBatchSequence: result,
+  wallet,
+});
+```
+
+---
+
+### Editing Vault Settings
+
+All edit methods create an intent that modifies the vault. If the setting has no modification delay and no scheduled activation, the intent is executed immediately in the same transaction.
+
+Each method accepts a `TaskContext` and a settings object, returning a `TxPayloadBatchSequence`:
+
+```typescript
+interface TaskContext {
+  vault: string;               // vault public key
+  manager: string;             // authorized manager public key
+  activation_timestamp?: number; // optional scheduled activation (unix seconds)
+  expiration_timestamp?: number; // optional expiration
+  min_bounty?: number;         // optional min bounty override
+  max_bounty?: number;         // optional max bounty override
+}
+```
+
+| Method | Settings Type | Description |
+|--------|--------------|-------------|
+| `editCreatorTx` | `EditCreatorSettings` | Transfer vault creator role |
+| `editManagersTx` | `EditManagerSettings` | Edit managers, weights, and authority bitmasks |
+| `editFeesTx` | `EditFeeSettings` | Update fee structure |
+| `editScheduleTx` | `EditScheduleSettings` | Configure repeating time cycles that gate deposits, automation, and management windows |
+| `editAutomationTx` | `EditAutomationSettings` | Configure rebalance automation |
+| `editLpTx` | `EditLpSettings` | Configure LP settings |
+| `editMetadataTx` | `EditMetadataSettings` | Update name, symbol, and metadata URI (JSON with name, symbol, description, image, cover) |
+| `editDepositsTx` | `EditDepositsSettings` | Enable or disable deposits |
+| `editForceRebalanceTx` | `EditForceRebalanceSettings` | Enable or disable force rebalance |
+| `editCustomRebalanceTx` | `EditCustomRebalanceSettings` | Enable or disable custom rebalance |
+| `editAddTokenDelayTx` | `EditAddTokenSettings` | Set time-lock for adding tokens |
+| `editUpdateWeightsDelayTx` | `EditUpdateWeightsSettings` | Set time-lock for weight updates |
+| `editSwapDelayTx` | `EditMakeDirectSwapSettings` | Set time-lock for direct swaps |
+
+#### Token Composition
+
+#### `addOrEditTokenTx(context: TaskContext, settings: AddOrEditTokenInput): Promise<TxPayloadBatchSequence>`
+
+Add a new token to the vault or update an existing token's oracle configuration:
+
+```typescript
+const tx = await sdk.addOrEditTokenTx(
+  { vault: "<VAULT_PUBKEY>", manager: "<MANAGER>" },
+  {
+    token_mint: "<TOKEN_MINT>",
+    active: true,
+    min_oracles_thresh: 1,
+    min_conf_bps: 10,
+    conf_thresh_bps: 200,
+    conf_multiplier: 1.0,
+    oracles: [
+      {
+        oracle_type: "pyth",
+        account_lut_id: 0,
+        account_lut_index: 0,
+        account: "<PYTH_PRICE_ACCOUNT>",
+        weight_bps: 10000,
+        is_required: true,
+        conf_thresh_bps: 200,
+        volatility_thresh_bps: 200,
+        max_slippage_bps: 1000,
+        min_liquidity: 0,
+        staleness_thresh: 120,
+        staleness_conf_rate_bps: 50,
+        token_decimals: 9,
+        twap_seconds_ago: 0,
+        twap_secondary_seconds_ago: 0,
+        quote_token: "usd",
+      },
+    ],
+  }
+);
+```
+
+#### `updateWeightsTx(context: TaskContext, settings: UpdateWeightsInput): Promise<TxPayloadBatchSequence>`
+
+Update target weights for all tokens in the vault:
+
+```typescript
+const tx = await sdk.updateWeightsTx(
+  { vault: "<VAULT_PUBKEY>", manager: "<MANAGER>" },
+  {
+    token_weights: [
+      { mint: "<TOKEN_MINT_1>", weight_bps: 5000 },
+      { mint: "<TOKEN_MINT_2>", weight_bps: 3000 },
+      { mint: "<TOKEN_MINT_3>", weight_bps: 2000 },
+    ], // basis points, must sum to 10000
+  }
+);
+```
+
+#### `makeDirectSwapTx(context, settings, jup_swap_ix?): Promise<TxPayloadBatchSequence>`
+
+Execute a direct token swap within the vault via Jupiter.
+
+---
+
+### Intent Execution & Cancellation
+
+#### `executeVaultIntentTx(params): Promise<TxPayloadBatchSequence>`
+
+Execute a pending intent after its time-lock has elapsed:
+
+```typescript
+await sdk.executeVaultIntentTx({
+  keeper: wallet.publicKey.toBase58(),
+  intent: "<INTENT_PUBKEY>",
+});
+```
+
+#### `executeDirectSwapVaultIntentTx(params): Promise<TxPayloadBatchSequence>`
+
+Execute a pending direct swap intent with a flash swap:
+
+```typescript
+await sdk.executeDirectSwapVaultIntentTx({
+  keeper: wallet.publicKey.toBase58(),
+  intent: "<INTENT_PUBKEY>",
+  jup_swap_ix: jupiterSwapInstruction,
+  jup_address_lookup_table_addresses: [...],
+});
+```
+
+#### `cancelVaultIntentTx(params): Promise<TxPayloadBatchSequence>`
+
+Cancel and close an intent account:
+
+```typescript
+await sdk.cancelVaultIntentTx({
+  keeper: wallet.publicKey.toBase58(),
+  intent: "<INTENT_PUBKEY>",
+});
+```
+
+---
+
+### Deposits & Withdrawals
+
+#### `buyVaultTx(params): Promise<TxPayloadBatchSequence>`
+
+Deposit tokens into a vault to receive vault tokens:
+
+```typescript
+const tx = await sdk.buyVaultTx({
+  buyer: wallet.publicKey.toBase58(),
+  vault_mint: "<VAULT_MINT>",
+  contributions: [
+    { mint: "So11111111111111111111111111111111111111112", amount: 1_000_000_000 }, // 1 SOL
+    { mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", amount: 100_000_000 }, // 100 USDC
+  ],
+  rebalance_slippage_bps: 100,             // optional (default: 1%)
+  per_trade_rebalance_slippage_bps: 100,   // optional
+});
+
+await sdk.signAndSendTxPayloadBatchSequence({
+  txPayloadBatchSequence: tx,
+  wallet,
+});
+```
+
+#### `depositTokensTx(params): Promise<TxPayloadBatchSequence>`
+
+Add more tokens to an existing deposit before locking:
+
+```typescript
+const tx = await sdk.depositTokensTx({
+  buyer: wallet.publicKey.toBase58(),
+  contributions: [{ mint: "<MINT>", amount: 500_000_000 }],
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+#### `lockDepositsTx(params): Promise<TxPayloadBatchSequence>`
+
+Lock deposits and start the auction process:
+
+```typescript
+const tx = await sdk.lockDepositsTx({
+  buyer: wallet.publicKey.toBase58(),
+  vault_mint: "<VAULT_MINT>",
+});
+```
+
+#### `sellVaultTx(params): Promise<TxPayloadBatchSequence>`
+
+Withdraw from a vault by burning vault tokens:
+
+```typescript
+const tx = await sdk.sellVaultTx({
+  seller: wallet.publicKey.toBase58(),
+  vault_mint: "<VAULT_MINT>",
+  withdraw_amount: 1_000_000,       // vault tokens to burn
+  keep_tokens: [],                  // mints to receive directly without rebalancing
+  rebalance_slippage_bps: 100,
+});
+```
+
+---
+
+### Rebalancing
+
+#### `rebalanceVaultTx(params): Promise<TxPayloadBatchSequence>`
+
+Trigger a rebalance to bring the vault back to its target weights:
+
+```typescript
+const tx = await sdk.rebalanceVaultTx({
+  keeper: wallet.publicKey.toBase58(),
+  vault_mint: "<VAULT_MINT>",
+  rebalance_slippage_bps: 100,
+});
+```
+
+#### `cancelRebalanceIntentTx(params): Promise<TxPayloadBatchSequence>`
+
+Cancel an active rebalance intent:
+
+```typescript
+const tx = await sdk.cancelRebalanceIntentTx({
+  keeper: wallet.publicKey.toBase58(),
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+---
+
+### Oracle Price Updates
+
+#### `updateTokenPricesTx(params): Promise<TxPayloadBatchSequence>`
+
+Refresh on-chain oracle prices for all tokens in a vault during a rebalance:
+
+```typescript
+const tx = await sdk.updateTokenPricesTx({
+  keeper: wallet.publicKey.toBase58(),
+  vault: "<VAULT_PUBKEY>",
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+#### `updatePythPriceFeedsTx(params): Promise<TxPayloadBatchSequence>`
+
+Update specific Pyth price feeds from on-chain price accounts:
+
+```typescript
+const tx = await sdk.updatePythPriceFeedsTx({
+  keeper: wallet.publicKey.toBase58(),
+  accounts: ["<PYTH_PRICE_ACCOUNT_1>", "<PYTH_PRICE_ACCOUNT_2>"],
+});
+```
+
+---
+
+### Flash Swaps
+
+#### `flashSwapTx(params): Promise<TxPayloadBatchSequence>`
+
+Execute an atomic flash swap during rebalance auctions — withdraws tokens from the vault, performs a swap (e.g. via Jupiter), and deposits the result back in a single transaction:
+
+```typescript
+const tx = await sdk.flashSwapTx({
+  keeper: wallet.publicKey.toBase58(),
+  vault: "<VAULT_PUBKEY>",
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+  mint_in: "<DEPOSIT_TOKEN_MINT>",
+  mint_out: "<WITHDRAW_TOKEN_MINT>",
+  amount_in: 1_000_000,
+  amount_out: 1_000_000,
+  jup_swap_ix: jupiterSwapInstruction,
+  jup_token_ledger_ix: jupiterTokenLedgerInstruction,
+  jup_address_lookup_table_addresses: [...],
+});
+```
+
+---
+
+### Minting & Redeeming
+
+#### `mintTx(params): Promise<TxPayloadBatchSequence>`
+
+Mint vault tokens after a deposit completes its auctions:
+
+```typescript
+const tx = await sdk.mintTx({
+  keeper: wallet.publicKey.toBase58(),
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+#### `redeemTokensTx(params): Promise<TxPayloadBatchSequence>`
+
+Redeem underlying tokens from a completed withdrawal:
+
+```typescript
+const tx = await sdk.redeemTokensTx({
+  keeper: wallet.publicKey.toBase58(),
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+---
+
+### Bounties
+
+#### `addBountyTx(params): Promise<TxPayloadBatchSequence>`
+
+Add bounty to a vault for incentivizing keeper automation:
+
+```typescript
+const tx = await sdk.addBountyTx({
+  keeper: wallet.publicKey.toBase58(),
+  vault: "<VAULT_PUBKEY>",
+  amount: 100_000_000, // lamports
+});
+```
+
+#### `claimBountyTx(params): Promise<TxPayloadBatchSequence>`
+
+Claim bounty rewards after completing rebalance tasks:
+
+```typescript
+const tx = await sdk.claimBountyTx({
+  keeper: wallet.publicKey.toBase58(),
+  rebalance_intent: "<REBALANCE_INTENT_PUBKEY>",
+});
+```
+
+---
+
+### Fee Management
+
+#### `withdrawVaultFeesTx(params): Promise<TxPayloadBatchSequence>`
+
+Withdraw and claim accumulated fees from a vault. Automatically detects which fee types the claimer is authorized to collect (protocol, creator, host, or manager fees):
+
+```typescript
+const tx = await sdk.withdrawVaultFeesTx({
+  claimer: wallet.publicKey.toBase58(),
+  vault: "<VAULT_PUBKEY>",
+});
+```
+
+#### `claimTokenFeesFromVaultTx(params): Promise<TxPayloadBatchSequence>`
+
+Claim remaining fee tokens from an existing `WithdrawVaultFees` account:
+
+```typescript
+const tx = await sdk.claimTokenFeesFromVaultTx({
+  claimer: wallet.publicKey.toBase58(),
+  withdrawVaultFees: "<WITHDRAW_VAULT_FEES_PUBKEY>",
+});
+```
+
+---
+
+### Lookup Tables
+
+#### `rewriteLookupTablesTx(params): Promise<TxPayloadBatchSequence>`
+
+Rebuild address lookup tables for a vault (needed when LUTs are full after adding tokens):
+
+```typescript
+const tx = await sdk.rewriteLookupTablesTx({
+  signer: wallet.publicKey.toBase58(),
+  vault_mint: "<VAULT_MINT>",
+  additional_accounts: ["<ACCOUNT_1>", "<ACCOUNT_2>"],
+});
+```
+
+---
+
+### Sending Transactions
+
+All transaction-building methods return a `TxPayloadBatchSequence`. Batches are sent sequentially; transactions within a batch are sent in parallel.
+
+#### `signAndSendTxPayloadBatchSequence(params): Promise<TransactionSignature[][]>`
+
+```typescript
+const signatures = await sdk.signAndSendTxPayloadBatchSequence({
+  txPayloadBatchSequence: tx,
+  wallet,
+  simulateTransactions: false, // optional
+});
+```
+
+#### `signAndSendVersionedTxs(params): Promise<TransactionSignature[][]>`
+
+```typescript
+const signatures = await sdk.signAndSendVersionedTxs({
+  versionedTxs,
+  wallet,
+});
+```
+
+---
+
+## Keeper Monitor (Reference Implementation)
+
+`KeeperMonitor` is an example keeper implementation included in the SDK. It provides automated monitoring and execution of all pending protocol tasks.
+
+```typescript
+import { KeeperMonitor } from "@symmetry-hq/sdk";
+
+const keeper = new KeeperMonitor({
+  wallet,                          // wallet with signing capability
+  connection,                      // Solana RPC connection
+  network: "mainnet",
+  jupiterApiKey: "<JUP_API_KEY>",
+  maxAllowedAccounts: 64,
+  priorityFee: 50_000,            // optional
+  simulateTransactions: false,     // optional
+});
+
+while (true) {
+  await keeper.update();
+  await new Promise(r => setTimeout(r, 10_000));
+}
+```
+
+The keeper automatically monitors and executes pending intents, handles the full rebalance lifecycle (price updates, Jupiter flash swaps, minting, redeeming, bounty claims), and manages concurrent task execution.
+
+---
+
+## Standalone Utilities
+
+| Export | Description |
+|--------|-------------|
+| `getJupTokenLedgerAndSwapInstructions` | Build Jupiter swap instructions for flash swaps |
+| `getSwapPairs` | Compute required swap pairs for a rebalance intent |
+| `isRebalanceRequired` | Check whether a vault needs rebalancing based on its threshold settings |
+
+---
+
+## Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `VAULTS_V3_PROGRAM_ID` | `BASKT7aKd8n7ibpUbwLP3Wiyxyi3yoiXsxBk4Hpumate` | Program address |
+| `COMPUTE_UNITS` | `1,000,000` | Default compute unit limit |
+| `PRIORITY_FEE` | `25,000` | Default priority fee (micro-lamports) |
+| `MAX_SUPPORTED_TOKENS_PER_VAULT` | `100` | Max tokens per vault |
+| `MAX_MANAGERS_PER_VAULT` | `10` | Max managers per vault |
+| `MAX_ORACLES_PER_TOKEN` | `4` | Max oracle sources per token |
+| `HUNDRED_PERCENT_BPS` | `10,000` | 100% in basis points |
+
+## Supported Oracles
+
+| Type | Enum | Description |
+|------|------|-------------|
+| Pyth | `0` | Pyth Network price feeds via Hermes ([Price Feed IDs](https://docs.pyth.network/price-feeds/core/price-feeds/price-feed-ids)) |
+| Raydium CLMM | `1` | Raydium Concentrated Liquidity AMM TWAP (currently disabled on-chain) |
+| Raydium CPMM | `2` | Raydium Constant Product AMM TWAP |
+| Switchboard | `3` | Switchboard oracle feeds (currently disabled on-chain) |
+
+Each token in a vault supports up to 4 oracle sources with configurable aggregation (e.g. weighted percentile).
+
+## Networks
+
+| Network | WSOL Mint | USDC Mint |
+|---------|-----------|-----------|
+| `mainnet` | `So11111111111111111111111111111111111111112` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
+| `devnet` | `So11111111111111111111111111111111111111112` | `USDCoctVLVnvTXBEuP9s8hntucdJokbo17RwHuNXemT` |
+
+## License
+
+BUSL-1.1 (Business Source License 1.1)

package/dist/src/instructions/automation/rebalanceSwap.d.ts

@@ -0,0 +1,11 @@
+import { BN } from '@coral-xyz/anchor';
+import { PublicKey, TransactionInstruction } from '@solana/web3.js';
+export declare function rebalanceSwapIx(params: {
+    keeper: PublicKey;
+    basket: PublicKey;
+    mintFrom: PublicKey;
+    mintTo: PublicKey;
+    amountIn: BN;
+    amountOut: BN;
+    mode: number;
+}): TransactionInstruction;

package/dist/src/instructions/automation/rebalanceSwap.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rebalanceSwapIx = rebalanceSwapIx;
+const spl_token_1 = require("@solana/spl-token");
+const web3_js_1 = require("@solana/web3.js");
+const constants_1 = require("../../constants");
+const pda_1 = require("../pda");
+const REBALANCE_SWAP_DISCRIMINATOR = Buffer.from([101, 122, 61, 201, 21, 165, 177, 213]);
+function rebalanceSwapIx(params) {
+    const { keeper, basket, mintFrom, mintTo, amountIn, amountOut, mode } = params;
+    let rebalanceIntent = (0, pda_1.getRebalanceIntentPda)(basket, keeper); // TODO: incorrect. Pass intent as func param
+    let keeperFromATA = (0, pda_1.getAta)(keeper, mintFrom);
+    let keeperToATA = (0, pda_1.getAta)(keeper, mintTo);
+    let basketFromATA = (0, pda_1.getAta)(basket, mintFrom);
+    let basketToATA = (0, pda_1.getAta)(basket, mintTo);
+    const keys = [
+        { pubkey: params.keeper, isWritable: true, isSigner: true },
+        { pubkey: params.basket, isWritable: true, isSigner: false },
+        { pubkey: rebalanceIntent, isWritable: true, isSigner: false },
+        { pubkey: params.mintFrom, isWritable: false, isSigner: false },
+        { pubkey: params.mintTo, isWritable: false, isSigner: false },
+        { pubkey: keeperFromATA, isWritable: true, isSigner: false },
+        { pubkey: keeperToATA, isWritable: true, isSigner: false },
+        { pubkey: basketFromATA, isWritable: true, isSigner: false },
+        { pubkey: basketToATA, isWritable: true, isSigner: false },
+        { pubkey: (0, pda_1.getGlobalConfigPda)(), isWritable: false, isSigner: false },
+        { pubkey: web3_js_1.SystemProgram.programId, isWritable: false, isSigner: false },
+        { pubkey: spl_token_1.TOKEN_PROGRAM_ID, isWritable: false, isSigner: false },
+        { pubkey: spl_token_1.TOKEN_2022_PROGRAM_ID, isWritable: false, isSigner: false },
+        { pubkey: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID, isWritable: false, isSigner: false },
+    ];
+    const discriminator = REBALANCE_SWAP_DISCRIMINATOR;
+    const amountInBuffer = Buffer.from(amountIn.toArray("le", 8));
+    const amountOutBuffer = Buffer.from(amountOut.toArray("le", 8));
+    const modeBuffer = Buffer.from([mode]);
+    const data = Buffer.concat([discriminator, amountInBuffer, amountOutBuffer, modeBuffer]);
+    return new web3_js_1.TransactionInstruction({
+        keys,
+        programId: constants_1.BASKETS_V3_PROGRAM_ID,
+        data,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symmetry-hq/sdk",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Symmetry V3 SDK",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -14,8 +14,8 @@
     "vaults",
     "sdk"
   ],
-  "author": "Sandstorm",
-  "license": "ISC",
+  "author": "Symmetry Protocol",
+  "license": "BUSL-1.1",
   "dependencies": {
     "@coral-xyz/borsh": "^0.31.1",
     "@pythnetwork/hermes-client": "^2.1.0",

package/dist/src/keeperRebalaneHandler.d.ts

@@ -1,32 +0,0 @@
-import { Connection, PublicKey } from "@solana/web3.js";
-import { Wallet } from "./txUtils";
-import { Basket, UIRebalanceIntent } from ".";
-export declare class RebalanceHandler {
-    private params;
-    private intent;
-    private basket;
-    constructor(params: {
-        intent: UIRebalanceIntent;
-        basket: Basket;
-        wallet: Wallet;
-        connection: Connection;
-        network: "devnet" | "mainnet";
-        jupiterApiKey: string;
-        maxAllowedAccounts: number;
-        priorityFee?: number;
-        simulateTransactions?: boolean;
-    });
-    delay: (ms: number) => Promise<unknown>;
-    refresh(): Promise<void>;
-    static run(params: {
-        intentPubkey: PublicKey;
-        wallet: Wallet;
-        connection: Connection;
-        network: "devnet" | "mainnet";
-        jupiterApiKey: string;
-        maxAllowedAccounts: number;
-        priorityFee?: number;
-        simulateTransactions?: boolean;
-    }): Promise<void>;
-    private execute;
-}

package/dist/src/keeperRebalaneHandler.js

@@ -1,278 +0,0 @@
-"use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RebalanceHandler = void 0;
-const web3_js_1 = require("@solana/web3.js");
-const _1 = require(".");
-const rebalanceIntent_1 = require("./states/intents/rebalanceIntent");
-const constants_1 = require("./constants");
-class RebalanceHandler {
-    constructor(params) {
-        var _a, _b;
-        this.delay = (ms) => __awaiter(this, void 0, void 0, function* () { return new Promise(resolve => setTimeout(resolve, ms)); });
-        this.params = {
-            wallet: params.wallet,
-            connection: params.connection,
-            symmetryCore: new _1.SymmetryCore({
-                connection: params.connection,
-                network: params.network,
-                priorityFee: (_a = params.priorityFee) !== null && _a !== void 0 ? _a : constants_1.PRIORITY_FEE,
-            }),
-            network: params.network,
-            jupiterApiKey: params.jupiterApiKey,
-            maxAllowedAccounts: params.maxAllowedAccounts,
-            simulateTransactions: (_b = params.simulateTransactions) !== null && _b !== void 0 ? _b : false,
-        };
-        this.intent = params.intent;
-        this.basket = params.basket;
-    }
-    refresh() {
-        return __awaiter(this, void 0, void 0, function* () {
-            this.intent = yield this.params.symmetryCore.fetchRebalanceIntent(this.intent.formatted_data.pubkey);
-            this.basket = yield this.params.symmetryCore.fetchBasket(this.intent.formatted_data.basket);
-        });
-    }
-    static run(params) {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            let symmetryCore = new _1.SymmetryCore({
-                connection: params.connection,
-                network: params.network,
-                priorityFee: (_a = params.priorityFee) !== null && _a !== void 0 ? _a : constants_1.PRIORITY_FEE,
-            });
-            let intent = yield symmetryCore.fetchRebalanceIntent(params.intentPubkey.toBase58());
-            let basket = yield symmetryCore.fetchBasket(intent.formatted_data.basket);
-            let handler = new RebalanceHandler({
-                intent, basket,
-                wallet: params.wallet,
-                connection: params.connection,
-                network: params.network,
-                jupiterApiKey: params.jupiterApiKey,
-                maxAllowedAccounts: params.maxAllowedAccounts,
-                simulateTransactions: params.simulateTransactions,
-            });
-            handler.execute();
-            for (let i = 0; i < 20; i++) {
-                yield handler.delay(15 * 1000);
-                try {
-                    yield handler.refresh();
-                }
-                catch (e) {
-                    break;
-                }
-            }
-        });
-    }
-    execute() {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
-            console.log("Starting rebalance handler for intent:", this.intent.formatted_data.pubkey);
-            let nextCheckTime = 0;
-            let numTriesUpdatePrices = 0;
-            let numTriesMint = 0;
-            let numTriesRedeemTokens = 0;
-            let numTriesClaimBounty = 0;
-            let rebalancePairs = [];
-            let lastJupQuotesUpdate = 0;
-            let jupQuotes = [];
-            while (true) {
-                if (!this.intent)
-                    break;
-                let intent = this.intent.formatted_data;
-                let chainData = this.intent.chain_data;
-                let now = Date.now() / 1000;
-                if (now < nextCheckTime) {
-                    yield this.delay(Math.min(30 * 1000, Math.max(0, nextCheckTime - now + 0.2) * 1000));
-                    continue;
-                }
-                nextCheckTime = now + 35;
-                if (intent.current_action == "not_active") {
-                    console.log("Intent not active, stopping");
-                    break;
-                }
-                if (intent.current_action == "deposit_tokens") {
-                    console.log("Waiting for deposit...");
-                    continue;
-                }
-                if (intent.current_action == "update_prices" && intent.last_action_timestamp > now) {
-                    nextCheckTime = intent.last_action_timestamp;
-                    continue;
-                }
-                if (intent.current_action == "update_prices") {
-                    if (numTriesUpdatePrices >= 3) {
-                        console.log("Max retries for update_prices");
-                        break;
-                    }
-                    numTriesUpdatePrices += 1;
-                    try {
-                        let tx = yield this.params.symmetryCore.updateTokenPricesTx({
-                            keeper: this.params.wallet.publicKey.toBase58(),
-                            basket: intent.basket,
-                            rebalance_intent: intent.pubkey,
-                        });
-                        let res = yield this.params.symmetryCore.signAndSendTxPayloadBatchSequence({ txPayloadBatchSequence: tx, wallet: this.params.wallet, simulateTransactions: this.params.simulateTransactions });
-                        console.log("Update Prices:", res);
-                    }
-                    catch (e) {
-                        if (numTriesUpdatePrices == 3) {
-                            console.log("Stop - update prices failed:", e);
-                        }
-                    }
-                    continue;
-                }
-                if (intent.auctions[2].end_time > now) {
-                    let auction0StartTime = intent.auctions[0].start_time;
-                    let auction0EndTime = intent.auctions[0].end_time;
-                    let auction1StartTime = intent.auctions[1].start_time;
-                    let auction1EndTime = intent.auctions[1].end_time;
-                    let auction2StartTime = intent.auctions[2].start_time;
-                    let auction2EndTime = intent.auctions[2].end_time;
-                    rebalancePairs = (0, rebalanceIntent_1.getSwapPairs)(chainData, this.basket);
-                    if (Date.now() / 1000 > lastJupQuotesUpdate + 60) {
-                        let usedValue = new Map();
-                        jupQuotes = [];
-                        for (let pair of rebalancePairs) {
-                            let inValue = (_a = usedValue.get(pair.inMint)) !== null && _a !== void 0 ? _a : 0;
-                            let outValue = (_b = usedValue.get(pair.outMint)) !== null && _b !== void 0 ? _b : 0;
-                            let swapValue = Math.min(pair.value - inValue, pair.value - outValue);
-                            if (swapValue < 0.005) {
-                                jupQuotes.push(undefined);
-                                continue;
-                            }
-                            usedValue.set(pair.inMint, inValue + swapValue);
-                            usedValue.set(pair.outMint, outValue + swapValue);
-                            let res = undefined;
-                            if (this.params.network == "mainnet")
-                                try {
-                                    res = Object.assign(Object.assign({}, (yield (0, _1.getJupTokenLedgerAndSwapInstructions)({
-                                        keeper: this.params.wallet.publicKey,
-                                        basketMintIn: new web3_js_1.PublicKey(pair.inMint),
-                                        basketMintOut: new web3_js_1.PublicKey(pair.outMint),
-                                        basketAmountIn: pair.inAmount,
-                                        basketAmountOut: pair.outAmount,
-                                        swapMode: "ioc",
-                                        apiKey: this.params.jupiterApiKey,
-                                        maxJupAccounts: this.params.maxAllowedAccounts,
-                                    }))), { inMint: pair.inMint, outMint: pair.outMint });
-                                }
-                                catch (_c) { }
-                            ;
-                            jupQuotes.push(res);
-                        }
-                    }
-                    for (let index = 0; index < rebalancePairs.length; index++)
-                        try {
-                            let pair = rebalancePairs[index];
-                            let quote = jupQuotes.find(q => q && q.inMint == pair.inMint && q.outMint == pair.outMint);
-                            if (!quote)
-                                continue;
-                            if (pair.value < 0.005)
-                                continue;
-                            let { tokenLedgerInstruction, swapInstruction, addressLookupTableAddresses, quoteResponse } = quote;
-                            if (!quoteResponse)
-                                continue;
-                            console.log(pair, "Jup Quote:", parseFloat(quoteResponse.outAmount), "Requested In:", pair.inAmount);
-                            if (parseFloat(quoteResponse.outAmount) <= pair.inAmount && this.params.network == "mainnet")
-                                continue;
-                            try {
-                                let tx = yield this.params.symmetryCore.flashSwapTx({
-                                    keeper: this.params.wallet.publicKey.toBase58(),
-                                    basket: this.basket.ownAddress.toBase58(),
-                                    rebalance_intent: intent.pubkey,
-                                    mint_in: pair.inMint,
-                                    mint_out: pair.outMint,
-                                    amount_in: pair.inAmount,
-                                    amount_out: pair.outAmount,
-                                    mode: 2,
-                                    jup_token_ledger_ix: tokenLedgerInstruction,
-                                    jup_swap_ix: swapInstruction,
-                                    jup_address_lookup_table_addresses: addressLookupTableAddresses,
-                                });
-                                let res = yield this.params.symmetryCore.signAndSendTxPayloadBatchSequence({ txPayloadBatchSequence: tx, wallet: this.params.wallet, simulateTransactions: this.params.simulateTransactions });
-                                console.log("Flash Swap:", res);
-                                rebalancePairs = rebalancePairs.splice(index, 1);
-                                index -= 1;
-                            }
-                            catch (_d) { }
-                        }
-                        catch (_e) { }
-                    nextCheckTime = (Date.now() / 1000) + 10;
-                    continue;
-                }
-                if (intent.rebalance_type == "deposit") {
-                    lastJupQuotesUpdate = 0;
-                    if (numTriesMint >= 3) {
-                        console.log("Max retries for mint");
-                        break;
-                    }
-                    numTriesMint += 1;
-                    try {
-                        let tx = yield this.params.symmetryCore.mintTx({
-                            keeper: this.params.wallet.publicKey.toBase58(),
-                            rebalance_intent: intent.pubkey,
-                        });
-                        let res = yield this.params.symmetryCore.signAndSendTxPayloadBatchSequence({ txPayloadBatchSequence: tx, wallet: this.params.wallet, simulateTransactions: this.params.simulateTransactions });
-                        console.log("Mint:", res);
-                    }
-                    catch (e) {
-                        if (numTriesMint == 3) {
-                            console.log("Stop - mint failed:", e);
-                        }
-                    }
-                    continue;
-                }
-                let hasTokens = intent.tokens.find((token) => token.amount > 0);
-                if (hasTokens && intent.rebalance_type == "withdraw") {
-                    if (numTriesRedeemTokens >= 3) {
-                        console.log("Max retries for redeem");
-                        break;
-                    }
-                    numTriesRedeemTokens += 1;
-                    try {
-                        let tx = yield this.params.symmetryCore.redeemTokensTx({
-                            keeper: this.params.wallet.publicKey.toBase58(),
-                            rebalance_intent: intent.pubkey,
-                        });
-                        let res = yield this.params.symmetryCore.signAndSendTxPayloadBatchSequence({ txPayloadBatchSequence: tx, wallet: this.params.wallet, simulateTransactions: this.params.simulateTransactions });
-                        console.log("Redeem Tokens:", res);
-                    }
-                    catch (e) {
-                        if (numTriesRedeemTokens == 3) {
-                            console.log("Stop - redeem failed:", e);
-                        }
-                    }
-                    continue;
-                }
-                if (numTriesClaimBounty >= 3) {
-                    console.log("Max retries for claim bounty");
-                    break;
-                }
-                numTriesClaimBounty += 1;
-                try {
-                    let tx = yield this.params.symmetryCore.claimBountyTx({
-                        keeper: this.params.wallet.publicKey.toBase58(),
-                        rebalance_intent: intent.pubkey,
-                    });
-                    let res = yield this.params.symmetryCore.signAndSendTxPayloadBatchSequence({ txPayloadBatchSequence: tx, wallet: this.params.wallet, simulateTransactions: this.params.simulateTransactions });
-                    console.log("Claim Bounty:", res);
-                    nextCheckTime = now + 60;
-                }
-                catch (e) {
-                    if (numTriesClaimBounty == 3) {
-                        console.log("Stop - claim bounty failed:", e);
-                    }
-                }
-            }
-            console.log("Rebalance handler finished for intent:", this.intent.formatted_data.pubkey);
-        });
-    }
-}
-exports.RebalanceHandler = RebalanceHandler;