feat: predicate sdk & cli support (#8224)

Author: troykessler

.changeset/predicate-cli-integration.md

@@ -0,0 +1,12 @@
+---
+'@hyperlane-xyz/cli': minor
+---
+
+Added CLI support for Predicate attestations in warp send command.
+
+CLI Changes:
+- Added `--predicate-api-key` option to `warp send` for automatic attestation fetching from Predicate API
+- Added `--attestation` option to `warp send` for using pre-obtained attestations (JSON string)
+- Detected PredicateRouterWrapper address and sent to Predicate API for correct attestation target
+- Added E2E tests for warp send with Predicate attestations
+- Added example YAML configs for Predicate warp routes

.changeset/predicate-wrapper-sdk.md

@@ -0,0 +1,23 @@
+---
+'@hyperlane-xyz/sdk': major
+---
+
+Added Predicate integration for compliance-gated warp route transfers
+
+- Added `PredicateWrapperConfigSchema` for configuring predicate wrapper deployment
+- Added `PredicateApiClient` for fetching attestations from Predicate API
+- Added `PredicateWrapperDeployer` for deploying and configuring PredicateRouterWrapper contracts
+- Integrated predicate wrapper deployment into warp route deployment flow
+- Supported aggregation hooks with predicate wrapper (wrapper executes first)
+- Always aggregated predicate wrapper with mailbox default hook to ensure gas quoting works correctly
+- Detected PredicateRouterWrapper recursively inside nested aggregation hooks
+
+Example configuration:
+```yaml
+ethereum:
+  type: collateral
+  token: '0x...'
+  predicateWrapper:
+    predicateRegistry: '0xe15a8Ca5BD8464283818088c1760d8f23B6a216E'
+    policyId: 'x-your-policy-id'
+```

.github/workflows/test-cli-e2e.yml

@@ -44,7 +44,9 @@ jobs:
         test:
           - core-deploy
           - warp-deploy-1
+          - warp-deploy-predicate
           - warp-apply-simple-updates
+          - warp-apply-predicate-updates
           - warp-check-1
           - warp-send
     steps:
@@ -90,6 +92,7 @@ jobs:
           - warp-apply-hook-updates
           - warp-apply-ism-updates
           - warp-apply-ownership-updates
+          - warp-apply-predicate-updates
           - warp-apply-rebalancing-config
           - warp-apply-simple-updates
           - warp-apply-submitters
@@ -102,6 +105,7 @@ jobs:
           - warp-bridge-2
           - warp-deploy-1
           - warp-deploy-2
+          - warp-deploy-predicate
           - warp-deploy-remote-routers
           # check
           - warp-check-1
@@ -115,6 +119,7 @@ jobs:
           - warp-read
           - warp-rebalancer
           - warp-send
+          - warp-send-predicate
           # xerc20
           - xerc20
     steps:

solidity/soldeer.lock

@@ -28,6 +28,12 @@ version = "4.9.3"
 git = "https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable.git"
 rev = "3d4c0d5741b131c231e558d7a6213392ab3672a5"
 
+[[dependencies]]
+name = "@predicate-contracts"
+version = "2.2.2"
+git = "https://github.com/predicatelabs/predicate-contracts.git"
+rev = "v2.2.2"
+
 [[dependencies]]
 name = "forge-std"
 version = "1.9.2"

typescript/cli/examples/warp-base.yaml

@@ -0,0 +1,24 @@
+base:
+  owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+  mailbox: '0xeA87ae93Fa0019a82A727bfd3eBd1cFCa8f64f1D'
+  hook:
+    type: predicateHook
+    address: '0x9995F95aaA827347Bc2AAbF862dF75Ead6E8b97a'
+  interchainSecurityModule: '0x0000000000000000000000000000000000000000'
+  remoteRouters:
+    '1':
+      address: '0x0000000000000000000000005f72c2d341884ddf0f8a18155d8172f56ae1eeec'
+  name: USD Coin
+  symbol: USDC
+  decimals: 6
+  isNft: false
+  contractVersion: 10.1.5
+  type: collateral
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
+  allowedRebalancers: []
+  allowedRebalancingBridges: {}
+  proxyAdmin:
+    address: '0x475bB419502213fdb44d89ad94A1234fA3d7B2f9'
+    owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+  destinationGas:
+    '1': '64000'

typescript/cli/examples/warp-config-predicate-mainnet.yaml

@@ -0,0 +1,14 @@
+base:
+  type: collateral
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
+  mailbox: '0xeA87ae93Fa0019a82A727bfd3eBd1cFCa8f64f1D'
+  owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+  predicateWrapper:
+    predicateRegistry: '0xe15a8Ca5BD8464283818088c1760d8f23B6a216E'
+    policyId: 'x-managed-policy-157b68744498ccac3201a806ef6036ac'
+    owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+
+ethereum:
+  type: synthetic
+  mailbox: '0xc005dc82818d67AF737725bD4bf75435d065D239'
+  owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'

typescript/cli/examples/warp-deployed-predicate-mainnet.yaml

@@ -0,0 +1,19 @@
+tokens:
+  - chainName: base
+    standard: EvmHypCollateral
+    decimals: 6
+    symbol: USDC
+    name: USD Coin
+    addressOrDenom: '0x659CAFbe5A0A5B8357192E7C280Fd1f77C28Bd9C'
+    collateralAddressOrDenom: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
+    connections:
+      - token: 'ethereum|ethereum|0x5f72C2D341884Ddf0F8A18155d8172f56Ae1eEEc'
+
+  - chainName: ethereum
+    standard: EvmHypSynthetic
+    decimals: 6
+    symbol: USDC
+    name: USD Coin
+    addressOrDenom: '0x5f72C2D341884Ddf0F8A18155d8172f56Ae1eEEc'
+    connections:
+      - token: 'ethereum|base|0x659CAFbe5A0A5B8357192E7C280Fd1f77C28Bd9C'

typescript/cli/examples/warp-ethereum.yaml

@@ -0,0 +1,19 @@
+ethereum:
+  owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+  mailbox: '0xc005dc82818d67AF737725bD4bf75435d065D239'
+  hook: '0x0000000000000000000000000000000000000000'
+  interchainSecurityModule: '0x0000000000000000000000000000000000000000'
+  remoteRouters:
+    '8453':
+      address: '0x000000000000000000000000659cafbe5a0a5b8357192e7c280fd1f77c28bd9c'
+  name: USD Coin
+  symbol: USDC
+  decimals: 6
+  isNft: false
+  contractVersion: 10.1.5
+  type: synthetic
+  proxyAdmin:
+    address: '0x0fbF624e7FD62e01f83862AFdc6a33A6338dB857'
+    owner: '0x380ad2e410688e0153125d01a6af9c4C27F7F0eC'
+  destinationGas:
+    '8453': '68000'

typescript/cli/package.json

@@ -25,7 +25,7 @@
   "types": "./dist/src/index.d.ts",
   "scripts": {
     "hyperlane": "node ./dist/cli.js",
-    "build": "pnpm version:update && tsc",
+    "build": "pnpm version:update && NODE_OPTIONS='--max-old-space-size=4096' tsc",
     "bundle": "rm -rf ./bundle && ncc build ./dist/cli.js -o bundle && node ../../scripts/ncc.post-bundle.mjs",
     "dev": "pnpm version:update && tsc --watch",
     "clean": "rm -rf ./dist && rm -rf ./bundle",

typescript/cli/src/commands/warp.ts

@@ -349,6 +349,9 @@ const send: CommandModuleWithWriteContext<
       recipient?: string;
       chains?: string[];
       skipValidation?: boolean;
+      predicateApiKey?: string;
+      predicateApiUrl?: string;
+      attestation?: string;
       sourceToken?: string;
       destinationToken?: string;
       feeQuotingUrl?: string;
@@ -380,6 +383,23 @@ const send: CommandModuleWithWriteContext<
       description: 'Skip transfer validation (e.g., collateral checks)',
       default: false,
     },
+    'predicate-api-key': {
+      type: 'string',
+      description: 'Predicate API key for fetching attestations automatically',
+      default: process.env.PREDICATE_API_KEY,
+      conflicts: 'attestation',
+    },
+    'predicate-api-url': {
+      type: 'string',
+      description:
+        'Predicate API base URL (overrides default; useful for testing)',
+      default: process.env.PREDICATE_API_URL,
+      implies: 'predicate-api-key',
+    },
+    attestation: {
+      type: 'string',
+      description: 'Pre-obtained Predicate attestation (JSON string)',
+    },
     'source-token': {
       type: 'string',
       description:
@@ -408,12 +428,17 @@ const send: CommandModuleWithWriteContext<
     timeout,
     quick,
     relay,
+    symbol: _symbol,
+    warp: _warp,
     warpRouteId,
     amount,
     recipient,
     roundTrip,
     chains: chainsArg,
     skipValidation,
+    predicateApiKey,
+    predicateApiUrl,
+    attestation,
     sourceToken,
     destinationToken,
     feeQuotingUrl,
@@ -495,6 +520,9 @@ const send: CommandModuleWithWriteContext<
       skipWaitForDelivery: quick,
       selfRelay: relay,
       skipValidation,
+      predicateApiKey,
+      predicateApiUrl,
+      attestation,
       sourceToken,
       destinationToken,
       feeQuotingUrl,