Vincent Policy: Bitcoin Bridge

Overview

The Bitcoin Bridge Policy validates that Bitcoin bridge transactions only send funds to approved Bitcoin addresses. This policy works with the @vaultlayer/vincent-ability-btc-bridge ability to provide security controls for cross-chain Bitcoin bridging operations.

Key Features

• Address Whitelisting: Validates destination Bitcoin addresses against allowed outputs
• PKP Address Auto-inclusion: Automatically includes PKP's derived Bitcoin address in allowed list
• Network Support: Supports both Bitcoin testnet and mainnet
• Flexible Configuration: Empty whitelist defaults to PKP address only
• Secure Derivation: Derives Bitcoin address from PKP public key using secp256k1 compression

How It Works

The Bitcoin Bridge Policy performs the following validation:

1. PKP Address Derivation: Derives a Bitcoin address from the PKP's public key

   • Compresses Ethereum public key (uncompressed format) to secp256k1 format
   • Derives P2WPKH (native SegWit) address
   • Supports both testnet and mainnet networks

2. Destination Address Resolution:

   • If destinationBtcAddress is not provided, defaults to PKP-derived address
   • If provided, uses the specified address

3. Allowed Outputs Building:

   • If allowedOutputs is empty, defaults to [pkpBtcAddress]
   • If allowedOutputs is provided, automatically includes PKP address if not already present
   • Final allowed list always includes the PKP address

4. Validation: Checks if the destination address is in the allowed outputs list

Installation

npm install @vaultlayer/vincent-policy-btc-bridge
# or
pnpm add @vaultlayer/vincent-policy-btc-bridge
# or
yarn add @vaultlayer/vincent-policy-btc-bridge

Usage

Basic Usage

import { bundledVincentPolicy } from '@vaultlayer/vincent-policy-btc-bridge';
import { createVincentAbilityPolicy } from '@lit-protocol/vincent-ability-sdk';

const BtcBridgePolicy = createVincentAbilityPolicy({
  abilityParamsSchema: myAbilityParamsSchema,
  bundledVincentPolicy,
  abilityParameterMappings: {
    destinationBtcAddress: 'destinationBtcAddress',
    btcNetwork: 'btcNetwork',
  },
});

// Configure with allowed outputs
const policyConfig = {
  allowedOutputs: [
    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', // Specific address
    'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4', // Another allowed address
    // PKP address is automatically included
  ],
};

Empty Whitelist (PKP Only)

const policyConfig = {
  allowedOutputs: [], // Empty - only PKP address allowed
};

Parameters

User Parameters (Policy Configuration)

allowedOutputs

• Type: string[]
• Required: Yes
• Description: Array of allowed Bitcoin output addresses
• Example: ['bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh', 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4']
• Behavior:
  • Empty array defaults to PKP address only
  • PKP address is automatically included if not present

Ability Parameters (From Ability)

destinationBtcAddress

• Type: string | undefined
• Required: No
• Description: Destination Bitcoin address (optional - defaults to PKP-derived address)
• Example: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'

btcNetwork

• Type: 'testnet' | 'livenet'
• Required: Yes
• Description: The Bitcoin network (testnet or mainnet)
• Note: Affects PKP address derivation

Policy Behavior

Allow Conditions

The policy will allow execution when:

• destinationBtcAddress is provided and is in the allowedOutputs list
• destinationBtcAddress is not provided (defaults to PKP address) and PKP address is in allowed list
• PKP address can be successfully derived from the public key

Deny Conditions

The policy will deny execution when:

• destinationBtcAddress is provided but is not in the allowedOutputs list
• PKP address cannot be derived from the public key
• Public key format is unsupported

Response Format

Allow Response

{
  destinationBtcAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  pkpBtcAddress: 'bc1qpkpderivedaddress...',
  isAllowed: true
}

Deny Response

{
  allow: false,
  reason: 'Destination Bitcoin address bc1q... is not in the allowed list',
  destinationBtcAddress: 'bc1q...',
  pkpBtcAddress: 'bc1qpkpderivedaddress...'
}

Address Derivation

The policy derives Bitcoin addresses from PKP public keys:

1. Public Key Format: Expects uncompressed Ethereum public key (0x + 130 hex chars = 132 chars)
2. Compression: Uses secp256k1 compression to convert to 33-byte compressed format
3. Address Generation: Creates P2WPKH (native SegWit) address using bitcoinjs-lib
4. Network: Respects btcNetwork parameter (testnet or mainnet)

Examples

Single Allowed Address

const policyConfig = {
  allowedOutputs: ['bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'],
};

// This allows:
// - Bridging to the specified address
// - Bridging to PKP address (automatically included)

Multiple Allowed Addresses

const policyConfig = {
  allowedOutputs: [
    'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
    'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4',
    'bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3',
  ],
  // PKP address is automatically added
};

// This allows bridging to:
// - Any of the three specified addresses
// - PKP address

PKP Only (Most Restrictive)

const policyConfig = {
  allowedOutputs: [], // Empty - only PKP address
};

// This only allows bridging to PKP's derived Bitcoin address

Custom Address + PKP

const policyConfig = {
  allowedOutputs: ['bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'],
  // PKP address automatically included
};

// This allows:
// - The specified address
// - PKP address (even if not explicitly listed)

Use Cases

1. Self-Custody: Restrict bridges to PKP address only for maximum security
2. Multi-Address Wallets: Allow bridging to multiple known addresses
3. Corporate Wallets: Whitelist specific company Bitcoin addresses
4. Vault Management: Control where bridged Bitcoin can be sent
5. Security Policies: Enforce address restrictions for compliance

Security Considerations

• Address Validation: Always validates addresses are in allowed list
• PKP Auto-inclusion: PKP address is always allowed (for recovery)
• Network Separation: Different networks (testnet/mainnet) use different addresses
• Public Key Security: PKP public key derivation is deterministic and secure
• No Sensitive Data: Only validates addresses, doesn't expose private keys

Integration with Ability

This policy is designed to work with the Bitcoin Bridge Ability:

import { bundledVincentAbility } from '@vaultlayer/vincent-ability-btc-bridge';
import { bundledVincentPolicy } from '@vaultlayer/vincent-policy-btc-bridge';

// Create policy
const BtcBridgePolicy = createVincentAbilityPolicy({
  abilityParamsSchema,
  bundledVincentPolicy,
  abilityParameterMappings: {
    destinationBtcAddress: 'destinationBtcAddress',
    btcNetwork: 'btcNetwork',
  },
});

// Execute with policy
const result = await executeAbility({
  ability: bundledVincentAbility,
  policy: BtcBridgePolicy,
  params: {
    action: 'bridge',
    sourceChain: 'base',
    amount: '0.1',
    btcNetwork: 'livenet',
    destinationBtcAddress: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  },
  userParams: {
    allowedOutputs: ['bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh'],
  },
});

Related Packages

• @vaultlayer/vincent-ability-btc-bridge - The ability that uses this policy
• @lit-protocol/vincent-ability-sdk - SDK for building Vincent Abilities and Policies
• bitcoinjs-lib - Bitcoin utilities
• @noble/secp256k1 - secp256k1 cryptography

License

MIT