@lit-protocol/vincent-ability-evm-transaction-signer 0.0.2-ea → 0.0.2

package/CHANGELOG.md

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

package/README.md

@@ -1,34 +1,42 @@
-# Vincent Ability: Transaction Signer
+# Vincent Ability: EVM 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.
+The EVM Transaction Signer Ability enables Vincent Apps to sign Ethereum Virtual Machine (EVM) transactions on behalf of Vincent Users using their Vincent Agent Wallets. This enables Vincent Apps to interact with contracts even if there isn't an explicit Vincent Ability made for interacting with that contract.
 
 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.
 
+## Key Features
+
+- **Secure Transaction Signing**: Signs transactions using Vincent Agent Wallets within Lit Protocol's secure Trusted Execution Environment
+- **Full Transaction Support**: Handles all EVM transaction types including legacy, EIP-2930, and EIP-1559
+- **Policy Integration**: Supports the Contract Whitelist Policy for restricting what transactions can be signed
+
 ## 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
+1. **Precheck Phase**: Validates the transaction structure and runs policy checks
+
+   - Deserializes the provided serialized transaction using ethers.js
+   - Validates all required fields are present (nonce, gasPrice, gasLimit, etc.)
+   - Returns deserialized transaction details for review
+
+2. **Execution Phase**: If permitted by the evaluated Policies, signs the serialized transaction
+   - Signs the transaction using the Vincent Agent Wallet
+   - Returns both the signed transaction hex and decoded signature components
 
 ### Workflow
 
-1. **Precheck Phase**:
+1. **Precheck Phase**: Validates the transaction structure and runs policy checks
 
-   - 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
+   - Deserializes the provided serialized transaction using ethers.js
+   - Validates all required fields are present (nonce, gasPrice, gasLimit, etc.)
+   - Returns deserialized transaction details for review
 
-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
+2. **Execution Phase**: If permitted by the evaluated Policies, signs the serialized transaction
+   - Signs the transaction using the Vincent Agent Wallet
+   - Returns both the signed transaction hex and decoded signature components
 
 ## Using the Ability
 

package/dist/CHANGELOG.md

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

package/dist/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/dist/README.md

@@ -0,0 +1,174 @@
+# Vincent Ability: EVM Transaction Signer
+
+## Overview
+
+The EVM Transaction Signer Ability enables Vincent Apps to sign Ethereum Virtual Machine (EVM) transactions on behalf of Vincent Users using their Vincent Agent Wallets. This enables Vincent Apps to interact with contracts even if there isn't an explicit Vincent Ability made for interacting with that contract.
+
+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.
+
+## Key Features
+
+- **Secure Transaction Signing**: Signs transactions using Vincent Agent Wallets within Lit Protocol's secure Trusted Execution Environment
+- **Full Transaction Support**: Handles all EVM transaction types including legacy, EIP-2930, and EIP-1559
+- **Policy Integration**: Supports the Contract Whitelist Policy for restricting what transactions can be signed
+
+## 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:
+
+1. **Precheck Phase**: Validates the transaction structure and runs policy checks
+
+   - Deserializes the provided serialized transaction using ethers.js
+   - Validates all required fields are present (nonce, gasPrice, gasLimit, etc.)
+   - Returns deserialized transaction details for review
+
+2. **Execution Phase**: If permitted by the evaluated Policies, signs the serialized transaction
+   - Signs the transaction using the Vincent Agent Wallet
+   - Returns both the signed transaction hex and decoded signature components
+
+### Workflow
+
+1. **Precheck Phase**: Validates the transaction structure and runs policy checks
+
+   - Deserializes the provided serialized transaction using ethers.js
+   - Validates all required fields are present (nonce, gasPrice, gasLimit, etc.)
+   - Returns deserialized transaction details for review
+
+2. **Execution Phase**: If permitted by the evaluated Policies, signs the serialized transaction
+   - Signs the transaction using the Vincent Agent Wallet
+   - Returns both the signed transaction hex and decoded signature components
+
+## 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

@@ -1,12 +1,12 @@
 {
   "name": "@lit-protocol/vincent-ability-evm-transaction-signer",
-  "version": "0.0.1-ea",
+  "version": "0.0.2",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@lit-protocol/vincent-policy-contract-whitelist": "0.0.3-ea",
-    "@lit-protocol/vincent-ability-sdk": "0.0.2-ea",
+    "@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"