@lit-protocol/vincent-ability-debridge 0.0.7-mma

package/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Vincent Ability Debridge
+
+This document provides guidelines for contributing to the Vincent Ability Debridge project.
+
+## Overview
+
+The Vincent Ability Debridge is a ability to send deposit, withdraw or redeem Debridge transactions from a Vincent app on behalf of the delegator. It's part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK.
+
+## Setup
+
+1. Follow the global setup instructions in the repository root [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Development Workflow
+
+### Testing
+
+Run tests:
+
+```bash
+nx test ability-debridge
+```
+
+### Building the Lit Action
+
+Build the ability:
+
+```bash
+nx action:build ability-debridge
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the ability:
+
+```bash
+nx action:deploy ability-erc20-approval
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+
+## Ability Development Guidelines
+
+1. Use the Vincent Ability SDK to create abilitys
+2. Define clear schemas for ability parameters
+3. Implement the ability lifecycle methods (precheck, execute)
+4. Handle errors gracefully
+5. Write comprehensive tests for all functionality
+6. Document the ability's purpose and usage
+
+## Integration with Policies
+
+This ability can be integrated with various Vincent Policies to enforce constraints. When developing or modifying the ability, consider how it will be used with policies such as:
+
+- Vincent Policy Spending Limit
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document the ability's purpose and usage
+- Update README.md when adding new features
+- Document the ability's parameters and behavior
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new functionality
+4. Link any related issues in your pull request description
+5. Request a review from a maintainer
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [Vincent Ability SDK Documentation](../../libs/ability-sdk/README.md)
+- [ERC20 Standard](https://eips.ethereum.org/EIPS/eip-20)
+- [ERC4626 Standard](https://eips.ethereum.org/EIPS/eip-4626)

package/README.md

@@ -0,0 +1,124 @@
+# Vincent Ability deBridge
+
+Bridge tokens across multiple blockchains using the deBridge protocol. Supports native tokens and
+ERC-20 tokens with automatic quote fetching and gas estimation.
+
+## Features
+
+- Cross-chain transfers between multiple EVM-compatible chains
+- Support for both native tokens (ETH, MATIC, etc.) and ERC-20 tokens
+- Automatic quote fetching from deBridge API
+- Gas estimation and fee calculation
+- Integrated with Vincent Ability SDK for secure execution
+
+## Installation
+
+```bash
+npm install @lit-protocol/vincent-ability-debridge
+```
+
+## Usage
+
+```typescript
+import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk';
+import { bundledVincentAbility as deBridgeAbility } from '@lit-protocol/vincent-ability-debridge';
+import { ethers } from 'ethers';
+
+// Initialize the ability client
+const deBridgeClient = getVincentAbilityClient({
+  bundledVincentAbility: deBridgeAbility,
+  ethersSigner: yourSigner, // Your ethers signer
+});
+
+// Example: Bridge 0.1 ETH from Base to Arbitrum
+const bridgeParams = {
+  rpcUrl: 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
+  sourceChain: '8453', // Base
+  destinationChain: '42161', // Arbitrum
+  sourceToken: '0x0000000000000000000000000000000000000000', // Native ETH
+  destinationToken: '0x0000000000000000000000000000000000000000', // Native ETH
+  amount: ethers.utils.parseEther('0.1').toString(), // 0.1 ETH in wei
+  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD7e',
+  operation: 'BRIDGE',
+  slippageBps: 100, // 1% slippage
+};
+
+// First run precheck
+const precheckRes = await deBridgeClient.precheck(bridgeParams, {
+  delegatorPkpEthAddress: pkpAddress,
+});
+
+if (precheckRes.success) {
+  // Then execute
+  const executeRes = await deBridgeClient.execute(bridgeParams, {
+    delegatorPkpEthAddress: pkpAddress,
+  });
+
+  if (executeRes.success) {
+    console.log('Transaction hash:', executeRes.result.data.txHash);
+    console.log('Order ID:', executeRes.result.data.orderId);
+  }
+}
+```
+
+## Supported Chains
+
+- Ethereum (1)
+- Polygon (137)
+- Arbitrum (42161)
+- Optimism (10)
+- Base (8453)
+- BSC (56)
+- Avalanche (43114)
+
+## Parameters
+
+| Parameter          | Type     | Required | Description                                                                |
+| ------------------ | -------- | -------- | -------------------------------------------------------------------------- |
+| `rpcUrl`           | `string` | ✅       | RPC URL for the source chain                                               |
+| `sourceChain`      | `string` | ✅       | Source chain ID (e.g., '1' for Ethereum, '8453' for Base)                  |
+| `destinationChain` | `string` | ✅       | Destination chain ID                                                       |
+| `sourceToken`      | `string` | ✅       | Source token address (use zero address for native token)                   |
+| `destinationToken` | `string` | ✅       | Destination token address (use zero address for native token)              |
+| `amount`           | `string` | ✅       | Amount in base units (wei for ETH, smallest unit for tokens)               |
+| `recipientAddress` | `string` | ✅       | Recipient address on destination chain                                     |
+| `operation`        | `string` | ✅       | `BRIDGE` for direct transfers, `BRIDGE_AND_SWAP` for cross-asset transfers |
+| `slippageBps`      | `number` | ❌       | Slippage tolerance in basis points (default: 100 = 1%)                     |
+
+⚠️ **Important**: The `amount` parameter must be in the token's smallest unit (e.g., wei for ETH).
+
+## Prerequisites
+
+- Node.js 16+ and npm/yarn
+- Sufficient token balance for the bridge amount + fees
+- Properly configured PKP wallet with required permissions
+- For ERC-20 tokens: Sufficient token allowance for the deBridge contract
+
+## Building
+
+```bash
+# Build the ability
+npm run build
+
+# Build all abilitys and policies
+npm run vincent:build
+```
+
+## Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run E2E tests
+npm run test:e2e
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on how
+to contribute to this project.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.

package/dist/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Vincent Ability Debridge
+
+This document provides guidelines for contributing to the Vincent Ability Debridge project.
+
+## Overview
+
+The Vincent Ability Debridge is a ability to send deposit, withdraw or redeem Debridge transactions from a Vincent app on behalf of the delegator. It's part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK.
+
+## Setup
+
+1. Follow the global setup instructions in the repository root [CONTRIBUTING.md](../../../CONTRIBUTING.md).
+2. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+## Development Workflow
+
+### Testing
+
+Run tests:
+
+```bash
+nx test ability-debridge
+```
+
+### Building the Lit Action
+
+Build the ability:
+
+```bash
+nx action:build ability-debridge
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the ability:
+
+```bash
+nx action:deploy ability-erc20-approval
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+
+## Ability Development Guidelines
+
+1. Use the Vincent Ability SDK to create abilitys
+2. Define clear schemas for ability parameters
+3. Implement the ability lifecycle methods (precheck, execute)
+4. Handle errors gracefully
+5. Write comprehensive tests for all functionality
+6. Document the ability's purpose and usage
+
+## Integration with Policies
+
+This ability can be integrated with various Vincent Policies to enforce constraints. When developing or modifying the ability, consider how it will be used with policies such as:
+
+- Vincent Policy Spending Limit
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document the ability's purpose and usage
+- Update README.md when adding new features
+- Document the ability's parameters and behavior
+
+## Pull Request Process
+
+1. Ensure your code follows the coding standards
+2. Update documentation if necessary
+3. Include tests for new functionality
+4. Link any related issues in your pull request description
+5. Request a review from a maintainer
+
+## Additional Resources
+
+- [Vincent Documentation](https://docs.heyvincent.ai/)
+- [Vincent Ability SDK Documentation](../../libs/ability-sdk/README.md)
+- [ERC20 Standard](https://eips.ethereum.org/EIPS/eip-20)
+- [ERC4626 Standard](https://eips.ethereum.org/EIPS/eip-4626)

package/dist/README.md

@@ -0,0 +1,124 @@
+# Vincent Ability deBridge
+
+Bridge tokens across multiple blockchains using the deBridge protocol. Supports native tokens and
+ERC-20 tokens with automatic quote fetching and gas estimation.
+
+## Features
+
+- Cross-chain transfers between multiple EVM-compatible chains
+- Support for both native tokens (ETH, MATIC, etc.) and ERC-20 tokens
+- Automatic quote fetching from deBridge API
+- Gas estimation and fee calculation
+- Integrated with Vincent Ability SDK for secure execution
+
+## Installation
+
+```bash
+npm install @lit-protocol/vincent-ability-debridge
+```
+
+## Usage
+
+```typescript
+import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk';
+import { bundledVincentAbility as deBridgeAbility } from '@lit-protocol/vincent-ability-debridge';
+import { ethers } from 'ethers';
+
+// Initialize the ability client
+const deBridgeClient = getVincentAbilityClient({
+  bundledVincentAbility: deBridgeAbility,
+  ethersSigner: yourSigner, // Your ethers signer
+});
+
+// Example: Bridge 0.1 ETH from Base to Arbitrum
+const bridgeParams = {
+  rpcUrl: 'https://base-mainnet.g.alchemy.com/v2/YOUR_KEY',
+  sourceChain: '8453', // Base
+  destinationChain: '42161', // Arbitrum
+  sourceToken: '0x0000000000000000000000000000000000000000', // Native ETH
+  destinationToken: '0x0000000000000000000000000000000000000000', // Native ETH
+  amount: ethers.utils.parseEther('0.1').toString(), // 0.1 ETH in wei
+  recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD7e',
+  operation: 'BRIDGE',
+  slippageBps: 100, // 1% slippage
+};
+
+// First run precheck
+const precheckRes = await deBridgeClient.precheck(bridgeParams, {
+  delegatorPkpEthAddress: pkpAddress,
+});
+
+if (precheckRes.success) {
+  // Then execute
+  const executeRes = await deBridgeClient.execute(bridgeParams, {
+    delegatorPkpEthAddress: pkpAddress,
+  });
+
+  if (executeRes.success) {
+    console.log('Transaction hash:', executeRes.result.data.txHash);
+    console.log('Order ID:', executeRes.result.data.orderId);
+  }
+}
+```
+
+## Supported Chains
+
+- Ethereum (1)
+- Polygon (137)
+- Arbitrum (42161)
+- Optimism (10)
+- Base (8453)
+- BSC (56)
+- Avalanche (43114)
+
+## Parameters
+
+| Parameter          | Type     | Required | Description                                                                |
+| ------------------ | -------- | -------- | -------------------------------------------------------------------------- |
+| `rpcUrl`           | `string` | ✅       | RPC URL for the source chain                                               |
+| `sourceChain`      | `string` | ✅       | Source chain ID (e.g., '1' for Ethereum, '8453' for Base)                  |
+| `destinationChain` | `string` | ✅       | Destination chain ID                                                       |
+| `sourceToken`      | `string` | ✅       | Source token address (use zero address for native token)                   |
+| `destinationToken` | `string` | ✅       | Destination token address (use zero address for native token)              |
+| `amount`           | `string` | ✅       | Amount in base units (wei for ETH, smallest unit for tokens)               |
+| `recipientAddress` | `string` | ✅       | Recipient address on destination chain                                     |
+| `operation`        | `string` | ✅       | `BRIDGE` for direct transfers, `BRIDGE_AND_SWAP` for cross-asset transfers |
+| `slippageBps`      | `number` | ❌       | Slippage tolerance in basis points (default: 100 = 1%)                     |
+
+⚠️ **Important**: The `amount` parameter must be in the token's smallest unit (e.g., wei for ETH).
+
+## Prerequisites
+
+- Node.js 16+ and npm/yarn
+- Sufficient token balance for the bridge amount + fees
+- Properly configured PKP wallet with required permissions
+- For ERC-20 tokens: Sufficient token allowance for the deBridge contract
+
+## Building
+
+```bash
+# Build the ability
+npm run build
+
+# Build all abilitys and policies
+npm run vincent:build
+```
+
+## Testing
+
+```bash
+# Run unit tests
+npm test
+
+# Run E2E tests
+npm run test:e2e
+```
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines on how
+to contribute to this project.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.

package/dist/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lit-protocol/vincent-ability-debridge",
+  "version": "0.0.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "vault-search": "tsx examples/vault-search.ts"
+  },
+  "dependencies": {
+    "@lit-protocol/constants": "^7.2.0",
+    "@lit-protocol/vincent-scaffold-sdk": "^1.1.6",
+    "@lit-protocol/vincent-ability-sdk": "workspace:*",
+    "ethers": "^5.8.0",
+    "tslib": "2.8.1",
+    "zod": "^3.25.64"
+  },
+  "peerDependencies": {
+    "@lit-protocol/vincent-app-sdk": "workspace:^"
+  },
+  "devDependencies": {
+    "esbuild": "^0.19.12",
+    "esbuild-plugin-polyfill-node": "^0.3.0",
+    "ipfs-only-hash": "^4.0.0",
+    "tsx": "^4.19.4"
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist/**",
+    "*.md"
+  ],
+  "type": "commonjs"
+}