biatec-concentrated-liquidity-amm 0.9.34 → 0.9.35

package/README.md

@@ -30,6 +30,16 @@ npm i biatec-concentrated-liquidity-amm
 
 ## Examples
 
+### Retrieve deployed app IDs
+
+```ts
+import { getConfig } from 'biatec-concentrated-liquidity-amm';
+
+const { configAppId, identityAppId, poolProviderAppId } = getConfig('testnet-v1.0');
+```
+
+Supported genesis IDs are `mainnet-v1.0`, `voimain-v1.0`, and `testnet-v1.0`. The helper throws if you pass an unsupported network so deployments stay explicit.
+
 ## Add liquidity
 
 ```
@@ -106,3 +116,108 @@ const txId = await clammRemoveLiquiditySender({
   lpToSend: bigint;
 })
 ```
+
+## Staking Pools (NEW)
+
+BiatecCLAMM now supports staking pools where asset A and asset B are the same token. This enables creation of interest-bearing tokens like B-ALGO, B-USDC, etc.
+
+### Creating a Native Token Staking Pool (B-ALGO)
+
+```typescript
+import { clammCreateSender } from 'biatec-concentrated-liquidity-amm';
+
+await poolProviderClient.send.setNativeTokenName({
+  args: {
+    appBiatecConfigProvider: configAppId,
+    nativeTokenName: 'ALGO',
+  },
+  appReferences: [configAppId],
+});
+
+const poolClient = await clammCreateSender({
+  transactionSigner: signerAccount,
+  clientBiatecPoolProvider: poolProviderClient,
+  appBiatecConfigProvider: configAppId,
+  assetA: 0n, // Native token (ALGO)
+  assetB: 0n, // Same as asset A
+  fee: 0n, // No fee
+  verificationClass: 0,
+  priceMin: BigInt(SCALE),
+  priceMax: BigInt(SCALE),
+  currentPrice: BigInt(SCALE),
+});
+```
+
+### Distributing Staking Rewards
+
+```typescript
+import { clammDistributeExcessAssetsSender } from 'biatec-concentrated-liquidity-amm';
+
+// After rewards accrue to the pool (e.g., from consensus rewards)
+// Note: rewardsAmount should already be in asset decimals (e.g., microAlgos)
+// Convert to base scale (9 decimals) by multiplying with scale factor
+const rewardsInBaseScale = (rewardsAmount * BigInt(SCALE)) / BigInt(assetDecimals);
+
+const txId = await clammDistributeExcessAssetsSender({
+  algod,
+  account: executiveSigner,
+  amountA: rewardsInBaseScale, // Amount in base scale (9 decimals)
+  amountB: 0n,
+  appBiatecConfigProvider: configAppId,
+  assetA: 0n,
+  assetB: 0n,
+  clientBiatecClammPool: poolClient,
+});
+```
+
+For complete documentation, see [docs/staking-pools.md](docs/staking-pools.md).
+
+### Key Features:
+
+- **Create Interest-Bearing Tokens**: Build B-ALGO, B-USDC, or any B-{TOKEN}
+- **Support Multi-Chain Networks**: Works with ALGO, VOI, ARAMID chains
+- **Distribute Rewards to LP Holders**: Share staking rewards, interest, or fees
+- **Enable Flexible Use Cases**: Power lending protocols, yield aggregation, revenue sharing
+
+### Use Cases:
+
+1. **Native Token Staking**: B-ALGO pools for staking ALGO with consensus rewards
+2. **Asset Staking**: B-USDC pools for lending protocol interest
+3. **Revenue Sharing**: Distribute protocol fees to token holders
+4. **Yield Aggregation**: Combine multiple yield sources
+
+## Documentation
+
+Comprehensive documentation is available in the `docs/` folder:
+
+### Core Documentation
+- **[Basic Use Cases](docs/basic-use-cases.md)** - Getting started with pools, swaps, and liquidity
+- **[Staking Pools](docs/staking-pools.md)** - Create B-ALGO, B-USDC interest-bearing tokens
+- **[Integration Guide](docs/integration-guide.md)** - Best practices for integrating CLAMM into your application
+
+### Technical Details
+- **[Liquidity Fee Protection](docs/liquidity-fee-protection.md)** - How fee accounting protects LPs
+- **[Liquidity Rounding](docs/liquidity-rounding.md)** - Rounding behavior and user expectations
+- **[Error Codes](docs/error-codes.md)** - Complete reference of all error messages
+
+### Security
+- **[Security Audits](audits/)** - Multiple AI-powered security audit reports
+- **[Integration Security](docs/integration-guide.md#security-considerations)** - Critical warnings for developers
+
+### Key Resources
+
+- 📖 **Error Troubleshooting**: See [error-codes.md](docs/error-codes.md) for solutions
+- 🔐 **Security Best Practices**: Review [integration-guide.md](docs/integration-guide.md) before deployment
+- 🧪 **Testing**: Examples in `__test__/` folder show proper usage patterns
+- 🛡️ **Audit Reports**: Six AI security audits in `audits/` folder
+
+## Security Considerations
+
+⚠️ **Important Security Notices**:
+
+1. **Price Oracle Usage**: Never use single pool VWAP as sole price source. See [integration guide](docs/integration-guide.md#using-clamm-as-price-oracle) for safe patterns.
+2. **Slippage Protection**: Always enforce minimum slippage (≥0.5%). Never use `minimumToReceive = 0`.
+3. **Identity Verification**: All operations require proper KYC verification class.
+4. **LP Token Rounding**: Small rounding losses (< 0.0001%) are expected. See [liquidity-rounding.md](docs/liquidity-rounding.md).
+
+Multiple security audits have been conducted. Review the `audits/` folder before mainnet deployment.