@lit-protocol/vincent-ability-evm-transaction-signer 0.0.1-ea

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.0.2 (2025-08-01)
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.0.0
+- Updated app-sdk to 2.0.0
+- Updated policy-contract-whitelist to 0.0.2

package/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing to Vincent Ability Transaction Signer
+
+This document provides guidelines for contributing to the Vincent Ability Transaction Signer project.
+
+## Overview
+
+The Vincent Ability Transaction Signer is a ability to sign transactions using a Vincent Agent Wallet. 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-evm-transaction-signer
+```
+
+### Building the Lit Action
+
+Build the policy:
+
+```bash
+nx action:build ability-evm-transaction-signer
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the policy:
+
+```bash
+nx action:deploy ability-evm-transaction-signer
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+
+## Ability Development Guidelines
+
+1. Use the Vincent Ability SDK to create abilities
+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 Contract Whitelist
+
+## 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)

package/README.md

@@ -0,0 +1,166 @@
+# Vincent Ability: Transaction Signer
+
+## Overview
+
+The Transaction Signer Ability enables Vincent Agent Wallets to sign EVM transactions utilizing the Vincent ecosystem to govern who can request signatures, as well as what's included in the transactions.
+
+This Vincent Ability is intended to be used with Vincent Policies, such as the [@lit-protocol/vincent-policy-contract-whitelist](../policy-contract-whitelist/) policy, to provide protections such as only signing transactions that interact with specific contracts and/or call specific functions on contract.
+
+## How It Works
+
+The Transaction Signer Ability is built using the Vincent Ability SDK and provides a secure way to sign Ethereum transactions. Here's how it operates:
+
+- **Input**: Accepts a serialized unsigned EVM transaction
+- **Parsing**: Uses `ethers.utils.parseTransaction` to deserialize and validate the transaction structure
+  - Important: All properties of the transaction are expected to be provided, including `nonce`, `gasPrice`, `gasLimit`, etc. The Ability will not fetch these values from the network on your behalf.
+- **Signing**: The Vincent Agent Wallet (PKP (Programmable Key Pair)) signs the transaction within the Lit Action environment
+- **Output**: Returns both the signed transaction hex and a deserialized version with signature components
+
+### Workflow
+
+1. **Precheck Phase**:
+
+   - Deserializes the input transaction
+   - Validates transaction structure
+   - Executes any registered Vincent Policy to validate the transaction meets the policy requirements
+   - Returns deserialized transaction details if successful
+
+2. **Execution Phase**:
+   - Performs the same validation as the precheck phase
+   - Signs the transaction using the Agent Wallet
+   - Returns both the signed transaction ready for broadcast, and the deserialized signed transaction
+
+## Using the Ability
+
+See the comprehensive E2E test in [contract-whitelist.spec.ts](../abilities-e2e/test-e2e/contract-whitelist.spec.ts) for a complete example of:
+
+- Setting up permissions and the Contract Whitelist Policy
+- Executing the Transaction Signer Ability
+- Validating the signed transaction
+- Broadcasting the signed transaction to the network
+
+```typescript
+import { getVincentAbilityClient } from '@lit-protocol/vincent-app-sdk/abilityClient';
+import { bundledVincentAbility } from '@lit-protocol/vincent-ability-evm-transaction-signer';
+
+// Create ability client
+const abilityClient = getVincentAbilityClient({
+  bundledVincentAbility: bundledVincentAbility,
+  ethersSigner: yourEthersSigner,
+});
+
+// Create a transaction
+const transaction = {
+  to: '0x4200000000000000000000000000000000000006', // Base WETH
+  value: '0x00',
+  data: '0xa9059cbb...', // transfer function call
+  chainId: 8453,
+  nonce: 0,
+  gasPrice: '0x...',
+  gasLimit: '0x...',
+};
+
+// Serialize the transaction
+const serializedTx = ethers.utils.serializeTransaction(transaction);
+
+const precheckResult = await abilityClient.precheck(
+  {
+    serializedTransaction: serializedTx,
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The Agent Wallet PKP that will sign
+  },
+);
+
+if (precheckResult.success) {
+  const { deserializedUnsignedTransaction } = precheckResult.result;
+  // Use the deserialized transaction
+}
+
+// Execute the ability
+const executeResult = await abilityClient.execute(
+  {
+    serializedTransaction: serializedTx,
+  },
+  {
+    delegatorPkpEthAddress: '0x...', // The Agent Wallet PKP that will sign
+  },
+);
+
+if (executeResult.success) {
+  const { signedTransaction, deserializedSignedTransaction } = executeResult.result;
+  // Use the signed transaction
+}
+```
+
+## Input/Output Schemas
+
+### Ability Parameters
+
+```typescript
+{
+  serializedTransaction: string; // The serialized unsigned transaction
+}
+```
+
+### Precheck Success Output
+
+```typescript
+{
+  deserializedUnsignedTransaction: {
+    to?: string;
+    nonce?: number;
+    gasLimit: string;
+    gasPrice?: string;
+    data: string;
+    value: string;
+    chainId: number;
+    type?: number;
+    accessList?: any[];
+    maxPriorityFeePerGas?: string;
+    maxFeePerGas?: string;
+  }
+}
+```
+
+### Execution Success Output
+
+```typescript
+{
+  signedTransaction: string; // The signed transaction ready for broadcast
+  deserializedSignedTransaction: {
+    hash?: string;
+    to: string;
+    from: string;
+    nonce: number;
+    gasLimit: string;
+    gasPrice?: string;
+    data: string;
+    value: string;
+    chainId: number;
+    v: number;
+    r: string;
+    s: string;
+    type?: number;
+    accessList?: any[];
+    maxPriorityFeePerGas?: string;
+    maxFeePerGas?: string;
+  }
+}
+```
+
+## Building
+
+Run `pnpx nx build ability-evm-transaction-signer` to build the Ability.
+
+## Running E2E tests
+
+Run `pnpx nx run abilities-e2e:test-e2e packages/apps/abilities-e2e/test-e2e/contract-whitelist.spec.ts` to execute the E2E tests via [Jest](https://jestjs.io).
+
+## Contributing
+
+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 file for details.

package/dist/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@lit-protocol/vincent-ability-evm-transaction-signer",
+  "version": "0.0.1-ea",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lit-protocol/vincent-policy-contract-whitelist": "workspace:*",
+    "@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"
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist/**",
+    "*.md"
+  ],
+  "type": "commonjs"
+}

package/dist/src/generated/vincent-ability-metadata.json

@@ -0,0 +1,3 @@
+{
+    "ipfsCid": "QmUQ3aCkuvhNL837yPtPXCq8UTZbx2pvwd5JP9NDditUaY"
+}