@ocap/tx-pipeline 1.31.1 → 1.31.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/esm/bridge-release-keys.d.mts +33 -0
  2. package/esm/bridge-release-keys.mjs +81 -0
  3. package/esm/bridge-reserves.d.mts +107 -0
  4. package/esm/bridge-reserves.mjs +242 -0
  5. package/esm/helpers/bridge-withdraw.d.mts +86 -0
  6. package/esm/helpers/bridge-withdraw.mjs +123 -0
  7. package/esm/helpers/replay-guard.d.mts +19 -1
  8. package/esm/helpers/replay-guard.mjs +39 -1
  9. package/esm/index.d.mts +3 -1
  10. package/esm/index.mjs +8 -6
  11. package/esm/legacy-protocol-sunset.d.mts +2 -2
  12. package/esm/legacy-protocol-sunset.mjs +5 -5
  13. package/esm/legacy-rollup-archive.d.mts +67 -0
  14. package/esm/legacy-rollup-archive.mjs +199 -0
  15. package/esm/library.d.mts +4 -4
  16. package/esm/library.mjs +3 -3
  17. package/esm/native-abt-exchange.d.mts +3 -0
  18. package/esm/native-abt-exchange.mjs +93 -46
  19. package/esm/pipes/bridge-release-gate.d.mts +30 -0
  20. package/esm/pipes/bridge-release-gate.mjs +143 -0
  21. package/esm/pipes/bridge-reserve-v2-gate.d.mts +53 -0
  22. package/esm/pipes/bridge-reserve-v2-gate.mjs +264 -0
  23. package/esm/pipes/decode-tx.mjs +29 -4
  24. package/esm/pipes/extract-signer.mjs +1 -1
  25. package/esm/pipes/extract-state.mjs +2 -2
  26. package/esm/pipes/post-execution-invariant-gate.d.mts +19 -2
  27. package/esm/pipes/post-execution-invariant-gate.mjs +121 -6
  28. package/esm/pipes/pre-flight-waf.d.mts +18 -1
  29. package/esm/pipes/pre-flight-waf.mjs +48 -13
  30. package/esm/pipes/update-owner.mjs +1 -1
  31. package/esm/pipes/verify-account-migration.mjs +1 -1
  32. package/esm/pipes/verify-delegation.mjs +49 -25
  33. package/esm/pipes/verify-multisig-v2.mjs +5 -4
  34. package/esm/pipes/verify-multisig.mjs +5 -4
  35. package/esm/pipes/verify-signature.d.mts +7 -1
  36. package/esm/pipes/verify-signature.mjs +119 -16
  37. package/esm/pipes/verify-signer.mjs +2 -2
  38. package/esm/pipes/verify-token-access.mjs +1 -1
  39. package/esm/pipes/verify-token-balance.mjs +1 -1
  40. package/esm/pipes/verify-tx-input.mjs +1 -1
  41. package/esm/pipes/verify-tx-size.mjs +1 -1
  42. package/esm/pipes/verify-tx.mjs +12 -5
  43. package/esm/super-suites-foundation.mjs +6 -6
  44. package/esm/transaction-block.d.mts +6 -2
  45. package/esm/transaction-block.mjs +282 -40
  46. package/esm/uniswap-router.d.mts +247 -1
  47. package/esm/uniswap-router.mjs +573 -2
  48. package/lib/bridge-release-keys.cjs +88 -0
  49. package/lib/bridge-release-keys.d.cts +33 -0
  50. package/lib/bridge-reserves.cjs +257 -0
  51. package/lib/bridge-reserves.d.cts +107 -0
  52. package/lib/helpers/bridge-withdraw.cjs +136 -0
  53. package/lib/helpers/bridge-withdraw.d.cts +86 -0
  54. package/lib/helpers/replay-guard.cjs +39 -0
  55. package/lib/helpers/replay-guard.d.cts +20 -2
  56. package/lib/index.cjs +25 -5
  57. package/lib/index.d.cts +3 -1
  58. package/lib/legacy-protocol-sunset.cjs +7 -7
  59. package/lib/legacy-protocol-sunset.d.cts +2 -2
  60. package/lib/legacy-rollup-archive.cjs +208 -0
  61. package/lib/legacy-rollup-archive.d.cts +67 -0
  62. package/lib/library.cjs +14 -68
  63. package/lib/library.d.cts +4 -4
  64. package/lib/native-abt-exchange.cjs +93 -46
  65. package/lib/native-abt-exchange.d.cts +3 -0
  66. package/lib/pipes/bridge-release-gate.cjs +145 -0
  67. package/lib/pipes/bridge-release-gate.d.cts +30 -0
  68. package/lib/pipes/bridge-reserve-v2-gate.cjs +273 -0
  69. package/lib/pipes/bridge-reserve-v2-gate.d.cts +53 -0
  70. package/lib/pipes/decode-itx.d.cts +1 -1
  71. package/lib/pipes/decode-tx.cjs +28 -3
  72. package/lib/pipes/decode-tx.d.cts +1 -1
  73. package/lib/pipes/extract-signer.cjs +1 -1
  74. package/lib/pipes/extract-state.cjs +3 -3
  75. package/lib/pipes/post-execution-invariant-gate.cjs +121 -4
  76. package/lib/pipes/post-execution-invariant-gate.d.cts +19 -2
  77. package/lib/pipes/pre-flight-waf.cjs +51 -13
  78. package/lib/pipes/pre-flight-waf.d.cts +19 -2
  79. package/lib/pipes/update-owner.cjs +1 -1
  80. package/lib/pipes/update-owner.d.cts +1 -1
  81. package/lib/pipes/verify-account-migration.cjs +1 -1
  82. package/lib/pipes/verify-delegation.cjs +50 -26
  83. package/lib/pipes/verify-multisig-v2.cjs +5 -4
  84. package/lib/pipes/verify-multisig.cjs +5 -4
  85. package/lib/pipes/verify-service-fee.d.cts +1 -1
  86. package/lib/pipes/verify-signature.cjs +118 -14
  87. package/lib/pipes/verify-signature.d.cts +8 -2
  88. package/lib/pipes/verify-signer.cjs +2 -2
  89. package/lib/pipes/verify-token-access.cjs +1 -1
  90. package/lib/pipes/verify-token-balance.cjs +1 -1
  91. package/lib/pipes/verify-tx-input.cjs +1 -1
  92. package/lib/pipes/verify-tx-size.cjs +1 -1
  93. package/lib/pipes/verify-tx-size.d.cts +1 -1
  94. package/lib/pipes/verify-tx.cjs +11 -5
  95. package/lib/pipes/verify-tx.d.cts +1 -1
  96. package/lib/super-suites-foundation.cjs +6 -6
  97. package/lib/transaction-block.cjs +282 -40
  98. package/lib/transaction-block.d.cts +6 -2
  99. package/lib/uniswap-router.cjs +576 -1
  100. package/lib/uniswap-router.d.cts +247 -1
  101. package/package.json +10 -10
  102. package/esm/evm-simplified-bridge.d.mts +0 -1370
  103. package/esm/evm-simplified-bridge.mjs +0 -3875
  104. package/lib/evm-simplified-bridge.cjs +0 -3943
  105. package/lib/evm-simplified-bridge.d.cts +0 -1370
@@ -1,1370 +0,0 @@
1
- import { CrossChainPurchaseInput } from "./transaction-block.cjs";
2
-
3
- //#region src/evm-simplified-bridge.d.ts
4
- declare const DEFAULT_MIN_EVM_CONFIRMATIONS = 12;
5
- declare const DEFAULT_MAX_ROLLUP_BLOCK_SIZE = 256;
6
- declare const MAX_EDGE_WEBHOOK_SKEW_SECONDS = 300;
7
- declare const MAX_EDGE_WEBHOOK_BODY_BYTES = 65536;
8
- declare const MAX_TRACKED_WEBHOOK_NONCES = 4096;
9
- declare const MIN_DIRECT_VOUCHER_TTL_SECONDS = 300;
10
- declare const MAX_DIRECT_VOUCHER_TTL_SECONDS = 604800;
11
- declare const DEFAULT_WITHDRAW_TIMELOCK_DELAY_SECONDS = 86400;
12
- declare const DEFAULT_ROLLUP_SUNSET_ACTIVATION_HEIGHT = 1;
13
- declare const DEPRECATED_ROLLUP_PROTOCOL_TYPE_URLS: readonly ["fg:t:create_rollup", "fg:t:update_rollup", "fg:t:join_rollup", "fg:t:leave_rollup", "fg:t:create_rollup_block", "fg:t:claim_block_reward", "fg:t:pause_rollup", "fg:t:resume_rollup"];
14
- declare const EIP712_BRIDGE_DOMAIN_NAME = "ArcEvmBridgeGateway";
15
- declare const EIP712_BRIDGE_DOMAIN_VERSION = "1";
16
- declare const DEFAULT_VERIFYING_CONTRACT_ADDRESS = "0x0000000000000000000000000000000000001241";
17
- declare const EMPTY_ROLLUP_MERKLE_ROOT = "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff";
18
- declare const ZERO_BYTES32_HASH = "0x0000000000000000000000000000000000000000000000000000000000000000";
19
- declare const ZERO_EVM_ADDRESS = "0x0000000000000000000000000000000000000000";
20
- /**
21
- * Issue #1241 & #1243:
22
- * Redesigned Simplified EVM Bridge Contract Specification (`ArcEvmBridgeGateway.sol`).
23
- * Implements the Dual-Track KISS architecture + 3-Layer Anti-Vault-Drain Security + EIP-712 Typed Data Signing:
24
- * 1. `payForOcapService`: Pay-Where-You-Are direct cashier (ERC-20 ABT / USDC stays on EVM, service delivered on OCAP).
25
- * 2. `depositForNativeAbt` & `claimWithdrawWithDirectVoucher` (Zero-Rollup-Block EIP-712 Pull Mode) / `claimWithdrawWithMerkleProof`.
26
- */
27
- declare const ARC_EVM_BRIDGE_GATEWAY_SOLIDITY_SPEC = "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.24;\n\ninterface IERC20Minimal {\n function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);\n function transfer(address recipient, uint256 amount) external returns (bool);\n}\n\ncontract ArcEvmBridgeGateway {\n bytes32 public constant EIP712_DOMAIN_TYPEHASH =\n keccak256(\"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)\");\n bytes32 public constant DIRECT_WITHDRAW_TYPEHASH =\n keccak256(\"DirectWithdrawVoucher(bytes32 bridgeIdHash,bytes32 ocapTxHash,address recipient,uint256 amount,uint256 expiresAt)\");\n\n address public immutable canonicalAbtToken;\n address public immutable guardian;\n bytes32 public immutable bridgeIdHash;\n bytes32 public immutable DOMAIN_SEPARATOR;\n uint256 public immutable minValidatorSignatures;\n uint256 public immutable maxDailyWithdrawCap;\n uint256 public immutable largeWithdrawThreshold;\n uint256 public constant TIMELOCK_DELAY = 24 hours;\n\n bool public paused;\n uint256 public latestBlockHeight;\n bytes32 public latestBlockHash;\n uint256 public cumulativeDepositedAbt;\n uint256 public cumulativeWithdrawnAbt;\n\n mapping(address => bool) public isBridgeValidator;\n mapping(uint256 => bytes32) public blockMerkleRoots;\n mapping(bytes32 => bool) public processedServiceOrders;\n mapping(bytes32 => bool) public claimedWithdrawTxs;\n mapping(bytes32 => bool) public cancelledWithdrawTxs;\n mapping(bytes32 => uint256) public timelockUnlockAt;\n mapping(uint256 => uint256) public dailyWithdrawnAbt;\n mapping(address => bool) public supportedServiceTokens;\n\n event OcapServicePaid(\n bytes32 indexed orderId,\n address indexed payer,\n string recipientDid,\n string serviceDid,\n address paymentToken,\n uint256 amount\n );\n\n event NativeAbtDepositLocked(\n address indexed depositor,\n string recipientDid,\n uint256 amount,\n uint256 cumulativeDepositedAbt\n );\n\n event RollupBlockSubmitted(\n uint256 indexed height,\n bytes32 previousHash,\n bytes32 merkleRoot,\n bytes32 txsHash,\n bytes32 blockHash\n );\n\n event LargeWithdrawTimelocked(\n bytes32 indexed ocapTxHash,\n address indexed recipient,\n uint256 amount,\n uint256 unlockAt\n );\n\n event NativeAbtWithdrawClaimed(\n bytes32 indexed ocapTxHash,\n address indexed recipient,\n uint256 amount,\n uint256 blockHeight\n );\n\n constructor(\n address _canonicalAbtToken,\n address _guardian,\n bytes32 _bridgeIdHash,\n bytes32 _genesisBlockHash,\n address[] memory _validators,\n uint256 _minValidatorSignatures,\n uint256 _maxDailyWithdrawCap,\n uint256 _largeWithdrawThreshold\n ) {\n require(_canonicalAbtToken != address(0) && _guardian != address(0), \"ZERO_ADDRESS\");\n require(_validators.length >= 2 && _minValidatorSignatures >= 2 && _minValidatorSignatures <= _validators.length, \"MULTI_SIGNER_QUORUM_REQUIRED\");\n require(_maxDailyWithdrawCap > 0 && _largeWithdrawThreshold > 0, \"INVALID_CAPS\");\n canonicalAbtToken = _canonicalAbtToken;\n guardian = _guardian;\n bridgeIdHash = _bridgeIdHash;\n minValidatorSignatures = _minValidatorSignatures;\n maxDailyWithdrawCap = _maxDailyWithdrawCap;\n largeWithdrawThreshold = _largeWithdrawThreshold;\n DOMAIN_SEPARATOR = keccak256(\n abi.encode(\n EIP712_DOMAIN_TYPEHASH,\n keccak256(bytes(\"ArcEvmBridgeGateway\")),\n keccak256(bytes(\"1\")),\n block.chainid,\n address(this)\n )\n );\n supportedServiceTokens[_canonicalAbtToken] = true;\n latestBlockHash = _genesisBlockHash;\n for (uint256 i = 0; i < _validators.length; i++) {\n require(_validators[i] != address(0) && !isBridgeValidator[_validators[i]], \"INVALID_VALIDATOR\");\n isBridgeValidator[_validators[i]] = true;\n }\n }\n\n function setPaused(bool _paused) external {\n require(msg.sender == guardian, \"ONLY_GUARDIAN\");\n paused = _paused;\n }\n\n function cancelFraudulentWithdraw(bytes32 ocapTxHash) external {\n require(msg.sender == guardian, \"ONLY_GUARDIAN\");\n require(!claimedWithdrawTxs[ocapTxHash], \"ALREADY_CLAIMED\");\n cancelledWithdrawTxs[ocapTxHash] = true;\n }\n\n // Track 1: Pay-Where-You-Are Direct Service Cashier (Zero Foreign Asset Bridge)\n function payForOcapService(\n bytes32 orderId,\n string calldata recipientDid,\n string calldata serviceDid,\n address paymentToken,\n uint256 amount\n ) external {\n require(!paused, \"BRIDGE_PAUSED\");\n require(orderId != bytes32(0) && !processedServiceOrders[orderId], \"INVALID_OR_DUPLICATE_ORDER\");\n require(supportedServiceTokens[paymentToken], \"UNSUPPORTED_PAYMENT_TOKEN\");\n require(amount > 0 && bytes(recipientDid).length > 0 && bytes(serviceDid).length > 0, \"INVALID_ARGS\");\n\n processedServiceOrders[orderId] = true;\n require(IERC20Minimal(paymentToken).transferFrom(msg.sender, address(this), amount), \"TRANSFER_FAILED\");\n emit OcapServicePaid(orderId, msg.sender, recipientDid, serviceDid, paymentToken, amount);\n }\n\n // Track 2A: Canonical ERC-20 ABT -> OCAP Native ABT 1:1 Deposit\n function depositForNativeAbt(string calldata recipientDid, uint256 amount) external {\n require(!paused, \"BRIDGE_PAUSED\");\n require(amount > 0 && bytes(recipientDid).length > 0, \"INVALID_DEPOSIT\");\n cumulativeDepositedAbt += amount;\n require(IERC20Minimal(canonicalAbtToken).transferFrom(msg.sender, address(this), amount), \"TRANSFER_FAILED\");\n emit NativeAbtDepositLocked(msg.sender, recipientDid, amount, cumulativeDepositedAbt);\n }\n\n // Track 2B (Primary \u2014 Zero-Rollup-Block EIP-712 Pull Mode):\n // Direct Threshold-Signed Withdraw Voucher (User-Pays-Claim-Gas, 0 RollupBlock / 0 Operator ETH Gas)\n function claimWithdrawWithDirectVoucher(\n bytes32 ocapTxHash,\n address to,\n uint256 amount,\n uint256 expiresAt,\n bytes32 voucherDigest,\n uint8[] calldata v,\n bytes32[] calldata r,\n bytes32[] calldata s\n ) external {\n require(!paused, \"BRIDGE_PAUSED\");\n require(!claimedWithdrawTxs[ocapTxHash] && !cancelledWithdrawTxs[ocapTxHash], \"ALREADY_CLAIMED_OR_CANCELLED\");\n require(to != address(0) && amount > 0, \"INVALID_RECIPIENT_OR_AMOUNT\");\n require(block.timestamp <= expiresAt, \"VOUCHER_EXPIRED\");\n require(cumulativeWithdrawnAbt + amount <= cumulativeDepositedAbt, \"CANARY_RESERVE_WATERMARK_EXCEEDED\");\n\n bytes32 structHash = keccak256(\n abi.encode(DIRECT_WITHDRAW_TYPEHASH, bridgeIdHash, ocapTxHash, to, amount, expiresAt)\n );\n bytes32 expectedDigest = keccak256(abi.encodePacked(\"\\x19\\x01\", DOMAIN_SEPARATOR, structHash));\n require(voucherDigest == expectedDigest, \"INVALID_EIP712_VOUCHER_DIGEST\");\n _verifyValidatorQuorum(voucherDigest, v, r, s);\n\n if (amount >= largeWithdrawThreshold) {\n uint256 unlockAt = timelockUnlockAt[ocapTxHash];\n if (unlockAt == 0) {\n timelockUnlockAt[ocapTxHash] = block.timestamp + TIMELOCK_DELAY;\n emit LargeWithdrawTimelocked(ocapTxHash, to, amount, timelockUnlockAt[ocapTxHash]);\n return;\n }\n require(block.timestamp >= unlockAt, \"TIMELOCK_ACTIVE\");\n }\n\n uint256 currentDay = block.timestamp / 1 days;\n require(dailyWithdrawnAbt[currentDay] + amount <= maxDailyWithdrawCap, \"DAILY_WITHDRAW_CAP_EXCEEDED\");\n dailyWithdrawnAbt[currentDay] += amount;\n\n claimedWithdrawTxs[ocapTxHash] = true;\n cumulativeWithdrawnAbt += amount;\n require(IERC20Minimal(canonicalAbtToken).transfer(to, amount), \"TRANSFER_FAILED\");\n emit NativeAbtWithdrawClaimed(ocapTxHash, to, amount, 0);\n }\n\n // Track 2B (Legacy Compatibility): Submit Rollup Merkle Block & Claim with Merkle Proof\n function submitRollupBlock(\n uint256 height,\n bytes32 previousHash,\n bytes32 merkleRoot,\n bytes32 txsHash,\n uint8[] calldata v,\n bytes32[] calldata r,\n bytes32[] calldata s\n ) external {\n require(!paused, \"BRIDGE_PAUSED\");\n require(height == latestBlockHeight + 1, \"INVALID_HEIGHT\");\n require(previousHash == latestBlockHash, \"INVALID_PREVIOUS_HASH\");\n bytes32 blockHash = keccak256(abi.encodePacked(height, previousHash, merkleRoot, txsHash));\n _verifyValidatorQuorum(blockHash, v, r, s);\n\n latestBlockHeight = height;\n latestBlockHash = blockHash;\n blockMerkleRoots[height] = merkleRoot;\n emit RollupBlockSubmitted(height, previousHash, merkleRoot, txsHash, blockHash);\n }\n\n function claimWithdrawWithMerkleProof(\n bytes32 ocapTxHash,\n address to,\n uint256 amount,\n uint256 blockHeight,\n bytes32[] calldata proof\n ) external {\n require(!paused, \"BRIDGE_PAUSED\");\n require(!claimedWithdrawTxs[ocapTxHash] && !cancelledWithdrawTxs[ocapTxHash], \"ALREADY_CLAIMED_OR_CANCELLED\");\n require(to != address(0) && amount > 0, \"INVALID_RECIPIENT_OR_AMOUNT\");\n require(cumulativeWithdrawnAbt + amount <= cumulativeDepositedAbt, \"CANARY_RESERVE_WATERMARK_EXCEEDED\");\n\n bytes32 root = blockMerkleRoots[blockHeight];\n require(root != bytes32(0) && root != bytes32(type(uint256).max), \"INVALID_BLOCK_ROOT\");\n bytes32 leaf = keccak256(abi.encodePacked(ocapTxHash, to, amount));\n require(_verifyMerkleProof(proof, root, leaf), \"INVALID_MERKLE_PROOF\");\n\n if (amount >= largeWithdrawThreshold) {\n uint256 unlockAt = timelockUnlockAt[ocapTxHash];\n if (unlockAt == 0) {\n timelockUnlockAt[ocapTxHash] = block.timestamp + TIMELOCK_DELAY;\n emit LargeWithdrawTimelocked(ocapTxHash, to, amount, timelockUnlockAt[ocapTxHash]);\n return;\n }\n require(block.timestamp >= unlockAt, \"TIMELOCK_ACTIVE\");\n }\n\n uint256 currentDay = block.timestamp / 1 days;\n require(dailyWithdrawnAbt[currentDay] + amount <= maxDailyWithdrawCap, \"DAILY_WITHDRAW_CAP_EXCEEDED\");\n dailyWithdrawnAbt[currentDay] += amount;\n\n claimedWithdrawTxs[ocapTxHash] = true;\n cumulativeWithdrawnAbt += amount;\n require(IERC20Minimal(canonicalAbtToken).transfer(to, amount), \"TRANSFER_FAILED\");\n emit NativeAbtWithdrawClaimed(ocapTxHash, to, amount, blockHeight);\n }\n\n function _verifyValidatorQuorum(\n bytes32 digest,\n uint8[] calldata v,\n bytes32[] calldata r,\n bytes32[] calldata s\n ) internal view {\n require(v.length >= minValidatorSignatures && v.length == r.length && v.length == s.length, \"QUORUM_NOT_MET\");\n address lastSigner = address(0);\n for (uint256 i = 0; i < v.length; i++) {\n address signer = ecrecover(digest, v[i], r[i], s[i]);\n require(signer > lastSigner && isBridgeValidator[signer], \"INVALID_OR_UNSORTED_SIGNER\");\n lastSigner = signer;\n }\n }\n\n function _verifyMerkleProof(bytes32[] calldata proof, bytes32 root, bytes32 leaf) internal pure returns (bool) {\n bytes32 computedHash = leaf;\n for (uint256 i = 0; i < proof.length; i++) {\n bytes32 proofElement = proof[i];\n if (computedHash <= proofElement) {\n computedHash = keccak256(abi.encodePacked(computedHash, proofElement));\n } else {\n computedHash = keccak256(abi.encodePacked(proofElement, computedHash));\n }\n }\n return computedHash == root;\n }\n}\n";
28
- interface SimplifiedEvmBridgeConfig {
29
- bridgeId: string;
30
- rollupAddress: string;
31
- bridgeProposerDid: string;
32
- guardianDid?: string;
33
- verifyingContractAddress?: string;
34
- ocapNativeAbtTokenAddress: string;
35
- canonicalErc20AbtAddress: string;
36
- allowedServicePaymentTokens: string[];
37
- allowedEvmChainIds: string[];
38
- validatorDids?: string[];
39
- minValidatorSignatures?: number;
40
- allowSingleSignerForTesting?: boolean;
41
- minConfirmations?: number;
42
- minDepositAmount: bigint;
43
- maxDepositAmount: bigint;
44
- minWithdrawAmount: bigint;
45
- maxWithdrawAmount: bigint;
46
- maxDailyWithdrawAbt?: bigint;
47
- largeWithdrawTimelockThresholdAbt?: bigint;
48
- timelockDelaySeconds?: number;
49
- maxBlockSize?: number;
50
- genesisBlockHash?: string;
51
- webhookHmacSecret: string;
52
- }
53
- interface EvmServicePaymentEventInput {
54
- evmChainId: string;
55
- evmTxHash: string;
56
- logIndex: number;
57
- confirmations: number;
58
- reorged?: boolean;
59
- orderId: string;
60
- payerEvmAddress: string;
61
- recipientDid: string;
62
- serviceDid: string;
63
- paymentTokenAddress: string;
64
- amount: bigint;
65
- deliverableNftDid?: string;
66
- }
67
- interface OcapServiceDeliveryInstruction {
68
- instructionId: string;
69
- eventKey: string;
70
- orderId: string;
71
- recipientDid: string;
72
- serviceDid: string;
73
- paymentTokenAddress: string;
74
- paidAmount: bigint;
75
- depositProofDigest: string;
76
- crossChainPurchaseInput: CrossChainPurchaseInput;
77
- }
78
- interface EvmAbtDepositEventInput {
79
- evmChainId: string;
80
- evmTxHash: string;
81
- logIndex: number;
82
- confirmations: number;
83
- reorged?: boolean;
84
- depositorEvmAddress: string;
85
- recipientDid: string;
86
- tokenAddress: string;
87
- amount: bigint;
88
- actualFee?: bigint;
89
- }
90
- interface OcapRelayerDepositTxInstruction {
91
- instructionId: string;
92
- eventKey: string;
93
- rollupAddress: string;
94
- proposerDid: string;
95
- proposerSponsored: true;
96
- recipientDid: string;
97
- tokenAddress: string;
98
- value: bigint;
99
- actualFee: bigint;
100
- evidenceHash: string;
101
- cumulativeDepositedAbt: bigint;
102
- }
103
- interface OcapAbtWithdrawItem {
104
- ocapTxHash: string;
105
- fromDid: string;
106
- recipientEvmAddress: string;
107
- amount: bigint;
108
- }
109
- interface BridgeValidatorSignature {
110
- validatorDid: string;
111
- signatureDigest: string;
112
- evmSignerAddress?: string;
113
- v?: number;
114
- r?: string;
115
- s?: string;
116
- }
117
- interface SealedRollupWithdrawBlock {
118
- height: number;
119
- previousHash: string;
120
- merkleRoot: string;
121
- txsHash: string;
122
- blockHash: string;
123
- withdrawTxs: OcapAbtWithdrawItem[];
124
- validatorSigners: string[];
125
- sealedAtUnixSeconds: number;
126
- }
127
- interface EvmWithdrawClaimProofBundle {
128
- ocapTxHash: string;
129
- recipientEvmAddress: string;
130
- amount: bigint;
131
- blockHeight: number;
132
- blockHash: string;
133
- merkleRoot: string;
134
- leafHash: string;
135
- merkleProof: string[];
136
- }
137
- interface DirectWithdrawVoucher {
138
- voucherDigest: string;
139
- eip712DomainSeparator: string;
140
- eip712StructHash: string;
141
- verifyingContractAddress: string;
142
- bridgeId: string;
143
- evmChainId: string;
144
- ocapTxHash: string;
145
- fromDid: string;
146
- recipientEvmAddress: string;
147
- amount: bigint;
148
- issuedAtUnixSeconds: number;
149
- expiresAtUnixSeconds: number;
150
- timelocked: boolean;
151
- unlocksAtUnixSeconds: number;
152
- cancelled?: boolean;
153
- validatorSigners: string[];
154
- validatorSignatures: BridgeValidatorSignature[];
155
- }
156
- interface BridgeDurableStateSnapshot {
157
- schemaVersion: 1;
158
- config: {
159
- bridgeId: string;
160
- rollupAddress: string;
161
- bridgeProposerDid: string;
162
- guardianDid: string;
163
- verifyingContractAddress: string;
164
- ocapNativeAbtTokenAddress: string;
165
- canonicalErc20AbtAddress: string;
166
- allowedServicePaymentTokens: string[];
167
- allowedEvmChainIds: string[];
168
- validatorDids: string[];
169
- minValidatorSignatures: number;
170
- allowSingleSignerForTesting: boolean;
171
- minConfirmations: number;
172
- minDepositAmount: string;
173
- maxDepositAmount: string;
174
- minWithdrawAmount: string;
175
- maxWithdrawAmount: string;
176
- maxDailyWithdrawAbt: string;
177
- largeWithdrawTimelockThresholdAbt: string;
178
- timelockDelaySeconds: number;
179
- maxBlockSize: number;
180
- genesisBlockHash: string;
181
- webhookHmacSecret: string;
182
- };
183
- paused?: boolean;
184
- latestBlockHeight: number;
185
- latestBlockHash: string;
186
- cumulativeDepositedAbt: string;
187
- cumulativeWithdrawnAbt: string;
188
- processedEventKeys: string[];
189
- processedServiceOrderIds: string[];
190
- processedWithdrawTxHashes: string[];
191
- cancelledWithdrawTxHashes?: string[];
192
- dailyWithdrawnByDay?: Array<{
193
- dayBucket: number;
194
- withdrawnAbt: string;
195
- }>;
196
- processedWebhookNonces: Array<{
197
- nonce: string;
198
- timestampSeconds: number;
199
- }>;
200
- pendingWithdrawQueue: Array<{
201
- ocapTxHash: string;
202
- fromDid: string;
203
- recipientEvmAddress: string;
204
- amount: string;
205
- }>;
206
- sealedBlocks: Array<{
207
- height: number;
208
- previousHash: string;
209
- merkleRoot: string;
210
- txsHash: string;
211
- blockHash: string;
212
- withdrawTxs: Array<{
213
- ocapTxHash: string;
214
- fromDid: string;
215
- recipientEvmAddress: string;
216
- amount: string;
217
- }>;
218
- validatorSigners: string[];
219
- sealedAtUnixSeconds: number;
220
- }>;
221
- issuedDirectVouchers?: Array<{
222
- voucherDigest: string;
223
- eip712DomainSeparator: string;
224
- eip712StructHash: string;
225
- verifyingContractAddress: string;
226
- bridgeId: string;
227
- evmChainId: string;
228
- ocapTxHash: string;
229
- fromDid: string;
230
- recipientEvmAddress: string;
231
- amount: string;
232
- issuedAtUnixSeconds: number;
233
- expiresAtUnixSeconds: number;
234
- timelocked: boolean;
235
- unlocksAtUnixSeconds: number;
236
- cancelled?: boolean;
237
- validatorSigners: string[];
238
- validatorSignatures: BridgeValidatorSignature[];
239
- }>;
240
- }
241
- type DeprecatedRollupProtocolTypeUrl = (typeof DEPRECATED_ROLLUP_PROTOCOL_TYPE_URLS)[number];
242
- type LegacyRollupRecordKind = 'RollupState' | 'RollupBlock' | 'deposit_token_v2' | 'withdraw_token_v2';
243
- interface LegacyRollupReadOnlySummary {
244
- readonly recordKind: LegacyRollupRecordKind;
245
- readonly mode: 'READ_ONLY_LEGACY_ARCHIVE';
246
- readonly rollupAddress: string;
247
- readonly tokenAddress?: string;
248
- readonly blockHeight?: number;
249
- readonly blockHash?: string;
250
- readonly previousHash?: string;
251
- readonly merkleRoot?: string;
252
- readonly txsHash?: string;
253
- readonly txHashes?: readonly string[];
254
- readonly proposerDid?: string;
255
- readonly validatorDids?: readonly string[];
256
- readonly fromDid?: string;
257
- readonly recipientAddress?: string;
258
- readonly amount?: bigint;
259
- readonly evidenceHash?: string;
260
- }
261
- interface BridgeWebPortalConfig {
262
- portalVersion: '1.0.0';
263
- hostPlatform: 'ARC_BRIDGE_BLOCKLET';
264
- blockletDid: string;
265
- didConnectSessionSupported: true;
266
- zeroBridgeFee: true;
267
- bridgeFeeBps: 0;
268
- walletRequired: 'STANDARD_WEB_EIP1193_ONLY';
269
- bridgeId: string;
270
- rollupAddress: string;
271
- verifyingContractAddress: string;
272
- canonicalErc20AbtAddress: string;
273
- ocapNativeAbtTokenAddress: string;
274
- allowedEvmChainIds: string[];
275
- allowedServicePaymentTokens: string[];
276
- paused: boolean;
277
- eip712Domain: {
278
- name: string;
279
- version: string;
280
- verifyingContract: string;
281
- };
282
- limits: {
283
- minDepositAmount: string;
284
- maxDepositAmount: string;
285
- minWithdrawAmount: string;
286
- maxWithdrawAmount: string;
287
- maxDailyWithdrawAbt: string;
288
- largeWithdrawTimelockThresholdAbt: string;
289
- timelockDelaySeconds: number;
290
- };
291
- deprecatedRollupProtocols: readonly string[];
292
- }
293
- interface Eip1193TransactionStep {
294
- stepId: string;
295
- description: string;
296
- evmChainId: string;
297
- to: string;
298
- valueHex: '0x0';
299
- methodSignature: string;
300
- functionSelector: string;
301
- calldataHex: string;
302
- args: Record<string, unknown>;
303
- }
304
- type BridgeWebPortalActionInput = {
305
- action: 'DEPOSIT_FOR_NATIVE_ABT';
306
- evmChainId: string;
307
- recipientDid: string;
308
- amount: bigint;
309
- userEvmAddress?: string;
310
- } | {
311
- action: 'CLAIM_WITH_DIRECT_VOUCHER';
312
- ocapTxHash: string;
313
- nowUnixSeconds?: number;
314
- } | {
315
- action: 'PAY_FOR_OCAP_SERVICE';
316
- evmChainId: string;
317
- orderId: string;
318
- recipientDid: string;
319
- serviceDid: string;
320
- paymentTokenAddress: string;
321
- amount: bigint;
322
- userEvmAddress?: string;
323
- };
324
- interface BridgeWebPortalActionBundle {
325
- action: BridgeWebPortalActionInput['action'];
326
- hostPlatform: 'ARC_BRIDGE_BLOCKLET';
327
- blockletDid: string;
328
- walletRequired: 'STANDARD_WEB_EIP1193_ONLY';
329
- bridgeId: string;
330
- evmChainId: string;
331
- verifyingContractAddress: string;
332
- autoRelayerSponsoredOnOcap: boolean;
333
- timelockStatus?: {
334
- timelocked: boolean;
335
- unlocksAtUnixSeconds: number;
336
- isUnlocked: boolean;
337
- claimPhase: 'IMMEDIATE_CLAIM' | 'TIMELOCK_INITIATION' | 'FINAL_UNLOCKED_CLAIM';
338
- };
339
- steps: Eip1193TransactionStep[];
340
- }
341
- interface CloudflareBridgeEdgeRequest {
342
- method: 'GET' | 'POST';
343
- path: '/health' | '/portal/config' | '/portal/build-tx' | '/webhook/evm-service-pay' | '/webhook/evm-abt-deposit' | '/webhook/ocap-abt-withdraw' | '/webhook/ocap-abt-withdraw-voucher' | '/webhook/guardian-pause' | '/webhook/guardian-cancel-withdraw' | '/cron/seal-withdraw-block' | '/query/withdraw-proof' | '/query/withdraw-voucher';
344
- headers?: Record<string, string | undefined>;
345
- bodyJson?: string;
346
- nowUnixSeconds?: number;
347
- }
348
- interface CloudflareBridgeEdgeResponse {
349
- status: number;
350
- body: Record<string, unknown>;
351
- }
352
- /**
353
- * Computes the `@ocap/merkle-tree` compatible packed withdraw leaf preimage:
354
- * `encodePacked(bytes32 txHash, address to, uint256 amount)`
355
- */
356
- declare function encodeEvmBridgeWithdrawPackedPreimage(txHash: string, toEvmAddress: string, amount: bigint): string;
357
- /**
358
- * Computes the `@ocap/merkle-tree` leaf hash (`keccak256(encodePacked(bytes32, address, uint256))`).
359
- */
360
- declare function computeEvmBridgeWithdrawLeafHash(txHash: string, toEvmAddress: string, amount: bigint): string;
361
- /**
362
- * Computes the `@ocap/merkle-tree` compatible `getListHash(txHashes)`.
363
- */
364
- declare function computeEvmBridgeTxsHash(txHashes: string[]): string;
365
- /**
366
- * Computes the `@ocap/merkle-tree` compatible `getBlockHash`:
367
- * `keccak256(encodePacked(uint256 height, bytes32 previousHash, bytes32 merkleRoot, bytes32 txsHash))`
368
- */
369
- declare function computeEvmBridgeBlockHash(block: {
370
- height: number;
371
- previousHash: string;
372
- merkleRoot: string;
373
- txsHash: string;
374
- }): string;
375
- /**
376
- * Deterministic sorted-pair Keccak-256 Merkle tree compatible with `@ocap/merkle-tree` and OpenZeppelin `MerkleProof`.
377
- */
378
- declare function buildEvmBridgeMerkleTree(withdrawTxs: OcapAbtWithdrawItem[]): {
379
- merkleRoot: string;
380
- leaves: string[];
381
- getProofForLeaf: (leafHash: string) => string[];
382
- };
383
- /**
384
- * Verifies a sorted-pair Keccak-256 Merkle proof against `merkleRoot`.
385
- */
386
- declare function verifyEvmBridgeMerkleProof(proof: string[], merkleRoot: string, leafHash: string): boolean;
387
- /**
388
- * Computes the expected validator signature digest for a Rollup block.
389
- */
390
- declare function computeValidatorBlockSignatureDigest(bridgeId: string, rollupAddress: string, blockHash: string, validatorDid: string): string;
391
- declare const EIP712_DOMAIN_TYPEHASH: string;
392
- declare const DIRECT_WITHDRAW_TYPEHASH: string;
393
- /**
394
- * Computes the standard EIP-712 `DOMAIN_SEPARATOR` matching `ArcEvmBridgeGateway.sol`:
395
- * `keccak256(abi.encode(EIP712_DOMAIN_TYPEHASH, keccak256(bytes(name)), keccak256(bytes(version)), chainId, verifyingContract))`
396
- */
397
- declare function computeEip712BridgeDomainSeparator(params: {
398
- name?: string;
399
- version?: string;
400
- evmChainId: string;
401
- verifyingContractAddress?: string;
402
- }): string;
403
- /**
404
- * Computes the standard EIP-712 `structHash` for `DirectWithdrawVoucher` matching `ArcEvmBridgeGateway.sol`:
405
- * `keccak256(abi.encode(DIRECT_WITHDRAW_TYPEHASH, keccak256(bytes(bridgeId)), ocapTxHash, recipient, amount, expiresAt))`
406
- */
407
- declare function computeEip712WithdrawStructHash(params: {
408
- bridgeId: string;
409
- ocapTxHash: string;
410
- recipientEvmAddress: string;
411
- amount: bigint;
412
- expiresAtUnixSeconds: number;
413
- }): string;
414
- /**
415
- * Computes the deterministic EIP-712 Zero-Rollup-Block Direct Withdraw Voucher Digest (`\x19\x01 || DOMAIN_SEPARATOR || structHash`):
416
- * binds `(bridgeId, evmChainId, verifyingContractAddress, ocapTxHash, recipientEvmAddress, amount, expiresAtUnixSeconds)`
417
- * so the withdrawing user can claim ERC-20 ABT directly on Ethereum/Base (`claimWithdrawWithDirectVoucher`)
418
- * without waiting for any RollupBlock batch or operator-paid Ethereum transactions.
419
- */
420
- declare function computeDirectWithdrawVoucherDigest(params: {
421
- bridgeId: string;
422
- evmChainId: string;
423
- verifyingContractAddress?: string;
424
- ocapTxHash: string;
425
- recipientEvmAddress: string;
426
- amount: bigint;
427
- expiresAtUnixSeconds: number;
428
- }): string;
429
- /**
430
- * Computes the expected validator signature digest for a Zero-Rollup-Block Direct Withdraw Voucher.
431
- */
432
- declare function computeValidatorVoucherSignatureDigest(bridgeId: string, voucherDigest: string, validatorDid: string): string;
433
- /**
434
- * Verifies a `DirectWithdrawVoucher` against the bridge EIP-712 domain, validator set, and quorum threshold.
435
- */
436
- declare function verifyDirectWithdrawVoucher(voucher: DirectWithdrawVoucher, options: {
437
- bridgeId: string;
438
- verifyingContractAddress?: string;
439
- allowedEvmChainIds: string[];
440
- validatorDids: string[];
441
- minValidatorSignatures: number;
442
- nowUnixSeconds?: number;
443
- }): boolean;
444
- /**
445
- * Issue #1245:
446
- * Returns true if `typeUrl` belongs to the 8 deprecated Rollup write protocols
447
- * (`create_rollup`, `update_rollup`, `join_rollup`, `leave_rollup`, `create_rollup_block`,
448
- * `claim_block_reward`, `pause_rollup`, `resume_rollup`).
449
- * Normalizes case, whitespace, camelCase/PascalCase, protobuf type URLs, and bare protocol names (`RT-1245-3`).
450
- */
451
- declare function isDeprecatedRollupWriteProtocol(typeUrl: string): boolean;
452
- /**
453
- * Issue #1245:
454
- * Sunset guard for active transaction pipeline execution:
455
- * - Blocks all 8 deprecated Rollup write protocols when `currentBlockHeight >= rollupSunsetActivationHeight`.
456
- * - Allows historical block replay when `currentBlockHeight < rollupSunsetActivationHeight`.
457
- */
458
- declare function assertRollupProtocolNotSunset(params: {
459
- typeUrl: string;
460
- currentBlockHeight: number;
461
- rollupSunsetActivationHeight?: number;
462
- }): void;
463
- /**
464
- * Issue #1245:
465
- * Strictly read-only historical parser for legacy `RollupState`, `RollupBlock`, `deposit_token_v2`,
466
- * and `withdraw_token_v2` records so block explorers, indexers, and audit tools can inspect historical
467
- * chain data after the active Rollup write protocols are removed.
468
- */
469
- declare function parseLegacyRollupReadOnlyRecord(rawRecord: Record<string, unknown>): LegacyRollupReadOnlySummary;
470
- /**
471
- * Derives the canonical 20-byte lowercase `0x`-prefixed Ethereum address from a 32-byte `secp256k1` private key.
472
- */
473
- declare function deriveEvmAddressFromPrivateKeyHex(privateKeyHex: string): string;
474
- /**
475
- * Signs a 32-byte digest (`0x...`) using a real `secp256k1` private key and returns Ethereum `(v, r, s)` + `signerEvmAddress`.
476
- */
477
- declare function signDigestWithSecp256k1PrivateKey(digestHex: string, privateKeyHex: string): {
478
- v: 27 | 28;
479
- r: string;
480
- s: string;
481
- signerEvmAddress: string;
482
- };
483
- /**
484
- * Recovers the 20-byte Ethereum signer address from `(digestHex, v, r, s)` identically to OpenZeppelin `ECDSA.recover` (EIP-2 low-`s` enforced).
485
- */
486
- declare function ecrecoverEvmAddress(digestHex: string, v: number, rHex: string, sHex: string): string;
487
- /**
488
- * Computes the HMAC-SHA256 signature for Cloudflare Edge webhook requests.
489
- */
490
- declare function computeEdgeWebhookHmac(secret: string, timestampSeconds: number, nonce: string, path: string, bodyJson: string): string;
491
- /**
492
- * Issue #1241:
493
- * Next-Gen Simplified EVM Bridge Node (`OcapSimplifiedEvmBridgeNode`).
494
- * - Pure ARC-native & Cloudflare Workers / Durable Objects ready (zero native C++ addons, full snapshot import/export).
495
- * - Implements Track 1 (`Pay-Where-You-Are` Direct Service Cashier) and Track 2 (`1:1 Canonical ABT Gateway`).
496
- * - 100% backward-compatible with OCAP `RollupState`, `deposit_token_v2`, `withdraw_token_v2`, and `@ocap/merkle-tree`.
497
- */
498
- declare class OcapSimplifiedEvmBridgeNode {
499
- readonly config: Required<SimplifiedEvmBridgeConfig>;
500
- private paused;
501
- private latestBlockHeight;
502
- private latestBlockHash;
503
- private cumulativeDepositedAbt;
504
- private cumulativeWithdrawnAbt;
505
- private readonly allowedChainSet;
506
- private readonly allowedPaymentTokenSet;
507
- private readonly validatorSet;
508
- private readonly processedEventKeys;
509
- private readonly processedServiceOrderIds;
510
- private readonly processedWithdrawTxHashes;
511
- private readonly cancelledWithdrawTxHashes;
512
- private readonly dailyWithdrawnByDay;
513
- private readonly processedWebhookNonces;
514
- private readonly pendingWithdrawQueue;
515
- private readonly sealedBlocks;
516
- private readonly withdrawTxToBlockHeight;
517
- private readonly issuedDirectVouchers;
518
- constructor(config: SimplifiedEvmBridgeConfig);
519
- private assertNotPaused;
520
- /**
521
- * Layer 3 Anti-Drain Control: Guardian emergency pause / unpause.
522
- */
523
- setBridgePaused(params: {
524
- guardianDid: string;
525
- paused: boolean;
526
- }): {
527
- paused: boolean;
528
- };
529
- /**
530
- * Layer 3 Anti-Drain Control: Guardian cancels a timelocked whale withdrawal before its timelock expires,
531
- * restoring the Canary reserve watermark and daily withdrawal cap.
532
- */
533
- cancelTimelockedWithdraw(params: {
534
- guardianDid: string;
535
- ocapTxHash: string;
536
- nowUnixSeconds: number;
537
- }): {
538
- cancelledTxHash: string;
539
- refundedReserveAbt: bigint;
540
- };
541
- private assertFinalizedEvmEvent;
542
- /**
543
- * Track 1 — `Pay-Where-You-Are, Consume-on-OCAP`:
544
- * Ingests a finalized `OcapServicePaid` event from Ethereum/Base (paid in ERC-20 ABT or USDC)
545
- * and produces a deterministic `OcapServiceDeliveryInstruction` (`CrossChainPurchaseInput`)
546
- * without minting or bridging any foreign token onto OCAP.
547
- */
548
- ingestEvmServicePaymentEvent(input: EvmServicePaymentEventInput): OcapServiceDeliveryInstruction;
549
- /**
550
- * Track 2A — `ERC-20 ABT -> OCAP Native ABT` 1:1 Relayer-Sponsored Deposit:
551
- * Ingests a finalized `NativeAbtDepositLocked` event on Ethereum/Base, increments the Canary
552
- * reserve watermark (`cumulativeDepositedAbt`), and generates a proposer-sponsored `deposit_token_v2`
553
- * instruction so even 0-gas OCAP accounts receive Native ABT in 1 click.
554
- */
555
- ingestEvmAbtDepositEvent(input: EvmAbtDepositEventInput): OcapRelayerDepositTxInstruction;
556
- /**
557
- * Track 2B (Step 1) — Enqueues a finalized OCAP `withdraw_token_v2` transaction for the next
558
- * Rollup Merkle block, enforcing the Canary Net-Inflow Reserve Watermark up front.
559
- */
560
- enqueueOcapAbtWithdraw(withdraw: OcapAbtWithdrawItem): {
561
- queuedCount: number;
562
- pendingWithdrawTotal: bigint;
563
- };
564
- /**
565
- * Pre-computes the next pending Rollup block header (`height`, `previousHash`, `merkleRoot`, `txsHash`, `blockHash`)
566
- * so validators can sign `blockHash` before calling `sealRollupWithdrawBlock`.
567
- */
568
- previewNextRollupWithdrawBlock(): {
569
- height: number;
570
- previousHash: string;
571
- merkleRoot: string;
572
- txsHash: string;
573
- blockHash: string;
574
- batchWithdrawTxs: OcapAbtWithdrawItem[];
575
- };
576
- /**
577
- * Track 2B (Step 2) — Seals a batch of pending OCAP withdrawals into a `@ocap/merkle-tree` compatible
578
- * Rollup block verified by M-of-N distinct validators.
579
- */
580
- sealRollupWithdrawBlock(params: {
581
- validatorSignatures: BridgeValidatorSignature[];
582
- sealedAtUnixSeconds: number;
583
- }): SealedRollupWithdrawBlock;
584
- /**
585
- * Track 2B (Step 3) — Generates the Merkle proof bundle for a sealed `ocapTxHash` so the user
586
- * can claim their ERC-20 ABT from `ArcEvmBridgeGateway.claimWithdrawWithMerkleProof` on Ethereum/Base.
587
- */
588
- generateWithdrawClaimProof(ocapTxHash: string): EvmWithdrawClaimProofBundle;
589
- /**
590
- * Track 2B (Primary — Zero-Rollup-Block EIP-712 Pull Mode):
591
- * Immediately issues a threshold-signed `DirectWithdrawVoucher` for an OCAP withdraw transaction
592
- * without creating any `RollupBlock`, without building any Merkle tree, and without requiring the
593
- * Cloudflare Bridge Node to submit any Ethereum transaction or hold ETH gas.
594
- */
595
- issueDirectWithdrawVoucher(params: {
596
- evmChainId: string;
597
- ocapTxHash: string;
598
- fromDid: string;
599
- recipientEvmAddress: string;
600
- amount: bigint;
601
- issuedAtUnixSeconds: number;
602
- expiresAtUnixSeconds: number;
603
- validatorSignatures: BridgeValidatorSignature[];
604
- }): DirectWithdrawVoucher;
605
- /**
606
- * Retrieves an already-issued Zero-Rollup-Block `DirectWithdrawVoucher` by `ocapTxHash`.
607
- */
608
- getDirectWithdrawVoucher(ocapTxHash: string): DirectWithdrawVoucher;
609
- getReserveWatermarkState(): {
610
- paused: boolean;
611
- latestBlockHeight: number;
612
- latestBlockHash: string;
613
- cumulativeDepositedAbt: bigint;
614
- cumulativeWithdrawnAbt: bigint;
615
- pendingWithdrawAbt: bigint;
616
- availableWithdrawReserveAbt: bigint;
617
- pendingWithdrawCount: number;
618
- issuedDirectVoucherCount: number;
619
- cancelledWithdrawCount: number;
620
- };
621
- /**
622
- * Issue #1245:
623
- * Returns the Circle `bridge.usdc.com`-style Web Portal configuration hosted by the ArcBridge Blocklet.
624
- * Requires zero custom native wallet code (`walletRequired: 'STANDARD_WEB_EIP1193_ONLY'`).
625
- */
626
- getWebPortalConfig(): BridgeWebPortalConfig;
627
- /**
628
- * Issue #1245:
629
- * Builds a wallet-agnostic EIP-1193 transaction execution plan for the ArcBridge Blocklet Web Portal
630
- * (`bridge.usdc.com`-style one-click web experience without custom wallet bridge code).
631
- */
632
- buildWebPortalActionBundle(input: BridgeWebPortalActionInput): BridgeWebPortalActionBundle;
633
- /**
634
- * Cloudflare Workers / Durable Objects / ArcBridge Blocklet Edge Handler (`fetch` & `scheduled` entry point):
635
- * Verifies HMAC-SHA256 webhook authentication and anti-replay nonces for all mutating endpoints.
636
- */
637
- handleCloudflareEdgeRequest(req: CloudflareBridgeEdgeRequest): CloudflareBridgeEdgeResponse;
638
- /**
639
- * Exports a JSON-serializable state snapshot for Cloudflare Durable Object storage (`ctx.storage.put`).
640
- */
641
- exportDurableStateSnapshot(): BridgeDurableStateSnapshot;
642
- /**
643
- * Restores an `OcapSimplifiedEvmBridgeNode` instance from a Cloudflare Durable Object state snapshot.
644
- * Enforces full Red-Team conservation of value, replay-set synchronization, block hash linkage, and
645
- * direct voucher EIP-712 signature verification (`RT-1241-1`).
646
- */
647
- static fromDurableStateSnapshot(snapshot: BridgeDurableStateSnapshot): OcapSimplifiedEvmBridgeNode;
648
- }
649
- interface LocalEvmValidatorKeySpec {
650
- validatorDid: string;
651
- privateKeyHex: string;
652
- evmSignerAddress: string;
653
- }
654
- interface EvmPendingTwoPhaseChallenge {
655
- ocapTxHash: string;
656
- recipientEvmAddress: string;
657
- amount: bigint;
658
- phase1BlockNumber: number;
659
- unlockAtUnixSeconds: number;
660
- challengeHash: string;
661
- sentinelCoSigned: boolean;
662
- }
663
- interface EvmChallengeSentinelCoSignature {
664
- ocapTxHash: string;
665
- challengeHash: string;
666
- sentinelDid: string;
667
- sentinelEvmAddress: string;
668
- v: number;
669
- r: string;
670
- s: string;
671
- replenishedHotAllowanceAbt: bigint;
672
- }
673
- /**
674
- * Computes the deterministic EVM-side Two-Phase Challenge Hash (`seq: 500`):
675
- * When a large withdrawal (`amount >= largeWithdrawThreshold`) is submitted to the Ethereum contract
676
- * in Phase 1, the contract does NOT release funds. Instead, it records the pending withdrawal state
677
- * and computes a fresh `challengeHash` incorporating Ethereum on-chain state (`phase1BlockNumber`):
678
- * `keccak256(abi.encode(TWO_PHASE_CHALLENGE_TYPEHASH, chainId, verifyingContract, ocapTxHash, recipient, amount, phase1BlockNumber))`
679
- * Because `phase1BlockNumber` is determined on Ethereum when Phase 1 is mined, an attacker with stolen
680
- * Phase-1 hot keys (`Key_Hot`) cannot pre-forge Phase 2 offline and must expose Phase 1 on Ethereum first,
681
- * after which `challengeHash` must be verified against the OCAP burn ledger and signed by a separate
682
- * Sentinel/Cold key (`Key_Sentinel`).
683
- */
684
- declare const TWO_PHASE_CHALLENGE_TYPEHASH: string;
685
- declare function computeEvmTwoPhaseChallengeHash(params: {
686
- evmChainId: string;
687
- verifyingContractAddress: string;
688
- ocapTxHash: string;
689
- recipientEvmAddress: string;
690
- amount: bigint;
691
- phase1BlockNumber: number;
692
- }): string;
693
- interface LocalEvmTxExecutionReceipt {
694
- evmTxHash: string;
695
- blockNumber: number;
696
- blockTimestampSeconds: number;
697
- from: string;
698
- to: string;
699
- functionSelector: string;
700
- eventEmitted: 'ERC20Approval' | 'OcapServicePaid' | 'NativeAbtDepositLocked' | 'LargeWithdrawTimelocked' | 'NativeAbtWithdrawClaimed';
701
- details: Record<string, unknown>;
702
- }
703
- /**
704
- * Issue #1245 & #1243 (`seq: 500`):
705
- * Deterministic Local EVM + OCAP End-to-End Testnet Harness (`OcapLocalEvmBridgeTestnetHarness`).
706
- * - Executes raw EIP-1193 ABI `calldataHex` produced by `OcapSimplifiedEvmBridgeNode.buildWebPortalActionBundle`
707
- * against an in-memory EVM state machine implementing `ArcEvmBridgeGateway.sol` + `MultiSigVault.sol` + `IERC20Minimal`.
708
- * - Uses authentic `secp256k1` ECDSA `(v, r, s)` signing and `ecrecover(digest, v, r, s)` public-key recovery.
709
- * - Supports `MultiSigVault` Cold Reserve + Hot `allowance` Isolation (`ERC20Rollup.sol:162-170` & `MultiSigVault.sol:447-473`)
710
- * and EVM-Anchored Two-Phase Challenge-Response (`challengeHash` + independent `Key_Sentinel` co-signature).
711
- */
712
- declare class OcapLocalEvmBridgeTestnetHarness {
713
- readonly evmChainId: string;
714
- readonly gatewayContractAddress: string;
715
- readonly canonicalAbtTokenAddress: string;
716
- readonly bridgeNode: OcapSimplifiedEvmBridgeNode;
717
- readonly validators: readonly LocalEvmValidatorKeySpec[];
718
- private blockNumber;
719
- private blockTimestampSeconds;
720
- private txSequence;
721
- private readonly erc20Balances;
722
- private readonly erc20Allowances;
723
- private readonly validatorEvmSet;
724
- private readonly processedServiceOrders;
725
- private readonly claimedWithdrawTxs;
726
- private readonly cancelledWithdrawTxs;
727
- private readonly timelockUnlockAt;
728
- private readonly pendingTwoPhaseChallenges;
729
- private readonly dailyWithdrawnAbt;
730
- private multiSigColdVaultAddress;
731
- private coldVaultSignerEvmAddress;
732
- private sentinelSignerDid;
733
- private sentinelSignerEvmAddress;
734
- private evmPaused;
735
- private evmCumulativeDepositedAbt;
736
- private evmCumulativeWithdrawnAbt;
737
- private readonly ocapNativeAbtBalances;
738
- private readonly ocapBurnedWithdrawTxs;
739
- private readonly ocapDeliveredServiceAssets;
740
- constructor(params: {
741
- evmChainId?: string;
742
- gatewayContractAddress?: string;
743
- canonicalAbtTokenAddress: string;
744
- usdcTokenAddress: string;
745
- bridgeNode: OcapSimplifiedEvmBridgeNode;
746
- validatorPrivateKeys: Array<{
747
- validatorDid: string;
748
- privateKeyHex: string;
749
- }>;
750
- });
751
- getBlockTimestampSeconds(): number;
752
- advanceTimeSeconds(deltaSeconds: number): number;
753
- mintTestErc20(tokenAddress: string, toEvmAddress: string, amount: bigint): void;
754
- getErc20Balance(tokenAddress: string, ownerEvmAddress: string): bigint;
755
- getOcapNativeAbtBalance(did: string): bigint;
756
- getOcapDeliveredAssets(did: string): string[];
757
- /**
758
- * Executes a user-signed OCAP `withdraw_token_v2` burn on the OCAP ledger and collects M-of-N
759
- * real `secp256k1` EIP-712 signatures (`v, r, s`) from the bridge validators.
760
- */
761
- initiateOcapWithdrawAndIssueEip712Voucher(params: {
762
- fromDid: string;
763
- recipientEvmAddress: string;
764
- amount: bigint;
765
- ttlSeconds?: number;
766
- }): DirectWithdrawVoucher;
767
- /**
768
- * Executes a raw EIP-1193 transaction step (`to`, `calldataHex`) on the Local EVM Testnet,
769
- * decoding the raw ABI hex calldata and enforcing all `ArcEvmBridgeGateway.sol` invariants.
770
- */
771
- executeEip1193Step(senderEvmAddress: string, step: Eip1193TransactionStep): LocalEvmTxExecutionReceipt;
772
- /**
773
- * Configures the `MultiSigVault.sol` Cold Reserve + Hot `allowance` Isolation & Independent
774
- * Sentinel Second-Factor Key Domain (`seq: 500`, matching `ArcBlock/contracts/src/ERC20Rollup.sol:162-170`
775
- * and `MultiSigVault.sol:447-473`):
776
- * - The Bridge Gateway contract (`gatewayContractAddress`) holds 0 ERC-20 ABT directly.
777
- * - All reserves sit in `vaultAddress` (`MultiSigVault`), which grants `gatewayContractAddress` a bounded
778
- * ERC-20 `allowance(vaultAddress, gatewayContractAddress)` (`initialHotAllowanceAbt`).
779
- * - Enforces strict cryptographic key-domain separation: neither `coldVaultPrivateKeyHex` nor
780
- * `sentinelPrivateKeyHex` may overlap with any Phase-1 hot bridge validator key (`validatorEvmSet`).
781
- */
782
- configureMultiSigColdVault(params: {
783
- vaultAddress: string;
784
- coldVaultPrivateKeyHex: string;
785
- sentinelDid: string;
786
- sentinelPrivateKeyHex: string;
787
- initialColdReserveAbt: bigint;
788
- initialHotAllowanceAbt: bigint;
789
- }): {
790
- vaultAddress: string;
791
- coldVaultSignerEvmAddress: string;
792
- sentinelDid: string;
793
- sentinelEvmAddress: string;
794
- coldReserveAbt: bigint;
795
- hotAllowanceAbt: bigint;
796
- };
797
- getMultiSigVaultState(): {
798
- vaultAddress: string | null;
799
- coldReserveAbt: bigint;
800
- hotAllowanceAbt: bigint;
801
- gatewayDirectBalanceAbt: bigint;
802
- sentinelEvmAddress: string | null;
803
- };
804
- /**
805
- * Mirrors `MultiSigVault.approveERC20(token, spender, ApproveAction, amount, signatures)`:
806
- * Only the independent Cold Vault signer (`coldVaultPrivateKeyHex`) can increase or decrease
807
- * the ERC-20 `allowance(vaultAddress, gatewayContractAddress)` hot exposure cap.
808
- */
809
- approveColdVaultHotAllowance(params: {
810
- action: 'INCREASE' | 'DECREASE';
811
- amount: bigint;
812
- coldVaultPrivateKeyHex: string;
813
- }): {
814
- vaultAddress: string;
815
- newHotAllowanceAbt: bigint;
816
- };
817
- getPendingTwoPhaseChallenge(ocapTxHash: string): EvmPendingTwoPhaseChallenge | undefined;
818
- /**
819
- * Intermediate Cross-Chain Handshake (`seq: 500`):
820
- * Takes the `challengeHash` emitted on Ethereum during Phase 1 back to the OCAP / Sentinel control plane:
821
- * 1. Verifies that `ocapTxHash` exists in `pendingTwoPhaseChallenges` on Ethereum and its `challengeHash` matches.
822
- * 2. Verifies against the OCAP ledger (`ocapBurnedWithdrawTxs`) that `ocapTxHash` genuinely burned the exact
823
- * `amount` for `recipientEvmAddress`. If an attacker forged Phase 1 with stolen `Key_Hot` without a matching
824
- * OCAP burn, Sentinel immediately cancels the withdrawal on EVM, pauses the bridge, and aborts!
825
- * 3. Uses the independent Second-Factor key (`sentinelPrivateKeyHex`, disjoint from `Key_Hot`) to sign `challengeHash`,
826
- * and optionally replenishes the `MultiSigVault` hot `allowance` if `coldVaultPrivateKeyHex` is provided.
827
- */
828
- coSignEvmWithdrawalChallenge(params: {
829
- ocapTxHash: string;
830
- challengeHash: string;
831
- sentinelPrivateKeyHex: string;
832
- coldVaultPrivateKeyHexForAllowanceTopUp?: string;
833
- }): EvmChallengeSentinelCoSignature;
834
- /**
835
- * Phase 2 on Ethereum (`seq: 500`):
836
- * Submits the independent second-factor signature (`sig_Phase2` over `challengeHash`) to the Ethereum
837
- * gateway contract. The contract verifies:
838
- * 1. The withdrawal completed Phase 1 on Ethereum (`pendingTwoPhaseChallenges.get(ocapTxHash)`) and its
839
- * on-chain `challengeHash` matches.
840
- * 2. `ecrecover(challengeHash, v, r, s)` recovers the authorized independent `sentinelSignerEvmAddress`.
841
- * 3. Transfers `amount` from `MultiSigVault` (`safeTransferFrom(token, vaultAddress, recipient, amount)`)
842
- * within the approved `allowance(vaultAddress, gatewayContractAddress)`.
843
- */
844
- finalizeChallengedWithdrawOnEvm(params: {
845
- senderEvmAddress: string;
846
- ocapTxHash: string;
847
- challengeHash: string;
848
- v: number;
849
- r: string;
850
- s: string;
851
- }): LocalEvmTxExecutionReceipt;
852
- private settleEvmWithdrawTransfer;
853
- /**
854
- * Crowdsourced User-Wallet Watchtower Witness (`seq: 463`):
855
- * Any user wallet or Blocklet can inspect pending timelocked withdrawals on the EVM gateway contract
856
- * against the authentic OCAP chain burn ledger (`ocapBurnedWithdrawTxs`).
857
- * If a timelocked withdrawal on EVM does not exist on OCAP (or has a mismatched amount/recipient),
858
- * the Watchtower Witness flags the anomaly and triggers Guardian cancellation + pause.
859
- */
860
- verifyWatchtowerStateConsistency(witnessWalletDid: string): {
861
- consistent: boolean;
862
- witnessWalletDid: string;
863
- flaggedTxHashes: string[];
864
- autoCancelledAndPaused: boolean;
865
- };
866
- private transferFromErc20;
867
- private transferDirectErc20;
868
- }
869
- declare const MULTISIG_OP_TYPEHASH: string;
870
- declare const BRIDGE_CHARTER_KIND: "BridgeGovernanceCharter";
871
- type MultiSigOperationSelector = 'SEND_ETHER' | 'SEND_ERC20' | 'APPROVE_ERC20' | 'ADD_SIGNER' | 'REMOVE_SIGNER' | 'SET_THRESHOLD' | 'REPLACE_SEED_SIGNER' | 'MIGRATE_VAULT';
872
- /**
873
- * Hardened `SignerManagerV2` + `MultiSigVaultV2` EIP-712 Digest (`seq: 504`):
874
- * Fixes the 4 Critical/High vulnerabilities identified in legacy `SignerManager.sol` & `MultiSigVault.sol`:
875
- * 1. CRITICAL-1 (Cross-Contract / Cross-Method Replay & Front-Run Nonce Burn):
876
- * Binds `targetContract` (`msg.sender`, e.g., `vaultAddress` vs `signerManagerAddress`), `selector` (`bytes4`),
877
- * and a contract-wide sequential `nonce` into the EIP-712 struct hash. Calling `ensureSignatures` directly
878
- * from an EOA or unauthorized contract produces a different `targetContract` (`msg.sender`) and fails recovery.
879
- * 2. CRITICAL-2 (Permanent Vault Lockout on Single Lost Seed Signer):
880
- * Supports `seedThreshold` (M-of-K seed quorum) and `REPLACE_SEED_SIGNER` recovery rotation.
881
- * 3. HIGH-1 (Opaque Raw-Hash Signing & `abi.encodePacked` Collision):
882
- * Uses EIP-712 Typed Structured Data with fixed-width 32-byte `abi.encode` words for wallet Clear-Signing.
883
- * 4. HIGH-2 (Per-Signer Nonce Desynchronization Under Partial Subset Signing):
884
- * Uses a single Safe-style sequential `nonce` per target contract and strictly ascending signer address order (`O(N)`).
885
- */
886
- declare function computeHardenedMultiSigOpDigest(params: {
887
- evmChainId: string;
888
- signerManagerAddress: string;
889
- targetContractAddress: string;
890
- operation: MultiSigOperationSelector;
891
- nonce: number;
892
- paramsHash: string;
893
- }): {
894
- domainSeparator: string;
895
- structHash: string;
896
- digest: string;
897
- selectorHex: string;
898
- };
899
- interface HardenedMultiSigSignature {
900
- signerEvmAddress: string;
901
- v: number;
902
- r: string;
903
- s: string;
904
- }
905
- declare class HardenedMultiSigSignerManagerV2 {
906
- readonly evmChainId: string;
907
- readonly signerManagerAddress: string;
908
- private readonly signers;
909
- private readonly seedSigners;
910
- private threshold;
911
- private seedThreshold;
912
- private readonly noncesByTarget;
913
- private readonly vetoedProposalHashes;
914
- constructor(params: {
915
- evmChainId: string;
916
- signerManagerAddress: string;
917
- signers: string[];
918
- seedSigners: string[];
919
- threshold: number;
920
- seedThreshold?: number;
921
- });
922
- getTargetNonce(targetContractAddress: string): number;
923
- getState(): {
924
- evmChainId: string;
925
- signerManagerAddress: string;
926
- signers: string[];
927
- seedSigners: string[];
928
- threshold: number;
929
- seedThreshold: number;
930
- };
931
- /**
932
- * Verifies EIP-712 signatures bound to `(evmChainId, signerManagerAddress, callerTargetContract, operation, nonce, paramsHash)`
933
- * in O(N) time with strictly ascending signer order (`currentSigner > lastSigner`) and `seedThreshold` check,
934
- * then atomically increments the target contract's sequential nonce.
935
- */
936
- ensureSignaturesForTarget(params: {
937
- callerTargetContract: string;
938
- operation: MultiSigOperationSelector;
939
- paramsHash: string;
940
- signatures: HardenedMultiSigSignature[];
941
- }): {
942
- consumedNonce: number;
943
- digest: string;
944
- verifiedSigners: string[];
945
- };
946
- /**
947
- * Recoverable Seed Signer Rotation (`CRITICAL-2` fix):
948
- * Replaces a lost or rotated `oldSeedSigner` with `newSeedSigner` when authorized by a valid quorum
949
- * meeting `threshold` and `seedThreshold` (so losing 1 seed key in a 2-of-3 seed quorum never bricks the vault).
950
- */
951
- replaceSeedSigner(params: {
952
- oldSeedSigner: string;
953
- newSeedSigner: string;
954
- signatures: HardenedMultiSigSignature[];
955
- }): {
956
- oldSeedSigner: string;
957
- newSeedSigner: string;
958
- consumedNonce: number;
959
- };
960
- isProposalVetoed(vledgerProposalHash: string): boolean;
961
- /**
962
- * Cross-Chain Seed Signer Veto Attestation (`RT-1262-8` & `RT-1262-9`):
963
- * Verifies an EIP-712 `MultiSigVetoAttestation` signed by an active Seed Signer and permanently blocks
964
- * `vledgerProposalHash` on the foreign chain `SignerManagerV2` contract, preventing a rogue signer from
965
- * scraping pre-veto voter signatures off VLedger and submitting them directly to the EVM contract.
966
- */
967
- recordVetoAttestation(params: {
968
- vledgerProposalHash: string;
969
- targetContractAddress: string;
970
- nonce: number;
971
- seedEvmAddress: string;
972
- v: number;
973
- r: string;
974
- s: string;
975
- }): {
976
- vledgerProposalHash: string;
977
- seedEvmAddress: string;
978
- digest: string;
979
- };
980
- /**
981
- * Stateless Foreign-Chain Certificate Verification & Nonce Consumption (`RT-1262-8`, `RT-1262-11..15`):
982
- * Models the on-chain EVM `SignerManagerV2` contract verification without relying on VLedger's in-memory map.
983
- * Enforces:
984
- * - Cryptographic veto check (`!this.vetoedProposalHashes.has(cert.vledgerProposalHash)`)
985
- * - EIP-712 bound cooldown & TTL window (`executableAfterUnixSeconds <= nowUnixSeconds <= expiresAtUnixSeconds`)
986
- * - Full `vledgerProposalHash`, `certificateHash`, and optional `clearSigningPreview` (`paramsHash`) integrity
987
- * - Active proposer check + Seed Executor & Proposer-Executor Separation (`executor !== proposer`) for critical ops
988
- * - Holder Hardware Final Release signature + M-of-N EIP-712 voter signatures with `seedThreshold`
989
- */
990
- verifyAndConsumePublishedCertificate(params: {
991
- certificate: OcapPublishedMultiSigCertificate;
992
- executorEvmAddress: string;
993
- holderReleaseSignature: {
994
- v: number;
995
- r: string;
996
- s: string;
997
- };
998
- nowUnixSeconds: number;
999
- minCooldownSeconds?: number;
1000
- }): {
1001
- consumedNonce: number;
1002
- verifiedSigners: string[];
1003
- certificateHash: string;
1004
- vledgerProposalHash: string;
1005
- executorEvmAddress: string;
1006
- };
1007
- }
1008
- interface BridgeValidatorEndpointSpec {
1009
- did: string;
1010
- evmSignerAddress: string;
1011
- endpoint?: string;
1012
- role: 'seed' | 'validator';
1013
- }
1014
- type BridgeGovernanceActionKind = 'PUBLISH' | 'UPDATE_LIMITS' | 'PAUSE' | 'RESUME' | 'MIGRATE_CONTRACT' | 'MIGRATE_VAULT' | 'ROTATE_SIGNERS' | 'CLOSE';
1015
- /**
1016
- * On-Chain Public Bridge Governance Charter (`seq: 504`):
1017
- * Preserves OCAP's public on-chain bridge configuration & governance audit trail (`core/state/src/states/rollup.ts`)
1018
- * after retiring the legacy Rollup block-packing machinery (`RollupBlock`).
1019
- */
1020
- interface BridgeGovernanceCharterState {
1021
- kind: typeof BRIDGE_CHARTER_KIND;
1022
- schemaVersion: 1;
1023
- bridgeId: string;
1024
- rollupAddress: string;
1025
- ocapTokenAddress: string;
1026
- supportedTokens: string[];
1027
- foreignChainType: 'EVM' | 'OCAP_ISOMORPHIC';
1028
- foreignChainId: string;
1029
- foreignChainName: string;
1030
- foreignTokenContractAddress: string;
1031
- verifyingContractAddress: string;
1032
- vaultAddress: string;
1033
- signerManagerAddress: string;
1034
- sentinelDid: string;
1035
- sentinelEvmAddress: string;
1036
- guardianDid: string;
1037
- migrateHistory: string[];
1038
- vaultHistory: string[];
1039
- validators: BridgeValidatorEndpointSpec[];
1040
- minValidatorSignatures: number;
1041
- seedValidatorQuorum: number;
1042
- minConfirmations: number;
1043
- limits: {
1044
- minDepositAmount: string;
1045
- maxDepositAmount: string;
1046
- minWithdrawAmount: string;
1047
- maxWithdrawAmount: string;
1048
- maxDailyWithdrawAmount: string;
1049
- largeWithdrawTimelockThreshold: string;
1050
- timelockDelaySeconds: number;
1051
- };
1052
- zeroBridgeFee: true;
1053
- bridgeFeeBps: 0;
1054
- paused: boolean;
1055
- closed: boolean;
1056
- enforceReserveWatermark: true;
1057
- reserves: Record<string, {
1058
- totalDeposited: string;
1059
- totalWithdrawn: string;
1060
- }>;
1061
- governanceVersion: number;
1062
- stateCommitmentHash: string;
1063
- lastGovernanceAction: {
1064
- action: BridgeGovernanceActionKind;
1065
- ocapTxHash: string;
1066
- blockHeight: number;
1067
- };
1068
- }
1069
- declare function computeBridgeGovernanceCharterHash(state: Omit<BridgeGovernanceCharterState, 'stateCommitmentHash'>): string;
1070
- declare class OcapOnChainBridgeGovernanceRegistry {
1071
- private readonly chartersByBridgeId;
1072
- publishBridgeCharter(params: {
1073
- bridgeId: string;
1074
- rollupAddress: string;
1075
- ocapTokenAddress: string;
1076
- supportedTokens?: string[];
1077
- foreignChainType?: 'EVM' | 'OCAP_ISOMORPHIC';
1078
- foreignChainId: string;
1079
- foreignChainName: string;
1080
- foreignTokenContractAddress: string;
1081
- verifyingContractAddress: string;
1082
- vaultAddress: string;
1083
- signerManagerAddress: string;
1084
- sentinelDid: string;
1085
- sentinelEvmAddress: string;
1086
- guardianDid: string;
1087
- validators: BridgeValidatorEndpointSpec[];
1088
- minValidatorSignatures: number;
1089
- seedValidatorQuorum?: number;
1090
- minConfirmations?: number;
1091
- limits: BridgeGovernanceCharterState['limits'];
1092
- ocapTxHash: string;
1093
- blockHeight: number;
1094
- }): BridgeGovernanceCharterState;
1095
- getBridgeCharter(bridgeId: string): BridgeGovernanceCharterState;
1096
- /**
1097
- * Executes an on-chain M-of-N governed bridge state transition (`PAUSE`, `RESUME`, `MIGRATE_CONTRACT`,
1098
- * `MIGRATE_VAULT`, `CLOSE`), enforcing the exact production invariants from `core/state/src/states/rollup.ts:527-630`:
1099
- * - Requires `minValidatorSignatures` distinct validator DIDs and at least `seedValidatorQuorum` seed validators.
1100
- * - `MIGRATE_CONTRACT` and `MIGRATE_VAULT` require `paused === true && closed === false`, reject self-migration
1101
- * and cyclic reuse of any historical address in `migrateHistory` / `vaultHistory`, and append the old address
1102
- * to the public on-chain linear history.
1103
- */
1104
- applyGovernedTransition(params: {
1105
- bridgeId: string;
1106
- action: 'PAUSE' | 'RESUME' | 'MIGRATE_CONTRACT' | 'MIGRATE_VAULT' | 'CLOSE';
1107
- newAddress?: string;
1108
- signerValidatorDids: string[];
1109
- ocapTxHash: string;
1110
- blockHeight: number;
1111
- }): BridgeGovernanceCharterState;
1112
- private verifyGovernanceSigners;
1113
- }
1114
- declare const PUBLISHED_MULTISIG_CERT_OP_TYPEHASH: string;
1115
- declare const HOLDER_RELEASE_INTENT_TYPEHASH: string;
1116
- declare const MULTISIG_VETO_ATTESTATION_TYPEHASH: string;
1117
- declare const HARD_FLOOR_MULTISIG_COOLDOWN_SECONDS = 60;
1118
- declare const DEFAULT_MIN_MULTISIG_COOLDOWN_SECONDS = 3600;
1119
- declare const MIN_MULTISIG_CERT_TTL_SECONDS = 300;
1120
- declare const MAX_MULTISIG_CERT_TTL_SECONDS: number;
1121
- declare const DEFAULT_MULTISIG_CERT_TTL_SECONDS: number;
1122
- declare const MAX_PUBLISHED_MULTISIG_PROPOSALS = 1024;
1123
- declare const MAX_MULTISIG_VOTES_PER_CERT = 32;
1124
- type PublishedMultiSigLedgerMode = 'VLEDGER' | 'OCAP_MAIN_CHAIN';
1125
- declare const EXPECTED_CATEGORY_BY_OPERATION: Record<MultiSigOperationSelector, MultiSigProposalIntentInput['category']>;
1126
- interface MultiSigDecodedParams {
1127
- operation: MultiSigOperationSelector;
1128
- tokenAddress?: string;
1129
- recipientOrSpenderAddress?: string;
1130
- amountWei?: string;
1131
- signerAddress?: string;
1132
- oldSeedSignerAddress?: string;
1133
- newSeedSignerAddress?: string;
1134
- newThreshold?: number;
1135
- newVaultAddress?: string;
1136
- }
1137
- interface PublishedMultiSigClearSigningPreview {
1138
- youAuthorize: string;
1139
- targetVault: string;
1140
- exactOutflow: string;
1141
- decodedParams: MultiSigDecodedParams;
1142
- postConditions: {
1143
- strictZeroUnlistedOutflow: true;
1144
- maxTokenOutflowWei: string;
1145
- allowedRecipientOrSpender?: string;
1146
- };
1147
- }
1148
- /**
1149
- * Deterministic ABI-style parameter hash computation from structured `MultiSigDecodedParams` (`RT-1262-11`):
1150
- * Eliminates Bybit-style blind-signing by proving that human-readable Clear-Signing fields (`tokenAddress`,
1151
- * `recipientOrSpenderAddress`, `amountWei`, `newVaultAddress`, etc.) hash to the exact `paramsHash` in EIP-712.
1152
- */
1153
- declare function computeMultiSigOperationParamsHash(decoded: MultiSigDecodedParams): string;
1154
- declare function buildPublishedMultiSigClearSigningPreview(params: {
1155
- targetContractAddress: string;
1156
- nonce: number;
1157
- decodedParams: MultiSigDecodedParams;
1158
- }): PublishedMultiSigClearSigningPreview;
1159
- interface MultiSigProposalIntentInput {
1160
- proposalId: string;
1161
- ledgerMode: PublishedMultiSigLedgerMode;
1162
- proposerDid: string;
1163
- proposerEvmAddress: string;
1164
- title: string;
1165
- rationale: string;
1166
- category: 'TREASURY_TRANSFER' | 'ALLOWANCE_UPDATE' | 'SIGNER_ROTATION' | 'BRIDGE_GOVERNANCE' | 'VAULT_MIGRATION';
1167
- evmChainId: string;
1168
- signerManagerAddress: string;
1169
- targetContractAddress: string;
1170
- operation: MultiSigOperationSelector;
1171
- nonce: number;
1172
- paramsHash: string;
1173
- proposedAtUnixSeconds: number;
1174
- cooldownSeconds?: number;
1175
- ttlSeconds?: number;
1176
- decodedParams?: MultiSigDecodedParams;
1177
- }
1178
- interface MultiSigVoteRecord {
1179
- voterDid: string;
1180
- voterEvmAddress: string;
1181
- comment: string;
1182
- votedAtUnixSeconds: number;
1183
- v: number;
1184
- r: string;
1185
- s: string;
1186
- eip712Digest: string;
1187
- }
1188
- interface OcapPublishedMultiSigCertificate {
1189
- kind: 'OcapPublishedMultiSigCert';
1190
- schemaVersion: 1;
1191
- proposalId: string;
1192
- ledgerMode: PublishedMultiSigLedgerMode;
1193
- vledgerProposalHash: string;
1194
- vledgerStateRoot: string;
1195
- proposerDid: string;
1196
- proposerEvmAddress: string;
1197
- title: string;
1198
- rationale: string;
1199
- category: MultiSigProposalIntentInput['category'];
1200
- evmChainId: string;
1201
- signerManagerAddress: string;
1202
- targetContractAddress: string;
1203
- operation: MultiSigOperationSelector;
1204
- selectorHex: string;
1205
- nonce: number;
1206
- paramsHash: string;
1207
- proposedAtUnixSeconds: number;
1208
- executableAfterUnixSeconds: number;
1209
- expiresAtUnixSeconds: number;
1210
- issuedAtUnixSeconds: number;
1211
- clearSigningPreview?: PublishedMultiSigClearSigningPreview;
1212
- votes: MultiSigVoteRecord[];
1213
- certificateHash: string;
1214
- }
1215
- declare function computeVLedgerMultiSigProposalHash(input: MultiSigProposalIntentInput, options?: {
1216
- minCooldownSeconds?: number;
1217
- }): string;
1218
- /**
1219
- * Computes the canonical, tamper-evident hash over all fields of an `OcapPublishedMultiSigCertificate` (RT-1262-3, RT-1262-15).
1220
- */
1221
- declare function computePublishedMultiSigCertificateHash(cert: Omit<OcapPublishedMultiSigCertificate, 'certificateHash'>): string;
1222
- /**
1223
- * Computes the EIP-712 digest for a Published Indirect Multi-Sig Vote (`seq: 508..511`, Issue #1262):
1224
- * Binds `vledgerProposalHash`, `executableAfterUnixSeconds`, and `expiresAtUnixSeconds` directly into
1225
- * the foreign chain `MultiSigVaultV2` / `SignerManagerV2` EIP-712 struct hash (`RT-1262-8`, `RT-1262-13`).
1226
- */
1227
- declare function computePublishedMultiSigVoteDigest(params: {
1228
- evmChainId: string;
1229
- signerManagerAddress: string;
1230
- vledgerProposalHash: string;
1231
- targetContractAddress: string;
1232
- operation: MultiSigOperationSelector;
1233
- nonce: number;
1234
- paramsHash: string;
1235
- executableAfterUnixSeconds: number;
1236
- expiresAtUnixSeconds: number;
1237
- }): {
1238
- domainSeparator: string;
1239
- structHash: string;
1240
- digest: string;
1241
- selectorHex: string;
1242
- };
1243
- /**
1244
- * Computes the EIP-712 Seed Signer Veto Attestation Digest (`RT-1262-9`):
1245
- * Allows any Seed Signer to cryptographically sign a veto that is enforced both on VLedger and on the
1246
- * foreign-chain `SignerManagerV2` contract (`recordVetoAttestation`).
1247
- */
1248
- declare function computeMultiSigVetoAttestationDigest(params: {
1249
- evmChainId: string;
1250
- signerManagerAddress: string;
1251
- vledgerProposalHash: string;
1252
- targetContractAddress: string;
1253
- nonce: number;
1254
- seedEvmAddress: string;
1255
- }): {
1256
- domainSeparator: string;
1257
- structHash: string;
1258
- digest: string;
1259
- };
1260
- /**
1261
- * Computes the Holder Hardware Final Release Intent Digest (`seq: 508..511`, Issue #1262):
1262
- * Because OCAP software nodes never hold custody keys or auto-sign foreign chain transactions,
1263
- * an authorized human executor must sign this Final Release Intent with their hardware key
1264
- * when submitting the `OcapPublishedMultiSigCertificate` to the foreign chain contract.
1265
- */
1266
- declare function computeHolderFinalReleaseDigest(params: {
1267
- evmChainId: string;
1268
- signerManagerAddress: string;
1269
- certificateHash: string;
1270
- vledgerProposalHash: string;
1271
- targetContractAddress: string;
1272
- nonce: number;
1273
- executableAfterUnixSeconds: number;
1274
- expiresAtUnixSeconds: number;
1275
- executorEvmAddress: string;
1276
- }): string;
1277
- /**
1278
- * Standardized Published Indirect Multi-Sig Engine (`OcapPublishedMultiSigEngine`, Issue #1262):
1279
- * Implements the 3-stage VLedger / OCAP Certificate-Driven Cross-Chain Control Plane:
1280
- * 1. Public Proposal & Vote History on VLedger / OCAP (with pre-execution notifications, cooldowns, and cryptographic Veto).
1281
- * 2. Deterministic `OcapPublishedMultiSigCertificate` generation once M-of-N (`threshold` + `seedThreshold`) is met.
1282
- * 3. Foreign-chain `MultiSigVaultV2` execution gated by BOTH the published certificate AND an individual holder's
1283
- * hardware Final Release Signature (zero software custody on OCAP nodes).
1284
- */
1285
- declare class OcapPublishedMultiSigEngine {
1286
- readonly signerManager: HardenedMultiSigSignerManagerV2;
1287
- readonly minCooldownSeconds: number;
1288
- private readonly proposals;
1289
- private vledgerSequence;
1290
- private vledgerStateRoot;
1291
- constructor(signerManager: HardenedMultiSigSignerManagerV2, options?: {
1292
- minCooldownSeconds?: number;
1293
- });
1294
- getVLedgerStateRoot(): string;
1295
- getProposalStatus(proposalId: string, nowUnixSeconds?: number): 'VOTING' | 'CERT_ISSUED' | 'EXECUTED' | 'VETOED' | 'EXPIRED' | undefined;
1296
- createProposal(input: MultiSigProposalIntentInput): {
1297
- proposalId: string;
1298
- vledgerProposalHash: string;
1299
- executableAfterUnixSeconds: number;
1300
- expiresAtUnixSeconds: number;
1301
- clearSigningPreview?: PublishedMultiSigClearSigningPreview;
1302
- vledgerStateRoot: string;
1303
- };
1304
- recordVote(params: {
1305
- proposalId: string;
1306
- voterDid: string;
1307
- voterEvmAddress: string;
1308
- comment: string;
1309
- votedAtUnixSeconds: number;
1310
- v: number;
1311
- r: string;
1312
- s: string;
1313
- }): {
1314
- proposalId: string;
1315
- totalVotes: number;
1316
- vledgerStateRoot: string;
1317
- };
1318
- /**
1319
- * Cryptographically Authenticated Seed Signer Veto (`RT-1262-8` & `RT-1262-9`):
1320
- * Verifies the Seed Signer's EIP-712 `MultiSigVetoAttestation` signature via `ecrecover` and records the
1321
- * veto on BOTH VLedger (`prop.vetoed = true`) AND the foreign-chain `SignerManagerV2` contract
1322
- * (`this.signerManager.recordVetoAttestation`), blocking off-chain signature scraping bypasses.
1323
- */
1324
- vetoProposal(params: {
1325
- proposalId: string;
1326
- guardianOrSeedDid: string;
1327
- seedEvmAddress: string;
1328
- reason: string;
1329
- v: number;
1330
- r: string;
1331
- s: string;
1332
- }): {
1333
- vledgerProposalHash: string;
1334
- vetoAttestationDigest: string;
1335
- vledgerStateRoot: string;
1336
- };
1337
- /**
1338
- * Stage 2: Crystallizes the verified vote records into an immutable `OcapPublishedMultiSigCertificate`
1339
- * once M-of-N (`threshold` + `seedThreshold`) is met and `executableAfterUnixSeconds <= nowUnixSeconds <= expiresAtUnixSeconds`.
1340
- */
1341
- issuePublishedCertificate(params: {
1342
- proposalId: string;
1343
- nowUnixSeconds: number;
1344
- }): OcapPublishedMultiSigCertificate;
1345
- /**
1346
- * Stage 3 (Holder Hardware Final Release on Foreign Chain):
1347
- * Delegates to `this.signerManager.verifyAndConsumePublishedCertificate` (stateless foreign-chain contract verifier)
1348
- * AND verifies VLedger state consistency, then marks the proposal `EXECUTED`.
1349
- */
1350
- executeWithPublishedCertificate(params: {
1351
- certificate: OcapPublishedMultiSigCertificate;
1352
- executorEvmAddress: string;
1353
- holderReleaseSignature: {
1354
- v: number;
1355
- r: string;
1356
- s: string;
1357
- };
1358
- nowUnixSeconds?: number;
1359
- }): {
1360
- executed: true;
1361
- proposalId: string;
1362
- vledgerProposalHash: string;
1363
- certificateHash: string;
1364
- executorEvmAddress: string;
1365
- consumedNonce: number;
1366
- verifiedSigners: string[];
1367
- };
1368
- }
1369
- //#endregion
1370
- export { ARC_EVM_BRIDGE_GATEWAY_SOLIDITY_SPEC, BRIDGE_CHARTER_KIND, BridgeDurableStateSnapshot, BridgeGovernanceActionKind, BridgeGovernanceCharterState, BridgeValidatorEndpointSpec, BridgeValidatorSignature, BridgeWebPortalActionBundle, BridgeWebPortalActionInput, BridgeWebPortalConfig, CloudflareBridgeEdgeRequest, CloudflareBridgeEdgeResponse, DEFAULT_MAX_ROLLUP_BLOCK_SIZE, DEFAULT_MIN_EVM_CONFIRMATIONS, DEFAULT_MIN_MULTISIG_COOLDOWN_SECONDS, DEFAULT_MULTISIG_CERT_TTL_SECONDS, DEFAULT_ROLLUP_SUNSET_ACTIVATION_HEIGHT, DEFAULT_VERIFYING_CONTRACT_ADDRESS, DEFAULT_WITHDRAW_TIMELOCK_DELAY_SECONDS, DEPRECATED_ROLLUP_PROTOCOL_TYPE_URLS, DIRECT_WITHDRAW_TYPEHASH, DeprecatedRollupProtocolTypeUrl, DirectWithdrawVoucher, EIP712_BRIDGE_DOMAIN_NAME, EIP712_BRIDGE_DOMAIN_VERSION, EIP712_DOMAIN_TYPEHASH, EMPTY_ROLLUP_MERKLE_ROOT, EXPECTED_CATEGORY_BY_OPERATION, Eip1193TransactionStep, EvmAbtDepositEventInput, EvmChallengeSentinelCoSignature, EvmPendingTwoPhaseChallenge, EvmServicePaymentEventInput, EvmWithdrawClaimProofBundle, HARD_FLOOR_MULTISIG_COOLDOWN_SECONDS, HOLDER_RELEASE_INTENT_TYPEHASH, HardenedMultiSigSignature, HardenedMultiSigSignerManagerV2, LegacyRollupReadOnlySummary, LegacyRollupRecordKind, LocalEvmTxExecutionReceipt, LocalEvmValidatorKeySpec, MAX_DIRECT_VOUCHER_TTL_SECONDS, MAX_EDGE_WEBHOOK_BODY_BYTES, MAX_EDGE_WEBHOOK_SKEW_SECONDS, MAX_MULTISIG_CERT_TTL_SECONDS, MAX_MULTISIG_VOTES_PER_CERT, MAX_PUBLISHED_MULTISIG_PROPOSALS, MAX_TRACKED_WEBHOOK_NONCES, MIN_DIRECT_VOUCHER_TTL_SECONDS, MIN_MULTISIG_CERT_TTL_SECONDS, MULTISIG_OP_TYPEHASH, MULTISIG_VETO_ATTESTATION_TYPEHASH, MultiSigDecodedParams, MultiSigOperationSelector, MultiSigProposalIntentInput, MultiSigVoteRecord, OcapAbtWithdrawItem, OcapLocalEvmBridgeTestnetHarness, OcapOnChainBridgeGovernanceRegistry, OcapPublishedMultiSigCertificate, OcapPublishedMultiSigEngine, OcapRelayerDepositTxInstruction, OcapServiceDeliveryInstruction, OcapSimplifiedEvmBridgeNode, PUBLISHED_MULTISIG_CERT_OP_TYPEHASH, PublishedMultiSigClearSigningPreview, PublishedMultiSigLedgerMode, SealedRollupWithdrawBlock, SimplifiedEvmBridgeConfig, TWO_PHASE_CHALLENGE_TYPEHASH, ZERO_BYTES32_HASH, ZERO_EVM_ADDRESS, assertRollupProtocolNotSunset, buildEvmBridgeMerkleTree, buildPublishedMultiSigClearSigningPreview, computeBridgeGovernanceCharterHash, computeDirectWithdrawVoucherDigest, computeEdgeWebhookHmac, computeEip712BridgeDomainSeparator, computeEip712WithdrawStructHash, computeEvmBridgeBlockHash, computeEvmBridgeTxsHash, computeEvmBridgeWithdrawLeafHash, computeEvmTwoPhaseChallengeHash, computeHardenedMultiSigOpDigest, computeHolderFinalReleaseDigest, computeMultiSigOperationParamsHash, computeMultiSigVetoAttestationDigest, computePublishedMultiSigCertificateHash, computePublishedMultiSigVoteDigest, computeVLedgerMultiSigProposalHash, computeValidatorBlockSignatureDigest, computeValidatorVoucherSignatureDigest, deriveEvmAddressFromPrivateKeyHex, ecrecoverEvmAddress, encodeEvmBridgeWithdrawPackedPreimage, isDeprecatedRollupWriteProtocol, parseLegacyRollupReadOnlyRecord, signDigestWithSecp256k1PrivateKey, verifyDirectWithdrawVoucher, verifyEvmBridgeMerkleProof };