@barzkit/sdk 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.3] - 2026-03-01
+
+### Added
+
+- `swap()` method on `BarzAgent` — swap tokens via Uniswap V3 (Sepolia)
+- `lend()` method on `BarzAgent` — supply tokens to Aave V3 (Sepolia)
+- `SwapParams` and `LendParams` interfaces
+- `src/actions/tokens.ts` — `resolveToken()`, `getTokenDecimals()`, `isNativeETH()`, `ETH_SENTINEL`
+- `src/actions/swap.ts` — `buildSwapTransactions()`, `getSwapTokenAddresses()`, `UNISWAP_V3_ROUTER`
+- `src/actions/lend.ts` — `buildLendTransactions()`, `getLendTokenAddresses()`, `AAVE_V3_POOL`
+- Token permission validation for DeFi actions (`allowedTokens` check)
+- Unit tests for tokens, swap, and lend calldata builders
+- `defi-agent` example
+- DeFi actions guide (`docs/guides/defi-actions.md`)
+
+### Changed
+
+- Extracted `executeBatch()` helper in `account.ts` (reused by `batchTransactions`, `swap`, `lend`)
+
+## [0.1.2] - 2026-03-01
+
+### Added
+
+- `explorerUrl` field in `ChainConfig` — block explorer base URL per chain
+- `getExplorerUrl(hash)` method on `BarzAgent` — returns full explorer link for a transaction
+- Console warning when using Base mainnet (real funds at risk)
+- Chain-specific unit tests (`tests/unit/chains.test.ts`)
+
+### Changed
+
+- Updated package description and keywords for better discoverability
+- Refactored chain tests into dedicated test file
+
+## [0.1.1] - 2026-03-01
+
+### Added
+
+- `batchTransactions()` — atomic multi-call in a single UserOperation
+
+## [0.1.0] - 2026-02-28
+
+### Added
+
+#### Core API
+
+- `createBarzAgent()` — create an ERC-4337 smart account wallet on any supported chain
+- `sendTransaction()` — send gasless transactions via Pimlico bundler + paymaster
+- `getBalance()` — query ETH and ERC-20 token balances
+- `waitForTransaction()` — wait for on-chain confirmation with structured `TransactionReceipt`
+- `getExplorerUrl()` — block explorer URL for any transaction hash
+
+#### Multi-chain
+
+- Chain support: Sepolia, Base Sepolia, Base mainnet
+- `CHAIN_CONFIGS` / `getChainConfig` — chain configuration registry
+- `TOKENS` — pre-configured token addresses (USDC, WETH, DAI) per chain
+- Custom `rpcUrl` option in `AgentConfig`
+- Console warning when using Base mainnet (real funds at risk)
+
+#### Permissions
+
+- `AgentPermissions` — spending limits, contract whitelists, time windows
+- `getPermissions()` / `updatePermissions()` — runtime permission management
+- Client-side validation: per-tx limit, daily spend cap, allowed contracts, time window
+
+#### Safety
+
+- `freeze()` / `unfreeze()` — client-side kill switch (Phase 1)
+- `isActive()` — check whether the agent wallet is frozen
+
+#### DX
+
+- Human-readable AA error mapping (AA21, AA25, AA31, AA33, AA40/41)
+- Typed error hierarchy: `BarzKitError`, `ConfigError`, `PermissionError`, `FrozenError`, `TransactionError`, `BundlerError`
+- Config validation with actionable error messages
+- Account `index` for deterministic multi-wallet derivation from the same owner key
+- `gasless` config option (default: `true`)
+- `ERC20_ABI` — common ERC-20 function ABIs for contract reads
+- `AgentEvent` type definitions for future event hooks
+- Dual-package build: ESM (`.mjs`) + CJS (`.js`) + DTS (`.d.ts`)
+
+[0.1.3]: https://github.com/barzkit/sdk/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/barzkit/sdk/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/barzkit/sdk/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/barzkit/sdk/releases/tag/v0.1.0

package/README.md

@@ -142,7 +142,7 @@ Your AI Agent
 
 ## Examples
 
-See [barzkit-examples](https://github.com/barzkit/examples) for complete working examples.
+See [examples](https://github.com/barzkit/examples) for complete working examples.
 
 ## Security
 
@@ -156,8 +156,8 @@ See [barzkit-examples](https://github.com/barzkit/examples) for complete working
 
 - [x] Core SDK: createWallet, sendTransaction, permissions, freeze
 - [x] Batch transactions: atomic multi-call in one UserOperation
-- [ ] Multi-chain: Base Sepolia, Base mainnet
-- [ ] DeFi actions: swap, lend (Uniswap, Aave)
+- [x] Multi-chain: Base Sepolia, Base mainnet
+- [x] DeFi actions: swap, lend (Uniswap, Aave)
 - [ ] ElizaOS plugin
 - [ ] LangChain tool
 - [ ] x402 payment handler
@@ -173,4 +173,4 @@ MIT
 
 ---
 
-[Documentation](https://github.com/barzkit/sdk) · [Examples](https://github.com/barzkit/examples) · [Trust Wallet Barz](https://github.com/trustwallet/barz)
+[Documentation](https://github.com/barzkit/docs) · [Examples](https://github.com/barzkit/examples) · [Trust Wallet Barz](https://github.com/trustwallet/barz)

package/dist/index.cjs

@@ -16,7 +16,8 @@ var CHAIN_CONFIGS = {
     bundlerUrl: "https://api.pimlico.io/v2/sepolia/rpc",
     paymasterUrl: "https://api.pimlico.io/v2/sepolia/rpc",
     entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-    entryPointVersion: "0.6"
+    entryPointVersion: "0.6",
+    explorerUrl: "https://sepolia.etherscan.io"
   },
   "base-sepolia": {
     chain: chains.baseSepolia,
@@ -24,7 +25,8 @@ var CHAIN_CONFIGS = {
     bundlerUrl: "https://api.pimlico.io/v2/base-sepolia/rpc",
     paymasterUrl: "https://api.pimlico.io/v2/base-sepolia/rpc",
     entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-    entryPointVersion: "0.6"
+    entryPointVersion: "0.6",
+    explorerUrl: "https://sepolia.basescan.org"
   },
   base: {
     chain: chains.base,
@@ -32,7 +34,8 @@ var CHAIN_CONFIGS = {
     bundlerUrl: "https://api.pimlico.io/v2/base/rpc",
     paymasterUrl: "https://api.pimlico.io/v2/base/rpc",
     entryPointAddress: "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789",
-    entryPointVersion: "0.6"
+    entryPointVersion: "0.6",
+    explorerUrl: "https://basescan.org"
   }
 };
 function getChainConfig(chain) {
@@ -315,6 +318,214 @@ var ERC20_ABI = [
     type: "function"
   }
 ];
+var ETH_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+var TOKEN_DECIMALS = {
+  ETH: 18,
+  WETH: 18,
+  USDC: 6,
+  USDT: 6,
+  DAI: 18,
+  USDbC: 6
+};
+function resolveToken(symbolOrAddress, chain) {
+  if (symbolOrAddress.startsWith("0x")) {
+    return viem.getAddress(symbolOrAddress);
+  }
+  const symbol = symbolOrAddress.toUpperCase();
+  if (symbol === "ETH") {
+    return ETH_SENTINEL;
+  }
+  const chainTokens = TOKENS[chain];
+  if (!chainTokens) {
+    throw new BarzKitError(
+      `No tokens configured for chain "${chain}".`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  const address = chainTokens[symbol];
+  if (!address) {
+    throw new BarzKitError(
+      `Unknown token "${symbolOrAddress}" on ${chain}. Available: ${Object.keys(chainTokens).join(", ")}`,
+      "UNKNOWN_TOKEN"
+    );
+  }
+  return address;
+}
+function getTokenDecimals(symbol) {
+  return TOKEN_DECIMALS[symbol.toUpperCase()] ?? null;
+}
+function isNativeETH(token) {
+  if (token.toUpperCase() === "ETH") return true;
+  if (token.startsWith("0x")) {
+    return token.toLowerCase() === ETH_SENTINEL.toLowerCase();
+  }
+  return false;
+}
+
+// src/actions/swap.ts
+var UNISWAP_V3_ROUTER = {
+  sepolia: "0x3bFA4769FB09eefC5a80d6E87c3B9C650f7Ae48E"
+};
+var SWAP_ROUTER_ABI = [
+  {
+    inputs: [
+      {
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "fee", type: "uint24" },
+          { name: "recipient", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "amountOutMinimum", type: "uint256" },
+          { name: "sqrtPriceLimitX96", type: "uint160" }
+        ],
+        name: "params",
+        type: "tuple"
+      }
+    ],
+    name: "exactInputSingle",
+    outputs: [{ name: "amountOut", type: "uint256" }],
+    stateMutability: "payable",
+    type: "function"
+  }
+];
+function buildSwapTransactions(params, chain, account) {
+  const router = UNISWAP_V3_ROUTER[chain];
+  if (!router) {
+    throw new BarzKitError(
+      `Uniswap V3 is not available on "${chain}". Supported: ${Object.keys(UNISWAP_V3_ROUTER).join(", ")}`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  const tokenIn = resolveToken(params.from, chain);
+  const tokenOut = resolveToken(params.to, chain);
+  if (tokenIn.toLowerCase() === tokenOut.toLowerCase()) {
+    throw new BarzKitError(
+      `Cannot swap a token to itself ("${params.from}" \u2192 "${params.to}").`,
+      "INVALID_SWAP"
+    );
+  }
+  const fromIsETH = isNativeETH(params.from);
+  const fromSymbol = params.from.startsWith("0x") ? null : params.from;
+  const decimals = fromSymbol ? getTokenDecimals(fromSymbol) ?? 18 : 18;
+  const amountIn = viem.parseUnits(params.amount, decimals);
+  const routerTokenIn = fromIsETH ? resolveToken("WETH", chain) : tokenIn;
+  const routerTokenOut = isNativeETH(params.to) ? resolveToken("WETH", chain) : tokenOut;
+  const fee = params.fee ?? 3e3;
+  const amountOutMinimum = 0n;
+  const swapData = viem.encodeFunctionData({
+    abi: SWAP_ROUTER_ABI,
+    functionName: "exactInputSingle",
+    args: [
+      {
+        tokenIn: routerTokenIn,
+        tokenOut: routerTokenOut,
+        fee,
+        recipient: account,
+        amountIn,
+        amountOutMinimum,
+        sqrtPriceLimitX96: 0n
+      }
+    ]
+  });
+  const txs = [];
+  if (fromIsETH) {
+    txs.push({
+      to: router,
+      value: amountIn,
+      data: swapData
+    });
+  } else {
+    const approveData = viem.encodeFunctionData({
+      abi: ERC20_ABI,
+      functionName: "approve",
+      args: [router, amountIn]
+    });
+    txs.push({
+      to: tokenIn,
+      data: approveData
+    });
+    txs.push({
+      to: router,
+      data: swapData
+    });
+  }
+  return txs;
+}
+function getSwapTokenAddresses(params, chain) {
+  const addresses = [];
+  const tokenIn = resolveToken(params.from, chain);
+  const tokenOut = resolveToken(params.to, chain);
+  if (tokenIn !== ETH_SENTINEL) addresses.push(tokenIn);
+  if (tokenOut !== ETH_SENTINEL) addresses.push(tokenOut);
+  return addresses;
+}
+var AAVE_V3_POOL = {
+  sepolia: "0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951"
+};
+var AAVE_POOL_ABI = [
+  {
+    inputs: [
+      { name: "asset", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "onBehalfOf", type: "address" },
+      { name: "referralCode", type: "uint16" }
+    ],
+    name: "supply",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  }
+];
+function buildLendTransactions(params, chain, account) {
+  if (params.protocol !== "aave") {
+    throw new BarzKitError(
+      `Unknown lending protocol "${params.protocol}". Supported: aave`,
+      "UNKNOWN_PROTOCOL"
+    );
+  }
+  const pool = AAVE_V3_POOL[chain];
+  if (!pool) {
+    throw new BarzKitError(
+      `Aave V3 is not available on "${chain}". Supported: ${Object.keys(AAVE_V3_POOL).join(", ")}`,
+      "UNSUPPORTED_CHAIN"
+    );
+  }
+  if (isNativeETH(params.token)) {
+    throw new BarzKitError(
+      "Cannot supply native ETH to Aave. Wrap to WETH first, then supply WETH.",
+      "NATIVE_ETH_NOT_SUPPORTED"
+    );
+  }
+  const tokenAddress = resolveToken(params.token, chain);
+  const tokenSymbol = params.token.startsWith("0x") ? null : params.token;
+  const decimals = tokenSymbol ? getTokenDecimals(tokenSymbol) ?? 18 : 18;
+  const amount = viem.parseUnits(params.amount, decimals);
+  const approveData = viem.encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: "approve",
+    args: [pool, amount]
+  });
+  const supplyData = viem.encodeFunctionData({
+    abi: AAVE_POOL_ABI,
+    functionName: "supply",
+    args: [tokenAddress, amount, account, 0]
+  });
+  return [
+    {
+      to: tokenAddress,
+      data: approveData
+    },
+    {
+      to: pool,
+      data: supplyData
+    }
+  ];
+}
+function getLendTokenAddresses(params, chain) {
+  const tokenAddress = resolveToken(params.token, chain);
+  return [tokenAddress];
+}
 
 // src/core/account.ts
 async function createBarzAgent(config) {
@@ -346,8 +557,33 @@ async function createBarzAgent(config) {
       }
     }
   });
+  if (config.chain === "base") {
+    console.warn("\u26A0\uFE0F Using Base mainnet \u2014 real funds at risk");
+  }
   const permissionManager = new PermissionManager(config.permissions);
   let frozen = false;
+  async function executeBatch(txs) {
+    for (const tx of txs) {
+      permissionManager.validate(tx);
+    }
+    try {
+      const userOpHash = await smartAccountClient.sendUserOperation({
+        calls: txs.map((tx) => ({
+          to: tx.to,
+          value: tx.value ?? 0n,
+          data: tx.data ?? "0x"
+        }))
+      });
+      const receipt = await smartAccountClient.waitForUserOperationReceipt({
+        hash: userOpHash
+      });
+      const totalValue = txs.reduce((sum, tx) => sum + (tx.value ?? 0n), 0n);
+      if (totalValue > 0n) permissionManager.recordSpend(totalValue);
+      return receipt.receipt.transactionHash;
+    } catch (error) {
+      throw humanizeError(error);
+    }
+  }
   const agent = {
     address: smartAccount.address,
     chain: config.chain,
@@ -375,26 +611,7 @@ async function createBarzAgent(config) {
           "BATCH_EMPTY"
         );
       }
-      for (const tx of txs) {
-        permissionManager.validate(tx);
-      }
-      try {
-        const userOpHash = await smartAccountClient.sendUserOperation({
-          calls: txs.map((tx) => ({
-            to: tx.to,
-            value: tx.value ?? 0n,
-            data: tx.data ?? "0x"
-          }))
-        });
-        const receipt = await smartAccountClient.waitForUserOperationReceipt({
-          hash: userOpHash
-        });
-        const totalValue = txs.reduce((sum, tx) => sum + (tx.value ?? 0n), 0n);
-        if (totalValue > 0n) permissionManager.recordSpend(totalValue);
-        return receipt.receipt.transactionHash;
-      } catch (error) {
-        throw humanizeError(error);
-      }
+      return executeBatch(txs);
     },
     async getBalance(token) {
       try {
@@ -428,6 +645,23 @@ async function createBarzAgent(config) {
         );
       }
     },
+    async swap(params) {
+      if (frozen) throw new FrozenError();
+      const tokenAddresses = getSwapTokenAddresses(params, config.chain);
+      validateTokenPermissions(tokenAddresses, permissionManager.permissions);
+      const txs = buildSwapTransactions(params, config.chain, smartAccount.address);
+      return executeBatch(txs);
+    },
+    async lend(params) {
+      if (frozen) throw new FrozenError();
+      const tokenAddresses = getLendTokenAddresses(params, config.chain);
+      validateTokenPermissions(tokenAddresses, permissionManager.permissions);
+      const txs = buildLendTransactions(params, config.chain, smartAccount.address);
+      return executeBatch(txs);
+    },
+    getExplorerUrl(hash) {
+      return `${chainConfig.explorerUrl}/tx/${hash}`;
+    },
     getPermissions() {
       return permissionManager.permissions;
     },
@@ -465,17 +699,38 @@ function validateConfig(config) {
     throw new ConfigError('Missing "pimlico.apiKey". Get a free key at https://dashboard.pimlico.io');
   }
 }
+function validateTokenPermissions(tokenAddresses, permissions) {
+  if (!permissions.allowedTokens || permissions.allowedTokens.length === 0) return;
+  const allowed = permissions.allowedTokens.map((a) => a.toLowerCase());
+  for (const token of tokenAddresses) {
+    if (!allowed.includes(token.toLowerCase())) {
+      throw new PermissionError(
+        `Token ${token} is not in the allowed list. Allowed: ${permissions.allowedTokens.join(", ")}`
+      );
+    }
+  }
+}
 
+exports.AAVE_V3_POOL = AAVE_V3_POOL;
 exports.BarzKitError = BarzKitError;
 exports.BundlerError = BundlerError;
 exports.CHAIN_CONFIGS = CHAIN_CONFIGS;
 exports.ConfigError = ConfigError;
 exports.ERC20_ABI = ERC20_ABI;
+exports.ETH_SENTINEL = ETH_SENTINEL;
 exports.FrozenError = FrozenError;
 exports.PermissionError = PermissionError;
 exports.TOKENS = TOKENS;
 exports.TransactionError = TransactionError;
+exports.UNISWAP_V3_ROUTER = UNISWAP_V3_ROUTER;
+exports.buildLendTransactions = buildLendTransactions;
+exports.buildSwapTransactions = buildSwapTransactions;
 exports.createBarzAgent = createBarzAgent;
 exports.getChainConfig = getChainConfig;
+exports.getLendTokenAddresses = getLendTokenAddresses;
+exports.getSwapTokenAddresses = getSwapTokenAddresses;
+exports.getTokenDecimals = getTokenDecimals;
+exports.isNativeETH = isNativeETH;
+exports.resolveToken = resolveToken;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map