@lit-protocol/vincent-ability-uniswap-swap 2.0.1 → 4.0.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# 3.0.0 (2025-09-11)
+
+### ⚠️ Breaking Changes
+
+- Refactor the Uniswap Swap Ability to utilize a prepare step which uses a Lit Action to generate and sign a Uniswap route generated by the V3 Alpha Router. The Swap Ability now intakes the signed route, validates it was signed by the expected PKP (which can only be used to sign the generated Uniswap routes within the prepare Lit Action), then uses the provided route to create and sign the Uniswap Swap transaction with the Agent Wallet PKP. The Uniswap Swap Ability was also updated to no longer support the Spending Limit Policy, and currently doesn't support any Policies. ([8bbb1c07](https://github.com/LIT-Protocol/Vincent/commit/8bbb1c07))
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.1.0
+- Updated app-sdk to 2.1.0
+
+### ❤️ Thank You
+
+- Wyatt Barnes @spacesailor24
+
 ## 2.0.1 (2025-09-03)
 
 ### 🧱 Updated Dependencies

package/README.md

@@ -1,18 +1,13 @@
 # Vincent Ability Uniswap Swap
 
-An ability to trigger swaps on Uniswap from a Vincent app on behalf of the delegator.
-
-## Overview
-
-The Vincent Ability Uniswap Swap is part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK. It allows Vincent apps to execute token swaps on Uniswap V3 on behalf of users, enabling seamless integration with decentralized exchange functionality.
+This Uniswap Swap Ability is part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK. It allows Vincent Apps to execute token swaps on Uniswap V3 on behalf of Vincent Users, enabling integration with decentralized exchanges.
 
 ## Features
 
 - Execute token swaps on Uniswap V3
 - Support for exact input and exact output swaps
-- Support for multiple token pairs
-- Integration with spending limit policies for enhanced security
-- Support for multiple chains and Uniswap deployments
+- Support for multi-hop swaps through multiple pools
+- Support for multiple chains that Uniswap V3 is deployed to
 
 ## Installation
 
@@ -22,106 +17,122 @@ npm install @lit-protocol/vincent-ability-uniswap-swap
 
 ## Usage
 
-This ability can be used in Vincent apps to execute Uniswap swaps:
+To use the Uniswap Swap Ability, you need to generate a signed swap quote first, then provide it to both the `precheck` and `execute` functions.
 
-```typescript
-import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
-import { bundledVincentAbility } from '@lit-protocol/vincent-ability-uniswap-swap';
+### 1. Generate a Signed Swap Quote
 
-// One of delegatee signers from your app's Vincent Dashboard
-const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY');
+Before executing a swap, you must generate a signed quote using the `getSignedUniswapQuote` function:
 
-// Initialize the Vincent Ability Client
-const abilityClient = getVincentAbilityClient({
-  ethersSigner: delegateeSigner,
-  bundledVincentAbility,
+```typescript
+import { LitNodeClient } from '@lit-protocol/lit-node-client';
+import { getSignedUniswapQuote } from '@lit-protocol/vincent-ability-uniswap-swap';
+import { ethers } from 'ethers';
+
+// Initialize Lit Node Client
+const litNodeClient = new LitNodeClient({
+  litNetwork: 'datil',
+  debug: true,
 });
-const delegatorPkpEthAddress = '0x09182301238'; // The delegator PKP Eth Address
-
-const abilityParams = {
-  chainId: '8453', // The chain where the tx will be executed
-  tokenIn: '0x1234...', // The input token address
-  amountIn: '1000000000000000000', // The input amount (in wei)
-  tokenOut: '0xabcd...', // The output token address
-  rpcUrl: 'https://mainnet.base.org', // The RPC to send the transaction through
-};
-
-// Run precheck to see if ability should be executed
-const precheckResult = await client.precheck(abilityParams, {
-  delegatorPkpEthAddress,
+await litNodeClient.connect();
+
+// Your delegatee signer (one of the delegatee signers for the Vincent App)
+const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY', provider);
+
+// Generate the signed quote
+const signedUniswapQuote = await getSignedUniswapQuote({
+  quoteParams: {
+    rpcUrl: 'https://mainnet.base.org',
+    tokenInAddress: '0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed', // DEGEN
+    tokenInAmount: '80', // Amount in token's smallest unit
+    tokenOutAddress: '0x4200000000000000000000000000000000000006', // WETH
+    recipient: delegatorPkpEthAddress, // The PKP that will execute the swap
+  },
+  ethersSigner: delegateeSigner,
+  litNodeClient,
 });
+```
 
-if (precheckResult.success === true) {
-  // Execute the Vincent Ability
-  const executeResult = await client.execute(abilityParams, {
-    delegatorPkpEthAddress,
-  });
+The return value of `getSignedUniswapQuote` is an object containing:
 
-  // ...ability has executed, you can check `executeResult` for details
-}
-```
+- `quote`: The Uniswap Quote/Route generated by the V3 SDK using the Alpha Router
+- `signature`: A signature of `quote` signed by a Lit PKP that is configured to only ever be able to sign these generated Uniswap Quotes within the specific Lit Action configured by this Ability
+- `dataSigned`: The data signed by the PKP, an ETH Personal Message containing the hash of the stringified `quote`
+- `signerPublicKey`: The public key of the PKP that signed the `quote`
+- `signerEthAddress`: The Ethereum address of the PKP that signed the `quote`
 
-## Integration with Policies
+Because the Uniswap SDK makes a lot of RPC calls when generating a quote/route, it exceeded the usage limits of Lit Actions when running within the same Lit Action as the Vincent logic for checking and executing Policies, and verifying on-chain delegation.
 
-This ability is integrated with the Vincent Policy Spending Limit to enforce spending constraints:
+So, the purpose of `getSignedUniswapQuote` is to generate a signed quote/route outside of the Vincent Ability Lit Action, and then provide it to the `precheck` and `execute` functions in a tamper-proof manner. The Vincent Delegatee is unable to modify the quote/route after it has been signed by the PKP, because the Ability verifies the provided route data was signed by the hardcoded PKP address.
+
+### 2. Run Precheck
+
+Provide the signed `quote` to `precheck` to check if the swap can be executed:
 
 ```typescript
-import {
-  createVincentAbilityPolicy,
-  createVincentAbility,
-  createPolicyMapFromAbilityPolicies,
-} from '@lit-protocol/vincent-ability-sdk';
-import { bundledVincentPolicy } from '@lit-protocol/vincent-policy-spending-limit';
-import { abilityParamsSchema } from '@lit-protocol/vincent-ability-uniswap-swap';
-
-const spendingLimitPolicy = createVincentAbilityPolicy({
-  abilityParamsSchema,
-  bundledVincentPolicy,
-  abilityParameterMappings: {
-    pkpEthAddress: 'pkpEthAddress',
-    ethRpcUrl: 'ethRpcUrl',
-    tokenInAddress: 'tokenAddress',
-    tokenInDecimals: 'tokenDecimals',
-    tokenInAmount: 'buyAmount',
-  },
-});
+import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
+import { bundledVincentAbility } from '@lit-protocol/vincent-ability-uniswap-swap';
 
-export const uniswapSwapWithSpendingLimit = createVincentAbility({
-  abilityParamsSchema,
-  policyMap: createPolicyMapFromAbilityPolicies([spendingLimitPolicy]),
-  // ... rest of ability implementation
+// Initialize the ability client
+const abilityClient = getVincentAbilityClient({
+  bundledVincentAbility,
+  ethersSigner: delegateeSigner,
 });
-```
 
-## Prerequisites
+// Run precheck with the signed quote
+const precheckResult = await abilityClient.precheck(
+  {
+    rpcUrlForUniswap: 'https://mainnet.base.org',
+    signedUniswapQuote: {
+      quote: signedUniswapQuote.quote,
+      signature: signedUniswapQuote.signature,
+    },
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The delegator PKP ETH address
+  },
+);
 
-Before executing a swap, ensure that:
+if (precheckResult.success) {
+  console.log('Swap can be executed');
+}
+```
 
-1. The user has approved the input token for the Uniswap router
-2. The user has sufficient balance of the input token
-3. The user has delegated permission to the Vincent app to execute swaps
+### 3. Execute the Swap
 
-You can use the Vincent Ability ERC20 Approval to handle token approvals:
+If `precheck` succeeds, execute the swap using the same signed `quote`:
 
 ```typescript
-import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
-import { ERC20_APPROVAL_TOOL_IPFS_ID } from '@lit-protocol/vincent-ability-erc20-approval';
+const executeResult = await abilityClient.execute(
+  {
+    rpcUrlForUniswap: 'https://mainnet.base.org',
+    signedUniswapQuote: {
+      quote: signedUniswapQuote.quote,
+      signature: signedUniswapQuote.signature,
+    },
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The delegator PKP ETH address
+  },
+);
 
-// ... approve tokens before swap
+if (executeResult.success) {
+  console.log('Swap executed successfully!');
+  console.log('Transaction hash:', executeResult.result.swapTxHash);
+}
 ```
 
-## Building
-
-Run `nx build ability-uniswap-swap` to build the library.
+A complete example of generating the signed `quote`, running `precheck`, and executing the swap is available in the `abilities-e2e`'s end-to-end [swap.spec.ts](../abilities-e2e/test-e2e/swap.spec.ts) test.
 
-## Running unit tests
+## Development
 
-Run `nx test ability-uniswap-swap` to execute the unit tests via [Jest](https://jestjs.io).
+Because of the need for the `getSignedUniswapQuote` function and it's corresponding Lit Action, included in this package is a script ([create-pkp-for-prepare.js](./scripts/create-pkp-for-prepare.js)) that is used to mint the PKP that is configured to only ever be able to sign these generated Uniswap Quotes within the specific Lit Action configured by this Ability.
 
-## Contributing
+Anytime changes are made to the [Prepare Lit Action](./src/lib/prepare/lit-action.ts), you **MUST** run the PKP minting script to update the PKP info recorded in [vincent-prepare-metadata.json](./src/generated/vincent-prepare-metadata.json) file. You can execute the script using the Nx target:
 
-Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.
+```
+pnpm nx run ability-uniswap-swap:action:create-pkp
+```
 
-## License
+This will run the `action:deploy` target, which will build the Prepare Lit Action and deploy it to IPFS, recording the IPFS CID in `vincent-prepare-metadata.json` file. Then the `create-pkp-for-prepare.js` script will be executed minting a new PKP that has the IPFS CID of the Prepare Lit Action as the only permitted Auth Method.
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+After making any changes to the Prepare Lit Action, generating a new signer PKP, run the `build` target to update the Swap Ability Lit Action with the new PKP ETH address used for verifying the `quote` signatures.

package/dist/CHANGELOG.md

@@ -1,3 +1,18 @@
+# 3.0.0 (2025-09-11)
+
+### ⚠️ Breaking Changes
+
+- Refactor the Uniswap Swap Ability to utilize a prepare step which uses a Lit Action to generate and sign a Uniswap route generated by the V3 Alpha Router. The Swap Ability now intakes the signed route, validates it was signed by the expected PKP (which can only be used to sign the generated Uniswap routes within the prepare Lit Action), then uses the provided route to create and sign the Uniswap Swap transaction with the Agent Wallet PKP. The Uniswap Swap Ability was also updated to no longer support the Spending Limit Policy, and currently doesn't support any Policies. ([8bbb1c07](https://github.com/LIT-Protocol/Vincent/commit/8bbb1c07))
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.1.0
+- Updated app-sdk to 2.1.0
+
+### ❤️ Thank You
+
+- Wyatt Barnes @spacesailor24
+
 ## 2.0.1 (2025-09-03)
 
 ### 🧱 Updated Dependencies

package/dist/README.md

@@ -1,18 +1,13 @@
 # Vincent Ability Uniswap Swap
 
-An ability to trigger swaps on Uniswap from a Vincent app on behalf of the delegator.
-
-## Overview
-
-The Vincent Ability Uniswap Swap is part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK. It allows Vincent apps to execute token swaps on Uniswap V3 on behalf of users, enabling seamless integration with decentralized exchange functionality.
+This Uniswap Swap Ability is part of the Vincent Abilities ecosystem and is built using the Vincent Ability SDK. It allows Vincent Apps to execute token swaps on Uniswap V3 on behalf of Vincent Users, enabling integration with decentralized exchanges.
 
 ## Features
 
 - Execute token swaps on Uniswap V3
 - Support for exact input and exact output swaps
-- Support for multiple token pairs
-- Integration with spending limit policies for enhanced security
-- Support for multiple chains and Uniswap deployments
+- Support for multi-hop swaps through multiple pools
+- Support for multiple chains that Uniswap V3 is deployed to
 
 ## Installation
 
@@ -22,106 +17,122 @@ npm install @lit-protocol/vincent-ability-uniswap-swap
 
 ## Usage
 
-This ability can be used in Vincent apps to execute Uniswap swaps:
+To use the Uniswap Swap Ability, you need to generate a signed swap quote first, then provide it to both the `precheck` and `execute` functions.
 
-```typescript
-import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
-import { bundledVincentAbility } from '@lit-protocol/vincent-ability-uniswap-swap';
+### 1. Generate a Signed Swap Quote
 
-// One of delegatee signers from your app's Vincent Dashboard
-const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY');
+Before executing a swap, you must generate a signed quote using the `getSignedUniswapQuote` function:
 
-// Initialize the Vincent Ability Client
-const abilityClient = getVincentAbilityClient({
-  ethersSigner: delegateeSigner,
-  bundledVincentAbility,
+```typescript
+import { LitNodeClient } from '@lit-protocol/lit-node-client';
+import { getSignedUniswapQuote } from '@lit-protocol/vincent-ability-uniswap-swap';
+import { ethers } from 'ethers';
+
+// Initialize Lit Node Client
+const litNodeClient = new LitNodeClient({
+  litNetwork: 'datil',
+  debug: true,
 });
-const delegatorPkpEthAddress = '0x09182301238'; // The delegator PKP Eth Address
-
-const abilityParams = {
-  chainId: '8453', // The chain where the tx will be executed
-  tokenIn: '0x1234...', // The input token address
-  amountIn: '1000000000000000000', // The input amount (in wei)
-  tokenOut: '0xabcd...', // The output token address
-  rpcUrl: 'https://mainnet.base.org', // The RPC to send the transaction through
-};
-
-// Run precheck to see if ability should be executed
-const precheckResult = await client.precheck(abilityParams, {
-  delegatorPkpEthAddress,
+await litNodeClient.connect();
+
+// Your delegatee signer (one of the delegatee signers for the Vincent App)
+const delegateeSigner = new ethers.Wallet('YOUR_DELEGATEE_PRIVATE_KEY', provider);
+
+// Generate the signed quote
+const signedUniswapQuote = await getSignedUniswapQuote({
+  quoteParams: {
+    rpcUrl: 'https://mainnet.base.org',
+    tokenInAddress: '0x4ed4E862860beD51a9570b96d89aF5E1B0Efefed', // DEGEN
+    tokenInAmount: '80', // Amount in token's smallest unit
+    tokenOutAddress: '0x4200000000000000000000000000000000000006', // WETH
+    recipient: delegatorPkpEthAddress, // The PKP that will execute the swap
+  },
+  ethersSigner: delegateeSigner,
+  litNodeClient,
 });
+```
 
-if (precheckResult.success === true) {
-  // Execute the Vincent Ability
-  const executeResult = await client.execute(abilityParams, {
-    delegatorPkpEthAddress,
-  });
+The return value of `getSignedUniswapQuote` is an object containing:
 
-  // ...ability has executed, you can check `executeResult` for details
-}
-```
+- `quote`: The Uniswap Quote/Route generated by the V3 SDK using the Alpha Router
+- `signature`: A signature of `quote` signed by a Lit PKP that is configured to only ever be able to sign these generated Uniswap Quotes within the specific Lit Action configured by this Ability
+- `dataSigned`: The data signed by the PKP, an ETH Personal Message containing the hash of the stringified `quote`
+- `signerPublicKey`: The public key of the PKP that signed the `quote`
+- `signerEthAddress`: The Ethereum address of the PKP that signed the `quote`
 
-## Integration with Policies
+Because the Uniswap SDK makes a lot of RPC calls when generating a quote/route, it exceeded the usage limits of Lit Actions when running within the same Lit Action as the Vincent logic for checking and executing Policies, and verifying on-chain delegation.
 
-This ability is integrated with the Vincent Policy Spending Limit to enforce spending constraints:
+So, the purpose of `getSignedUniswapQuote` is to generate a signed quote/route outside of the Vincent Ability Lit Action, and then provide it to the `precheck` and `execute` functions in a tamper-proof manner. The Vincent Delegatee is unable to modify the quote/route after it has been signed by the PKP, because the Ability verifies the provided route data was signed by the hardcoded PKP address.
+
+### 2. Run Precheck
+
+Provide the signed `quote` to `precheck` to check if the swap can be executed:
 
 ```typescript
-import {
-  createVincentAbilityPolicy,
-  createVincentAbility,
-  createPolicyMapFromAbilityPolicies,
-} from '@lit-protocol/vincent-ability-sdk';
-import { bundledVincentPolicy } from '@lit-protocol/vincent-policy-spending-limit';
-import { abilityParamsSchema } from '@lit-protocol/vincent-ability-uniswap-swap';
-
-const spendingLimitPolicy = createVincentAbilityPolicy({
-  abilityParamsSchema,
-  bundledVincentPolicy,
-  abilityParameterMappings: {
-    pkpEthAddress: 'pkpEthAddress',
-    ethRpcUrl: 'ethRpcUrl',
-    tokenInAddress: 'tokenAddress',
-    tokenInDecimals: 'tokenDecimals',
-    tokenInAmount: 'buyAmount',
-  },
-});
+import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
+import { bundledVincentAbility } from '@lit-protocol/vincent-ability-uniswap-swap';
 
-export const uniswapSwapWithSpendingLimit = createVincentAbility({
-  abilityParamsSchema,
-  policyMap: createPolicyMapFromAbilityPolicies([spendingLimitPolicy]),
-  // ... rest of ability implementation
+// Initialize the ability client
+const abilityClient = getVincentAbilityClient({
+  bundledVincentAbility,
+  ethersSigner: delegateeSigner,
 });
-```
 
-## Prerequisites
+// Run precheck with the signed quote
+const precheckResult = await abilityClient.precheck(
+  {
+    rpcUrlForUniswap: 'https://mainnet.base.org',
+    signedUniswapQuote: {
+      quote: signedUniswapQuote.quote,
+      signature: signedUniswapQuote.signature,
+    },
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The delegator PKP ETH address
+  },
+);
 
-Before executing a swap, ensure that:
+if (precheckResult.success) {
+  console.log('Swap can be executed');
+}
+```
 
-1. The user has approved the input token for the Uniswap router
-2. The user has sufficient balance of the input token
-3. The user has delegated permission to the Vincent app to execute swaps
+### 3. Execute the Swap
 
-You can use the Vincent Ability ERC20 Approval to handle token approvals:
+If `precheck` succeeds, execute the swap using the same signed `quote`:
 
 ```typescript
-import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
-import { ERC20_APPROVAL_TOOL_IPFS_ID } from '@lit-protocol/vincent-ability-erc20-approval';
+const executeResult = await abilityClient.execute(
+  {
+    rpcUrlForUniswap: 'https://mainnet.base.org',
+    signedUniswapQuote: {
+      quote: signedUniswapQuote.quote,
+      signature: signedUniswapQuote.signature,
+    },
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The delegator PKP ETH address
+  },
+);
 
-// ... approve tokens before swap
+if (executeResult.success) {
+  console.log('Swap executed successfully!');
+  console.log('Transaction hash:', executeResult.result.swapTxHash);
+}
 ```
 
-## Building
-
-Run `nx build ability-uniswap-swap` to build the library.
+A complete example of generating the signed `quote`, running `precheck`, and executing the swap is available in the `abilities-e2e`'s end-to-end [swap.spec.ts](../abilities-e2e/test-e2e/swap.spec.ts) test.
 
-## Running unit tests
+## Development
 
-Run `nx test ability-uniswap-swap` to execute the unit tests via [Jest](https://jestjs.io).
+Because of the need for the `getSignedUniswapQuote` function and it's corresponding Lit Action, included in this package is a script ([create-pkp-for-prepare.js](./scripts/create-pkp-for-prepare.js)) that is used to mint the PKP that is configured to only ever be able to sign these generated Uniswap Quotes within the specific Lit Action configured by this Ability.
 
-## Contributing
+Anytime changes are made to the [Prepare Lit Action](./src/lib/prepare/lit-action.ts), you **MUST** run the PKP minting script to update the PKP info recorded in [vincent-prepare-metadata.json](./src/generated/vincent-prepare-metadata.json) file. You can execute the script using the Nx target:
 
-Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute to this project.
+```
+pnpm nx run ability-uniswap-swap:action:create-pkp
+```
 
-## License
+This will run the `action:deploy` target, which will build the Prepare Lit Action and deploy it to IPFS, recording the IPFS CID in `vincent-prepare-metadata.json` file. Then the `create-pkp-for-prepare.js` script will be executed minting a new PKP that has the IPFS CID of the Prepare Lit Action as the only permitted Auth Method.
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+After making any changes to the Prepare Lit Action, generating a new signer PKP, run the `build` target to update the Swap Ability Lit Action with the new PKP ETH address used for verifying the `quote` signatures.

package/dist/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@lit-protocol/vincent-ability-uniswap-swap",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lit-protocol/vincent-policy-spending-limit": "workspace:*",
+    "@lit-protocol/lit-node-client": "^7.2.3",
     "@lit-protocol/vincent-ability-sdk": "workspace:*",
+    "@lit-protocol/vincent-app-sdk": "workspace:*",
     "@uniswap/sdk-core": "^7.7.2",
+    "@uniswap/smart-order-router": "^4.22.9",
     "ethers": "^5.8.0",
+    "json-stable-stringify": "^1.3.0",
     "tslib": "2.8.1",
     "zod": "^3.25.64"
   },
@@ -20,9 +23,8 @@
     "@lit-protocol/auth-helpers": "^7.2.3",
     "@lit-protocol/constants": "^7.2.3",
     "@lit-protocol/contracts-sdk": "^7.2.3",
-    "@lit-protocol/lit-node-client": "^7.2.3",
+    "@lit-protocol/esbuild-plugin-polyfill-node": "^0.3.0",
     "esbuild": "^0.19.12",
-    "esbuild-plugin-polyfill-node": "^0.3.0",
     "ipfs-only-hash": "^4.0.0",
     "viem": "^2.28.0"
   },