@lit-protocol/vincent-policy-contract-whitelist 0.0.12-mma → 1.0.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.0.1 (2025-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.0.1
+- Updated app-sdk to 2.0.1
+
 # 1.0.0 (2025-08-05)
 
 ### ⚠️ Breaking Changes

package/dist/CHANGELOG.md

@@ -0,0 +1,21 @@
+## 1.0.1 (2025-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.0.1
+- Updated app-sdk to 2.0.1
+
+# 1.0.0 (2025-08-05)
+
+### ⚠️ Breaking Changes
+
+- #### Define uiSchema/jsonSchema for registry usage ([cebcee0c](https://github.com/LIT-Protocol/Vincent/commit/cebcee0c))
+
+### 🧱 Updated Dependencies
+
+- Updated ability-sdk to 2.0.0
+- Updated app-sdk to 2.0.0
+
+### ❤️ Thank You
+
+- Daryl Collins

package/dist/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Vincent Policy Contract Whitelist
+
+This document provides guidelines for contributing to the Vincent Policy Contract Whitelist project.
+
+## Overview
+
+<!-- TODO -->
+
+## 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 policy-contract-whitelist
+```
+
+### Building the Lit Action
+
+Build the policy:
+
+```bash
+nx action:build policy-contract-whitelist
+```
+
+### Deploying the Lit Action to IPFS
+
+Building will be done automatically. Deploy the policy:
+
+```bash
+nx action:deploy policy-contract-whitelist
+```
+
+## Project Structure
+
+- `src/`: Source code
+  - `index.ts`: Main entry point
+
+## Policy Development Guidelines
+
+1. Use the Vincent Ability SDK to create policies
+2. Define clear schemas for ability parameters and user parameters
+3. Implement the policy lifecycle methods (evaluate, commit)
+4. Handle errors gracefully
+5. Write comprehensive tests for all functionality
+6. Document the policy's purpose and usage
+
+## Integration with Abilities
+
+<!-- TODO -->
+
+## Testing
+
+Write unit tests for all functionality:
+
+```bash
+pnpm test
+```
+
+## Documentation
+
+- Document the policy's purpose and usage
+- Update README.md when adding new features
+- Document the policy'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,146 @@
+# Vincent Policy: Contract Whitelist
+
+## Overview
+
+The Contract Whitelist Policy enforces strict access control for blockchain transactions by ensuring that Vincent Apps can only interact with
+pre-approved smart contracts and execute specific whitelisted functions on those contracts.
+
+This Vincent Policy is designed to work with Vincent Abilities, particularly the [@lit-protocol/vincent-ability-evm-transaction-signer](../ability-evm-transaction-signer/) ability, to provide granular control over which transactions can be signed.
+
+## Key Features
+
+- **Multi-chain Support**: Configure whitelists for multiple blockchain networks
+- **Granular Function Control**: Specify which functions are whitelisted using the Solidity function signature
+- **Wildcard Support**: Allow all functions for trusted contracts using the `*` wildcard
+
+## How It Works
+
+The Contract Whitelist Policy is built using the Vincent Policy SDK and validates transactions against a hierarchical whitelist. Here's how it operates:
+
+1. **Transaction Parsing**: Receives a serialized EVM transaction and parses it using ethers.js
+2. **Data Extraction**: Extracts the chain ID (the `chainId` field in the transaction), target contract address (the `to` field in the transaction), and function selector (first 4 bytes of the transaction `data` field)
+3. **Whitelist Validation**: Checks the transaction against the configured on-chain whitelist:
+   - Is the chain ID whitelisted?
+   - Is the contract address whitelisted for that chain?
+   - Is the function selector allowed (explicitly or via wildcard)?
+4. **Result**: Returns an allow or deny decision with detailed information
+
+## Example Configuration
+
+```typescript
+const policyConfig = {
+  whitelist: {
+    // Ethereum Mainnet
+    '1': {
+      // WETH Contract - Specific functions only
+      '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2': {
+        functionSelectors: [
+          '0xa9059cbb', // transfer(address,uint256)
+          '0x23b872dd', // transferFrom(address,address,uint256)
+        ],
+      },
+      // USDC Contract - Single function only
+      '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': {
+        functionSelectors: [
+          '0xa9059cbb', // transfer(address,uint256)
+        ],
+      },
+    },
+    // Base Mainnet
+    '8453': {
+      // Base WETH - All functions allowed via wildcard
+      '0x4200000000000000000000000000000000000006': {
+        functionSelectors: ['*'], // Allow ALL functions for this contract
+      },
+      // Another contract with mixed approach
+      '0x1234567890123456789012345678901234567890': {
+        functionSelectors: [
+          '0xa9059cbb', // transfer(address,uint256) - explicitly allowed
+          '*', // Plus all other functions via wildcard
+        ],
+      },
+    },
+  },
+};
+```
+
+### Wildcard Support
+
+The policy supports using `'*'` as a wildcard to allow all functions for a specific contract:
+
+- **Specific selectors only**: `['0xa9059cbb', '0x23b872dd']` - Only these exact functions are allowed
+- **Wildcard only**: `['*']` - All functions are allowed for this contract
+- **Mixed approach**: `['0xa9059cbb', '*']` - All functions are allowed (wildcard takes precedence)
+
+**Security Note**: Use wildcards carefully! Only use `'*'` for contracts you fully trust, as it allows any function call to that contract.
+
+## Integration with Abilities
+
+The Contract Whitelist Policy is designed to work seamlessly with Vincent Abilities, particularly the [Transaction Signer Ability](../ability-evm-transaction-signer/README.md):
+
+```typescript
+import { createVincentAbilityPolicy } from '@lit-protocol/vincent-ability-sdk';
+import { bundledVincentPolicy } from '@lit-protocol/vincent-policy-contract-whitelist';
+
+const ContractWhitelistPolicy = createVincentAbilityPolicy({
+  abilityParamsSchema,
+  bundledVincentPolicy,
+  abilityParameterMappings: {
+    serializedTransaction: 'serializedTransaction',
+  },
+});
+```
+
+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
+
+## Output Schemas
+
+### Precheck/Evaluation Allow Result
+
+```typescript
+{
+  chainId: number; // The validated chain ID
+  contractAddress: string; // The validated contract address
+  functionSelector: string; // The validated function selector
+  wildcardUsed: boolean; // Whether the wildcard "*" was used to allow this function
+}
+```
+
+The `wildcardUsed` property indicates whether the transaction was allowed through the wildcard (`'*'`) or through an explicit function selector:
+
+- `true`: The function was allowed via wildcard (function selector not explicitly listed)
+- `false`: The function was explicitly whitelisted (even if wildcard is also present)
+
+This information is valuable for auditing and security monitoring purposes.
+
+### Precheck/Evaluation Deny Result
+
+```typescript
+{
+  reason: string;                    // Why the transaction was denied
+  chainId?: number;                  // The chain ID (if available)
+  contractAddress?: string;          // The contract address (if available)
+  functionSelector?: string;         // The function selector (if available)
+}
+```
+
+## Building
+
+Run `pnpx nx build policy-contract-whitelist` to build the library.
+
+## 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,6 +1,6 @@
 {
   "name": "@lit-protocol/vincent-policy-contract-whitelist",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "publishConfig": {
     "access": "public"
   },