npm package: @lit-protocol/vincent-ability-uniswap-swap
Description: 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.
Latest version: 8.1.2

# Vincent Ability Uniswap Swap

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 multi-hop swaps through multiple pools
- Support for multiple chains that Uniswap V3 is deployed to

## Installation

```bash
npm install @lit-protocol/vincent-ability-uniswap-swap
```

## Usage

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.

### 1. Generate a Signed Swap Quote

Before executing a swap, you must generate a signed quote using the `getSignedUniswapQuote` function:

```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,
});
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,
});
```

The return value of `getSignedUniswapQuote` is an object containing:

- `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`

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.

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 { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
import { bundledVincentAbility } from '@lit-protocol/vincent-ability-uniswap-swap';

// Initialize the ability client
const abilityClient = getVincentAbilityClient({
  bundledVincentAbility,
  ethersSigner: delegateeSigner,
});

// 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
  },
);

if (precheckResult.success) {
  console.log('Swap can be executed');
}
```

### 3. Execute the Swap

If `precheck` succeeds, execute the swap using the same signed `quote`:

```typescript
const executeResult = await abilityClient.execute(
  {
    rpcUrlForUniswap: 'https://mainnet.base.org',
    signedUniswapQuote: {
      quote: signedUniswapQuote.quote,
      signature: signedUniswapQuote.signature,
    },
  },
  {
    delegatorPkpEthAddress: '0x...', // The delegator PKP ETH address
  },
);

if (executeResult.success) {
  console.log('Swap executed successfully!');
  console.log('Transaction hash:', executeResult.result.swapTxHash);
}
```

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.

## Development

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.

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:

```
pnpm nx run ability-uniswap-swap:action:create-pkp
```

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.

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.