@ocap/tx-pipeline 1.31.4 → 1.31.6

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 (57) hide show
  1. package/esm/bridge-release-keys.d.mts +17 -1
  2. package/esm/bridge-release-keys.mjs +35 -20
  3. package/esm/bridge-reserves.d.mts +48 -9
  4. package/esm/bridge-reserves.mjs +66 -16
  5. package/esm/helpers/bridge-withdraw.d.mts +22 -38
  6. package/esm/helpers/bridge-withdraw.mjs +57 -77
  7. package/esm/helpers/replay-guard.d.mts +29 -12
  8. package/esm/helpers/replay-guard.mjs +68 -22
  9. package/esm/index.d.mts +3 -3
  10. package/esm/index.mjs +3 -3
  11. package/esm/legacy-protocol-sunset.d.mts +35 -21
  12. package/esm/legacy-protocol-sunset.mjs +124 -70
  13. package/esm/legacy-rollup-archive.d.mts +44 -7
  14. package/esm/legacy-rollup-archive.mjs +78 -13
  15. package/esm/library.d.mts +3 -3
  16. package/esm/library.mjs +3 -3
  17. package/esm/pipes/bridge-release-gate.d.mts +3 -2
  18. package/esm/pipes/bridge-release-gate.mjs +90 -35
  19. package/esm/pipes/bridge-reserve-v2-gate.d.mts +2 -0
  20. package/esm/pipes/bridge-reserve-v2-gate.mjs +31 -13
  21. package/esm/pipes/decode-tx.mjs +1 -1
  22. package/esm/pipes/post-execution-invariant-gate.mjs +5 -4
  23. package/esm/pipes/pre-flight-waf.mjs +6 -3
  24. package/esm/pipes/verify-multisig-v2.mjs +1 -1
  25. package/esm/pipes/verify-multisig.mjs +1 -1
  26. package/esm/pipes/verify-tx-size.mjs +8 -2
  27. package/esm/pipes/verify-tx.mjs +1 -1
  28. package/esm/transaction-block.mjs +11 -0
  29. package/lib/bridge-release-keys.cjs +35 -18
  30. package/lib/bridge-release-keys.d.cts +17 -1
  31. package/lib/bridge-reserves.cjs +73 -18
  32. package/lib/bridge-reserves.d.cts +48 -9
  33. package/lib/helpers/bridge-withdraw.cjs +60 -80
  34. package/lib/helpers/bridge-withdraw.d.cts +22 -38
  35. package/lib/helpers/replay-guard.cjs +64 -17
  36. package/lib/helpers/replay-guard.d.cts +29 -12
  37. package/lib/index.cjs +2 -2
  38. package/lib/index.d.cts +3 -3
  39. package/lib/legacy-protocol-sunset.cjs +122 -69
  40. package/lib/legacy-protocol-sunset.d.cts +35 -21
  41. package/lib/legacy-rollup-archive.cjs +82 -14
  42. package/lib/legacy-rollup-archive.d.cts +44 -7
  43. package/lib/library.cjs +1 -2
  44. package/lib/library.d.cts +3 -3
  45. package/lib/pipes/bridge-release-gate.cjs +89 -33
  46. package/lib/pipes/bridge-release-gate.d.cts +3 -2
  47. package/lib/pipes/bridge-reserve-v2-gate.cjs +30 -12
  48. package/lib/pipes/bridge-reserve-v2-gate.d.cts +2 -0
  49. package/lib/pipes/decode-tx.cjs +1 -1
  50. package/lib/pipes/post-execution-invariant-gate.cjs +3 -2
  51. package/lib/pipes/pre-flight-waf.cjs +6 -3
  52. package/lib/pipes/verify-multisig-v2.cjs +1 -1
  53. package/lib/pipes/verify-multisig.cjs +1 -1
  54. package/lib/pipes/verify-tx-size.cjs +8 -2
  55. package/lib/pipes/verify-tx.cjs +1 -1
  56. package/lib/transaction-block.cjs +11 -0
  57. package/package.json +10 -10
@@ -8,7 +8,6 @@ const ErrorCode = {
8
8
  InvalidSunset: "INVALID_LEGACY_PROTOCOL_SUNSET",
9
9
  ForbiddenSunset: "FORBIDDEN_LEGACY_PROTOCOL_SUNSET"
10
10
  };
11
- const DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT = require_legacy_rollup_archive.DEFAULT_ROLLUP_SUNSET_ACTIVATION_HEIGHT;
12
11
  const MAX_LEGACY_MIOTX_PARTICIPANTS = 64;
13
12
  const MAX_LEGACY_MIOTX_TOKENS_PER_ENTRY = 32;
14
13
  const MAX_LEGACY_MIOTX_ASSETS_PER_ENTRY = 64;
@@ -65,7 +64,7 @@ const DEPRECATED_ROLLUP_AND_BRIDGE_TYPE_URLS = Object.freeze([
65
64
  ]);
66
65
  /**
67
66
  * Complete list of all 27 deprecated legacy `V1/V2/V3`, `miotx`, and Rollup write protocols
68
- * frozen into `READ_ONLY_LEGACY_ARCHIVE` mode after `sunsetActivationHeight`.
67
+ * frozen into `READ_ONLY_LEGACY_ARCHIVE` mode once the sunset is switched on.
69
68
  */
70
69
  const DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS = Object.freeze([
71
70
  ...DEPRECATED_MIOTX_AND_TRADE_TYPE_URLS,
@@ -451,35 +450,99 @@ function getLegacyProtocolReplacementSpec(typeUrl) {
451
450
  }
452
451
  /**
453
452
  * Active Write Pipeline Sunset Gate (`assertLegacyProtocolNotSunset`):
454
- * - When `readOnlyArchiveMode === true` or `currentBlockHeight < sunsetActivationHeight`, allows historical read/replay.
455
- * - When `currentBlockHeight >= sunsetActivationHeight`, fails closed (`FORBIDDEN_LEGACY_PROTOCOL_SUNSET`) on all
456
- * 27 deprecated `V1/V2/V3`, `miotx`, and Rollup write protocols with actionable VNext migration guidance.
453
+ * - When `readOnlyArchiveMode === true`, allows historical read/replay.
454
+ * - Otherwise fails closed (`FORBIDDEN_LEGACY_PROTOCOL_SUNSET`) on all 27 deprecated `V1/V2/V3`, `miotx`, and Rollup
455
+ * write protocols of the v1 branch with actionable VNext migration guidance.
456
+ *
457
+ * #1720 (S4b, bridge/docs/deposit-withdraw-v2-unification.md §7.1): `branch` is required (missing throws, whatever the
458
+ * type) and the blockHeight parameters are gone (CHAIN_DESIGN §1 item 2): the sunset is switched on by wiring the guard
459
+ * (or the add-on's `SUNSET_READ_ONLY_ARCHIVE` mode), not by a height.
457
460
  */
458
461
  function assertLegacyProtocolNotSunset(params) {
459
462
  if (!params || typeof params !== "object") throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: params must be an object");
463
+ require_legacy_rollup_archive.assertNoBlockHeightParams(params, "LegacyProtocolSunset");
460
464
  const rawTypeUrl = assertCleanString(params.typeUrl, "typeUrl");
461
- if (!Number.isSafeInteger(params.currentBlockHeight) || params.currentBlockHeight < 0) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: currentBlockHeight must be a non-negative safe integer");
462
- const activationHeight = params.sunsetActivationHeight ?? DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
463
- if (!Number.isSafeInteger(activationHeight) || activationHeight < 1) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: sunsetActivationHeight must be a positive safe integer (>= 1)");
465
+ require_legacy_rollup_archive.assertRollupBranchInfo(params.branch);
464
466
  if (params.readOnlyArchiveMode === true) return;
465
467
  const spec = getLegacyProtocolReplacementSpec(rawTypeUrl);
466
- if (spec && params.currentBlockHeight >= activationHeight) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolSunset: legacy write protocol ${spec.legacyTypeUrl} (${spec.category}${spec.isMiotx ? ", miotx" : ""}) is sunset and read-only at block height ${params.currentBlockHeight} (>= activation height ${activationHeight}). Replacement: ${spec.vnextReplacementTypeUrl} (${spec.migrationGuidance})`);
468
+ if (spec && require_legacy_rollup_archive.isBridgeBranch(spec.legacyTypeUrl, params.branch)) return;
469
+ if (spec) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolSunset: legacy write protocol ${spec.legacyTypeUrl} (${spec.category}${spec.isMiotx ? ", miotx" : ""}) is sunset and read-only. Replacement: ${spec.vnextReplacementTypeUrl} (${spec.migrationGuidance})`);
470
+ }
471
+ /**
472
+ * #1720 (S4b): the rollup-family types. Each names a rollup row (`itx.rollup`), whose version decides the branch: the
473
+ * sunset outcome of `deposit_token_v2` / `withdraw_token_v2` / governance, and whether a record is a legacy rollup
474
+ * record at all. Every other type has no rollup row and so no bridge branch.
475
+ */
476
+ const ROLLUP_FAMILY_TYPE_URLS = new Set([
477
+ ...DEPRECATED_ROLLUP_AND_BRIDGE_TYPE_URLS,
478
+ "fg:t:rollup_state",
479
+ "fg:t:rollup_block"
480
+ ]);
481
+ /** Canonical type URL -> legacy rollup record kind (the archive delegates these to `parseLegacyRollupReadOnlyRecord`). */
482
+ const ROLLUP_RECORD_KIND_MAP = Object.freeze({
483
+ "fg:t:rollup_state": "RollupState",
484
+ "fg:t:rollup_block": "RollupBlock",
485
+ "fg:t:create_rollup_block": "RollupBlock",
486
+ "fg:t:deposit_token": "deposit_token_v2",
487
+ "fg:t:deposit_token_v2": "deposit_token_v2",
488
+ "fg:t:withdraw_token": "withdraw_token_v2",
489
+ "fg:t:withdraw_token_v2": "withdraw_token_v2"
490
+ });
491
+ const hasName = (value) => value !== void 0 && value !== null && String(value).trim() !== "";
492
+ /** The names a record / statement gives for its type (`typeUrl`, `type`, `recordKind`), each normalized. */
493
+ function namedTypeUrls(stmt) {
494
+ return [
495
+ "typeUrl",
496
+ "type",
497
+ "recordKind"
498
+ ].filter((k) => hasName(stmt[k])).map((k) => normalizeProtocolTypeUrl(String(stmt[k])));
499
+ }
500
+ /**
501
+ * #1720 review: a record whose `recordKind` names another type than its `typeUrl` / `type` is refused, like the
502
+ * typeUrl-vs-type conflict. The archive reads `recordKind` first and the add-on `typeUrl` first: a disagreement would
503
+ * let one name pick the branch (or skip it) and the other pick what is archived / compiled. Aliases of one legacy rollup
504
+ * record kind (`RollupBlock` / `create_rollup_block`) agree.
505
+ */
506
+ function assertRecordKindAgrees(stmt, label) {
507
+ if (!hasName(stmt.recordKind)) return;
508
+ const identity = (canonical) => ROLLUP_RECORD_KIND_MAP[canonical] ?? canonical;
509
+ const recordKind = identity(normalizeProtocolTypeUrl(String(stmt.recordKind)));
510
+ for (const k of ["typeUrl", "type"]) {
511
+ if (!hasName(stmt[k])) continue;
512
+ const other = identity(normalizeProtocolTypeUrl(String(stmt[k])));
513
+ if (other !== recordKind) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolSunset: ${label} has conflicting recordKind (${recordKind}) and typeUrl / type (${other})`);
514
+ }
467
515
  }
468
- function validateVNextStatementOrTemplate(stmt, label, currentBlockHeight, sunsetActivationHeight, requireStrictWhitelist, depth = 0) {
516
+ /** The v1 branch of a type that names no rollup row (not a rollup-family type). */
517
+ const NO_ROLLUP_BRANCH = Object.freeze({
518
+ isBridgeV2: false,
519
+ itx: null
520
+ });
521
+ /**
522
+ * #1720 (S4b): the branch of one statement / record for the statement-level helpers. A rollup-family type needs the
523
+ * caller's resolver (missing throws: never a default); any other type has no rollup row and is the v1 branch.
524
+ */
525
+ function resolveStatementBranch(stmt, canonicalTypeUrl, resolveBranch, label) {
526
+ if (![canonicalTypeUrl, ...namedTypeUrls(stmt)].some((name) => ROLLUP_FAMILY_TYPE_URLS.has(name))) return NO_ROLLUP_BRANCH;
527
+ if (typeof resolveBranch !== "function") throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, `LegacyProtocolSunset: ${label} (${canonicalTypeUrl}) needs branch information: pass resolveBranch (rollupBranchOf)`);
528
+ const branch = resolveBranch(stmt);
529
+ require_legacy_rollup_archive.assertRollupBranchInfo(branch);
530
+ return branch;
531
+ }
532
+ function validateVNextStatementOrTemplate(stmt, label, resolveBranch, requireStrictWhitelist, depth = 0) {
469
533
  if (depth > 8) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolSunset: ${label} exceeds maximum nested statementTemplates depth`);
470
534
  if (!stmt || typeof stmt !== "object" || Array.isArray(stmt)) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, `LegacyProtocolSunset: ${label} must be an object`);
471
535
  const hasTypeUrl = stmt.typeUrl !== void 0 && stmt.typeUrl !== null && String(stmt.typeUrl).trim() !== "";
472
536
  const hasType = stmt.type !== void 0 && stmt.type !== null && String(stmt.type).trim() !== "";
473
537
  if (!hasTypeUrl && !hasType) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, `LegacyProtocolSunset: ${label} is missing type or typeUrl`);
538
+ assertRecordKindAgrees(stmt, label);
474
539
  if (hasTypeUrl) assertLegacyProtocolNotSunset({
475
540
  typeUrl: String(stmt.typeUrl),
476
- currentBlockHeight,
477
- sunsetActivationHeight
541
+ branch: resolveStatementBranch(stmt, normalizeProtocolTypeUrl(String(stmt.typeUrl)), resolveBranch, label)
478
542
  });
479
543
  if (hasType) assertLegacyProtocolNotSunset({
480
544
  typeUrl: String(stmt.type),
481
- currentBlockHeight,
482
- sunsetActivationHeight
545
+ branch: resolveStatementBranch(stmt, normalizeProtocolTypeUrl(String(stmt.type)), resolveBranch, label)
483
546
  });
484
547
  const canonicalFromTypeUrl = hasTypeUrl ? normalizeProtocolTypeUrl(String(stmt.typeUrl)) : "";
485
548
  const canonicalFromType = hasType ? normalizeProtocolTypeUrl(String(stmt.type)) : "";
@@ -507,7 +570,7 @@ function validateVNextStatementOrTemplate(stmt, label, currentBlockHeight, sunse
507
570
  ];
508
571
  for (const candidate of candidateTemplateArrays) if (candidate.templates !== void 0 && candidate.templates !== null) {
509
572
  if (!Array.isArray(candidate.templates)) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, `LegacyProtocolSunset: ${candidate.path} must be an array when present`);
510
- for (let tIdx = 0; tIdx < candidate.templates.length; tIdx++) validateVNextStatementOrTemplate(candidate.templates[tIdx], `${candidate.path}[${tIdx}]`, currentBlockHeight, sunsetActivationHeight, requireStrictWhitelist, depth + 1);
573
+ for (let tIdx = 0; tIdx < candidate.templates.length; tIdx++) validateVNextStatementOrTemplate(candidate.templates[tIdx], `${candidate.path}[${tIdx}]`, resolveBranch, requireStrictWhitelist, depth + 1);
511
574
  }
512
575
  }
513
576
  }
@@ -517,12 +580,11 @@ function validateVNextStatementOrTemplate(stmt, label, currentBlockHeight, sunse
517
580
  * or nested `ContractNFT` `statementTemplates`.
518
581
  */
519
582
  function assertTransactionBlockVNextPure(block, options) {
583
+ require_legacy_rollup_archive.assertNoBlockHeightParams(options, "LegacyProtocolSunset");
520
584
  if (!block || typeof block !== "object") throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: block must be an object");
521
585
  if (!Array.isArray(block.statements) || block.statements.length === 0) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: TransactionBlock must contain at least one statement");
522
- const currentBlockHeight = options?.currentBlockHeight ?? DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
523
- const sunsetActivationHeight = options?.sunsetActivationHeight ?? DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
524
586
  const requireStrictWhitelist = options?.requireStrictCanonicalWhitelist ?? true;
525
- for (let i = 0; i < block.statements.length; i++) validateVNextStatementOrTemplate(block.statements[i], `statement[${i}]`, currentBlockHeight, sunsetActivationHeight, requireStrictWhitelist, 0);
587
+ for (let i = 0; i < block.statements.length; i++) validateVNextStatementOrTemplate(block.statements[i], `statement[${i}]`, options?.resolveBranch, requireStrictWhitelist, 0);
526
588
  }
527
589
  function parseTokenList(rawTokens, primaryTokenAddress, primaryValue, label = "tokens") {
528
590
  const entries = /* @__PURE__ */ new Map();
@@ -586,23 +648,14 @@ function parseMiotxParticipantList(rawList, label) {
586
648
  * and Rollup records into a deeply frozen (`Object.freeze`) read-only archive summary (`mode: 'READ_ONLY_LEGACY_ARCHIVE'`).
587
649
  * Enforces strict zero-sum token and asset conservation for historical `transfer_v3` `miotx` records.
588
650
  */
589
- function parseLegacyTxReadOnlyArchiveRecord(rawRecord) {
651
+ function parseLegacyTxReadOnlyArchiveRecord(rawRecord, branch) {
590
652
  if (!rawRecord || typeof rawRecord !== "object" || Array.isArray(rawRecord)) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: rawRecord must be a plain object");
591
653
  assertNoProtoPollutionKeys(rawRecord, "rawRecord");
654
+ assertRecordKindAgrees(rawRecord, "rawRecord");
592
655
  const rawKind = String(rawRecord.recordKind ?? rawRecord.typeUrl ?? rawRecord.type ?? "").trim();
593
656
  if (!rawKind) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolSunset: recordKind or typeUrl is required");
594
657
  const canonicalTypeUrl = normalizeProtocolTypeUrl(rawKind);
595
- const resolvedRollupKind = rawKind === "RollupState" || rawKind === "RollupBlock" ? rawKind : {
596
- "fg:t:rollup_state": "RollupState",
597
- "fg:t:rollup_block": "RollupBlock",
598
- "fg:t:create_rollup_block": "RollupBlock",
599
- "fg:t:deposit_token": "deposit_token_v2",
600
- "fg:t:deposit_token_v1": "deposit_token_v2",
601
- "fg:t:deposit_token_v2": "deposit_token_v2",
602
- "fg:t:withdraw_token": "withdraw_token_v2",
603
- "fg:t:withdraw_token_v1": "withdraw_token_v2",
604
- "fg:t:withdraw_token_v2": "withdraw_token_v2"
605
- }[canonicalTypeUrl];
658
+ const resolvedRollupKind = rawKind === "RollupState" || rawKind === "RollupBlock" ? rawKind : ROLLUP_RECORD_KIND_MAP[canonicalTypeUrl];
606
659
  if (resolvedRollupKind) {
607
660
  const nestedItx = rawRecord.itx && typeof rawRecord.itx === "object" && !Array.isArray(rawRecord.itx) ? rawRecord.itx : {};
608
661
  assertNoProtoPollutionKeys(nestedItx, "itx");
@@ -610,7 +663,7 @@ function parseLegacyTxReadOnlyArchiveRecord(rawRecord) {
610
663
  ...nestedItx,
611
664
  ...rawRecord,
612
665
  recordKind: resolvedRollupKind
613
- });
666
+ }, branch);
614
667
  const canonicalLegacyTypeUrl = rollupSummary.recordKind === "RollupState" || rollupSummary.recordKind === "RollupBlock" ? rollupSummary.recordKind : `fg:t:${rollupSummary.recordKind}`;
615
668
  return Object.freeze({
616
669
  recordKind: rollupSummary.recordKind,
@@ -871,8 +924,8 @@ function parseLegacyTxReadOnlyArchiveRecord(rawRecord) {
871
924
  * containing only versionless atomic statements (`fg:t:transfer`, `fg:t:acquire_asset`) with explicit
872
925
  * `readSet` / `writeSet` footprints and zero-sum conservation.
873
926
  */
874
- function compileLegacyTxToVNextTransactionBlock(rawRecord) {
875
- const summary = parseLegacyTxReadOnlyArchiveRecord(rawRecord);
927
+ function compileLegacyTxToVNextTransactionBlock(rawRecord, branch) {
928
+ const summary = parseLegacyTxReadOnlyArchiveRecord(rawRecord, branch);
876
929
  const blockId = summary.txHash ? `vnext:${summary.txHash}` : `vnext:${summary.recordKind}`;
877
930
  if (summary.recordKind === "transfer_v2") {
878
931
  const inp = summary.inputs[0];
@@ -1173,12 +1226,12 @@ function compileLegacyTxToVNextTransactionBlock(rawRecord) {
1173
1226
  }
1174
1227
  /**
1175
1228
  * Executes a VNext `TransactionBlockInput` after enforcing `assertTransactionBlockVNextPure`
1176
- * (guaranteeing no deprecated `V1/V2/V3`, `miotx`, or Rollup protocol can execute at or after `sunsetActivationHeight`).
1229
+ * (guaranteeing no deprecated `V1/V2/V3`, `miotx`, or Rollup protocol of the v1 branch can execute).
1177
1230
  */
1178
1231
  async function executeVNextTransactionBlock(block, options) {
1232
+ require_legacy_rollup_archive.assertNoBlockHeightParams(options, "LegacyProtocolSunset");
1179
1233
  assertTransactionBlockVNextPure(block, {
1180
- currentBlockHeight: options.currentBlockHeight,
1181
- sunsetActivationHeight: options.sunsetActivationHeight,
1234
+ resolveBranch: options.resolveBranch,
1182
1235
  requireStrictCanonicalWhitelist: true
1183
1236
  });
1184
1237
  return require_transaction_block.executeTransactionBlock(block, {
@@ -1206,14 +1259,12 @@ var LegacyProtocolCompatibilityAddon = class {
1206
1259
  this.totalPassthroughVNextTxs = 0;
1207
1260
  this.rejectedAfterSunsetCount = 0;
1208
1261
  this.translatedCounts = /* @__PURE__ */ new Map();
1262
+ require_legacy_rollup_archive.assertNoBlockHeightParams(options, "LegacyProtocolCompatibilityAddon");
1209
1263
  const mode = options?.mode ?? "ADDON_TRANSLATE_AND_EXECUTE";
1210
1264
  if (mode !== "ADDON_TRANSLATE_AND_EXECUTE" && mode !== "SUNSET_READ_ONLY_ARCHIVE") throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, `LegacyProtocolCompatibilityAddon: invalid mode ${String(mode)}`);
1211
1265
  const targetRemovalRelease = assertCleanString(options?.targetRemovalRelease ?? "v2.0-major", "targetRemovalRelease", 64);
1212
- const sunsetActivationHeight = options?.sunsetActivationHeight ?? DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
1213
- if (!Number.isSafeInteger(sunsetActivationHeight) || sunsetActivationHeight < 1) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolCompatibilityAddon: sunsetActivationHeight must be a positive safe integer (>= 1)");
1214
1266
  this.mode = mode;
1215
1267
  this.targetRemovalRelease = targetRemovalRelease;
1216
- this.sunsetActivationHeight = sunsetActivationHeight;
1217
1268
  }
1218
1269
  getMode() {
1219
1270
  return this.mode;
@@ -1261,7 +1312,7 @@ var LegacyProtocolCompatibilityAddon = class {
1261
1312
  }
1262
1313
  return value;
1263
1314
  }
1264
- translateStatementTemplateRecursively(stmt, warnings, currentBlockHeight, depth = 0) {
1315
+ translateStatementTemplateRecursively(stmt, warnings, resolveBranch, depth = 0) {
1265
1316
  if (depth > 8) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, "LegacyProtocolCompatibilityAddon: maximum nested statementTemplates depth exceeded");
1266
1317
  if (!stmt || typeof stmt !== "object" || Array.isArray(stmt)) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolCompatibilityAddon: statement must be an object");
1267
1318
  assertNoProtoPollutionKeys(stmt, "statement");
@@ -1274,20 +1325,19 @@ var LegacyProtocolCompatibilityAddon = class {
1274
1325
  const canonicalInputUrl = normUrl || normType;
1275
1326
  let resolvedTypeUrl = canonicalInputUrl;
1276
1327
  if (isDomainCoupledProtocolAlias(canonicalInputUrl)) {
1277
- if (this.mode === "SUNSET_READ_ONLY_ARCHIVE" && currentBlockHeight >= this.sunsetActivationHeight) {
1328
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") {
1278
1329
  this.rejectedAfterSunsetCount += 1;
1279
- throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolCompatibilityAddon: domain-coupled protocol alias ${canonicalInputUrl} is disabled in SUNSET_READ_ONLY_ARCHIVE mode at height ${currentBlockHeight}`);
1330
+ throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolCompatibilityAddon: domain-coupled protocol alias ${canonicalInputUrl} is disabled in SUNSET_READ_ONLY_ARCHIVE mode`);
1280
1331
  }
1281
1332
  const mapped = resolveDomainAgnosticVNextProtocol(canonicalInputUrl);
1282
1333
  this.recordTranslation(warnings, canonicalInputUrl, mapped, "DOMAIN_COUPLED_ALIAS", `Use domain-agnostic L1 primitive ${mapped}`);
1283
1334
  resolvedTypeUrl = mapped;
1284
1335
  } else if (isDeprecatedLegacyWriteProtocol(canonicalInputUrl)) {
1285
- if (this.mode === "SUNSET_READ_ONLY_ARCHIVE" && currentBlockHeight >= this.sunsetActivationHeight) {
1336
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") {
1286
1337
  this.rejectedAfterSunsetCount += 1;
1287
1338
  assertLegacyProtocolNotSunset({
1288
1339
  typeUrl: canonicalInputUrl,
1289
- currentBlockHeight,
1290
- sunsetActivationHeight: this.sunsetActivationHeight
1340
+ branch: resolveStatementBranch(stmt, canonicalInputUrl, resolveBranch, "statement")
1291
1341
  });
1292
1342
  }
1293
1343
  const spec = getLegacyProtocolReplacementSpec(canonicalInputUrl);
@@ -1297,12 +1347,12 @@ var LegacyProtocolCompatibilityAddon = class {
1297
1347
  }
1298
1348
  const rawItx = stmt.itx && typeof stmt.itx === "object" && !Array.isArray(stmt.itx) ? { ...stmt.itx } : {};
1299
1349
  assertNoProtoPollutionKeys(rawItx, "stmt.itx");
1300
- if (Array.isArray(rawItx.statementTemplates)) rawItx.statementTemplates = rawItx.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, currentBlockHeight, depth + 1));
1350
+ if (Array.isArray(rawItx.statementTemplates)) rawItx.statementTemplates = rawItx.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, resolveBranch, depth + 1));
1301
1351
  if (rawItx.data?.value && Array.isArray(rawItx.data.value.statementTemplates)) rawItx.data = {
1302
1352
  ...rawItx.data,
1303
1353
  value: {
1304
1354
  ...rawItx.data.value,
1305
- statementTemplates: rawItx.data.value.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, currentBlockHeight, depth + 1))
1355
+ statementTemplates: rawItx.data.value.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, resolveBranch, depth + 1))
1306
1356
  }
1307
1357
  };
1308
1358
  if (rawItx.contractAsset?.data?.value && Array.isArray(rawItx.contractAsset.data.value.statementTemplates)) rawItx.contractAsset = {
@@ -1311,7 +1361,7 @@ var LegacyProtocolCompatibilityAddon = class {
1311
1361
  ...rawItx.contractAsset.data,
1312
1362
  value: {
1313
1363
  ...rawItx.contractAsset.data.value,
1314
- statementTemplates: rawItx.contractAsset.data.value.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, currentBlockHeight, depth + 1))
1364
+ statementTemplates: rawItx.contractAsset.data.value.statementTemplates.map((tpl) => this.translateStatementTemplateRecursively(tpl, warnings, resolveBranch, depth + 1))
1315
1365
  }
1316
1366
  }
1317
1367
  };
@@ -1332,17 +1382,16 @@ var LegacyProtocolCompatibilityAddon = class {
1332
1382
  translateToVNextTransactionBlock(txOrBlock, options) {
1333
1383
  if (!txOrBlock || typeof txOrBlock !== "object" || Array.isArray(txOrBlock)) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolCompatibilityAddon: txOrBlock must be a plain object");
1334
1384
  assertNoProtoPollutionKeys(txOrBlock, "txOrBlock");
1335
- const currentBlockHeight = options?.currentBlockHeight ?? DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
1336
- if (!Number.isSafeInteger(currentBlockHeight) || currentBlockHeight < 0) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolCompatibilityAddon: currentBlockHeight must be a non-negative safe integer");
1385
+ require_legacy_rollup_archive.assertNoBlockHeightParams(options, "LegacyProtocolCompatibilityAddon");
1386
+ const resolveBranch = options?.resolveBranch;
1337
1387
  const warnings = [];
1338
1388
  if ("statements" in txOrBlock && Array.isArray(txOrBlock.statements)) {
1339
1389
  const inputBlock = txOrBlock;
1340
1390
  if (inputBlock.statements.length === 0) throw new _ocap_util_lib_error.CustomError(ErrorCode.InvalidSunset, "LegacyProtocolCompatibilityAddon: TransactionBlock must contain at least one statement");
1341
- if (this.mode === "SUNSET_READ_ONLY_ARCHIVE" && currentBlockHeight >= this.sunsetActivationHeight) {
1391
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") {
1342
1392
  try {
1343
1393
  assertTransactionBlockVNextPure(inputBlock, {
1344
- currentBlockHeight,
1345
- sunsetActivationHeight: this.sunsetActivationHeight,
1394
+ resolveBranch,
1346
1395
  requireStrictCanonicalWhitelist: true
1347
1396
  });
1348
1397
  } catch (err) {
@@ -1369,6 +1418,7 @@ var LegacyProtocolCompatibilityAddon = class {
1369
1418
  const normType$1 = hasType$1 ? normalizeProtocolTypeUrl(String(rawStmt.type)) : "";
1370
1419
  if (hasTypeUrl$1 && hasType$1 && normUrl$1 !== normType$1) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolCompatibilityAddon: statement[${i}] has conflicting typeUrl (${normUrl$1}) and type (${normType$1})`);
1371
1420
  const stmtTypeUrl = normUrl$1 || normType$1;
1421
+ assertRecordKindAgrees(rawStmt, `statement[${i}]`);
1372
1422
  const baseOffset = expandedStatements.length;
1373
1423
  if (isDeprecatedLegacyWriteProtocol(stmtTypeUrl)) {
1374
1424
  const spec = getLegacyProtocolReplacementSpec(stmtTypeUrl);
@@ -1376,7 +1426,7 @@ var LegacyProtocolCompatibilityAddon = class {
1376
1426
  ...rawStmt,
1377
1427
  from: rawStmt.from ?? inputBlock.from,
1378
1428
  typeUrl: stmtTypeUrl
1379
- });
1429
+ }, resolveStatementBranch(rawStmt, stmtTypeUrl, resolveBranch, `statement[${i}]`));
1380
1430
  this.recordTranslation(warnings, spec.legacyTypeUrl, spec.vnextReplacementTypeUrl, spec.category, spec.migrationGuidance);
1381
1431
  for (const subStmt of compiledSub.transactionBlock.statements) {
1382
1432
  const shiftedItx = baseOffset > 0 ? this.remapStepReferencesInValue(subStmt.itx, (localIdx) => baseOffset + localIdx) : subStmt.itx;
@@ -1388,7 +1438,7 @@ var LegacyProtocolCompatibilityAddon = class {
1388
1438
  }
1389
1439
  origStepLastExpandedIndex.push(expandedStatements.length - 1);
1390
1440
  } else {
1391
- const translatedStmt = this.translateStatementTemplateRecursively(rawStmt, warnings, currentBlockHeight, 0);
1441
+ const translatedStmt = this.translateStatementTemplateRecursively(rawStmt, warnings, resolveBranch, 0);
1392
1442
  const remappedItx = this.remapStepReferencesInValue(translatedStmt.itx, (origIdx) => origIdx < origStepLastExpandedIndex.length ? origStepLastExpandedIndex[origIdx] : origIdx);
1393
1443
  expandedStatements.push({
1394
1444
  ...translatedStmt,
@@ -1409,8 +1459,7 @@ var LegacyProtocolCompatibilityAddon = class {
1409
1459
  writeSet: footprint$1.writeSet
1410
1460
  };
1411
1461
  assertTransactionBlockVNextPure(finalBlock$1, {
1412
- currentBlockHeight,
1413
- sunsetActivationHeight: this.sunsetActivationHeight,
1462
+ resolveBranch,
1414
1463
  requireStrictCanonicalWhitelist: true
1415
1464
  });
1416
1465
  const wasTranslated$1 = warnings.length > 0;
@@ -1431,16 +1480,22 @@ var LegacyProtocolCompatibilityAddon = class {
1431
1480
  const normUrl = hasTypeUrl ? normalizeProtocolTypeUrl(String(rawRecord.typeUrl)) : "";
1432
1481
  const normType = hasType ? normalizeProtocolTypeUrl(String(rawRecord.type)) : "";
1433
1482
  if (hasTypeUrl && hasType && normUrl !== normType) {
1434
- if (this.mode === "SUNSET_READ_ONLY_ARCHIVE" && currentBlockHeight >= this.sunsetActivationHeight) this.rejectedAfterSunsetCount += 1;
1483
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") this.rejectedAfterSunsetCount += 1;
1435
1484
  throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolCompatibilityAddon: transaction has conflicting typeUrl (${normUrl}) and type (${normType})`);
1436
1485
  }
1486
+ try {
1487
+ assertRecordKindAgrees(rawRecord, "transaction");
1488
+ } catch (err) {
1489
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") this.rejectedAfterSunsetCount += 1;
1490
+ throw err;
1491
+ }
1437
1492
  const rawKind = String(rawRecord.typeUrl ?? rawRecord.type ?? rawRecord.recordKind ?? "").trim();
1438
1493
  const canonicalUrl = normUrl || normType || normalizeProtocolTypeUrl(rawKind);
1439
- if (this.mode === "SUNSET_READ_ONLY_ARCHIVE" && currentBlockHeight >= this.sunsetActivationHeight) try {
1494
+ const recordBranch = resolveStatementBranch(rawRecord, canonicalUrl, resolveBranch, "transaction");
1495
+ if (this.mode === "SUNSET_READ_ONLY_ARCHIVE") try {
1440
1496
  assertLegacyProtocolNotSunset({
1441
1497
  typeUrl: canonicalUrl,
1442
- currentBlockHeight,
1443
- sunsetActivationHeight: this.sunsetActivationHeight
1498
+ branch: recordBranch
1444
1499
  });
1445
1500
  if (isDomainCoupledProtocolAlias(canonicalUrl)) throw new _ocap_util_lib_error.CustomError(ErrorCode.ForbiddenSunset, `LegacyProtocolCompatibilityAddon: domain-coupled protocol alias ${canonicalUrl} is disabled in SUNSET_READ_ONLY_ARCHIVE mode`);
1446
1501
  } catch (err) {
@@ -1449,7 +1504,7 @@ var LegacyProtocolCompatibilityAddon = class {
1449
1504
  }
1450
1505
  if (isDeprecatedLegacyWriteProtocol(canonicalUrl)) {
1451
1506
  const spec = getLegacyProtocolReplacementSpec(canonicalUrl);
1452
- const compiled = compileLegacyTxToVNextTransactionBlock(rawRecord);
1507
+ const compiled = compileLegacyTxToVNextTransactionBlock(rawRecord, recordBranch);
1453
1508
  this.recordTranslation(warnings, spec.legacyTypeUrl, spec.vnextReplacementTypeUrl, spec.category, spec.migrationGuidance);
1454
1509
  this.totalTranslatedTxs += 1;
1455
1510
  return Object.freeze({
@@ -1467,7 +1522,7 @@ var LegacyProtocolCompatibilityAddon = class {
1467
1522
  from: fromDid,
1468
1523
  delegator: typeof rawRecord.delegator === "string" ? rawRecord.delegator : void 0,
1469
1524
  itx: rawRecord.itx && typeof rawRecord.itx === "object" && !Array.isArray(rawRecord.itx) ? rawRecord.itx : rawRecord
1470
- }, warnings, currentBlockHeight, 0);
1525
+ }, warnings, resolveBranch, 0);
1471
1526
  const rawBlock = {
1472
1527
  id: typeof rawRecord.txHash === "string" ? `vnext:${rawRecord.txHash}` : void 0,
1473
1528
  from: fromDid,
@@ -1481,8 +1536,7 @@ var LegacyProtocolCompatibilityAddon = class {
1481
1536
  writeSet: footprint.writeSet
1482
1537
  };
1483
1538
  assertTransactionBlockVNextPure(finalBlock, {
1484
- currentBlockHeight,
1485
- sunsetActivationHeight: this.sunsetActivationHeight,
1539
+ resolveBranch,
1486
1540
  requireStrictCanonicalWhitelist: true
1487
1541
  });
1488
1542
  const wasTranslated = warnings.length > 0;
@@ -1502,13 +1556,13 @@ var LegacyProtocolCompatibilityAddon = class {
1502
1556
  * 2. Executes the resulting pure VNext `TransactionBlockInput` on the VNext `OverlayStateDB` engine.
1503
1557
  */
1504
1558
  async executeWithCompatibilityAddon(txOrBlock, options) {
1505
- const translationResult = this.translateToVNextTransactionBlock(txOrBlock, { currentBlockHeight: options.currentBlockHeight });
1559
+ require_legacy_rollup_archive.assertNoBlockHeightParams(options, "LegacyProtocolCompatibilityAddon");
1560
+ const translationResult = this.translateToVNextTransactionBlock(txOrBlock, { resolveBranch: options.resolveBranch });
1506
1561
  return {
1507
1562
  executionResult: await executeVNextTransactionBlock(translationResult.transactionBlock, {
1508
1563
  statedb: options.statedb,
1509
1564
  executeStatement: options.executeStatement,
1510
- currentBlockHeight: options.currentBlockHeight,
1511
- sunsetActivationHeight: this.sunsetActivationHeight,
1565
+ resolveBranch: options.resolveBranch,
1512
1566
  dryRun: options.dryRun
1513
1567
  }),
1514
1568
  translationResult
@@ -1517,7 +1571,6 @@ var LegacyProtocolCompatibilityAddon = class {
1517
1571
  };
1518
1572
 
1519
1573
  //#endregion
1520
- exports.DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT = DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT;
1521
1574
  exports.DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS = DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS;
1522
1575
  exports.DEPRECATED_MIOTX_AND_TRADE_TYPE_URLS = DEPRECATED_MIOTX_AND_TRADE_TYPE_URLS;
1523
1576
  exports.DEPRECATED_MIOTX_PROTOCOL_TYPE_URLS = DEPRECATED_MIOTX_PROTOCOL_TYPE_URLS;
@@ -1,8 +1,7 @@
1
- import { LegacyRollupReadOnlySummary } from "./legacy-rollup-archive.cjs";
1
+ import { LegacyRollupReadOnlySummary, RollupBranchInfo, RollupBranchResolver } from "./legacy-rollup-archive.cjs";
2
2
  import { StatementExecutor, TransactionBlockInput, TransactionBlockResult } from "./transaction-block.cjs";
3
3
 
4
4
  //#region src/legacy-protocol-sunset.d.ts
5
- declare const DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT = 1;
6
5
  declare const MAX_LEGACY_MIOTX_PARTICIPANTS = 64;
7
6
  declare const MAX_LEGACY_MIOTX_TOKENS_PER_ENTRY = 32;
8
7
  declare const MAX_LEGACY_MIOTX_ASSETS_PER_ENTRY = 64;
@@ -23,7 +22,7 @@ declare const DEPRECATED_VERSIONED_ASSET_TYPE_URLS: readonly ["fg:t:acquire_asse
23
22
  declare const DEPRECATED_ROLLUP_AND_BRIDGE_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", "fg:t:close_rollup", "fg:t:migrate_rollup", "fg:t:deposit_token", "fg:t:deposit_token_v2", "fg:t:withdraw_token", "fg:t:withdraw_token_v2", "fg:t:revoke_withdraw"];
24
23
  /**
25
24
  * Complete list of all 27 deprecated legacy `V1/V2/V3`, `miotx`, and Rollup write protocols
26
- * frozen into `READ_ONLY_LEGACY_ARCHIVE` mode after `sunsetActivationHeight`.
25
+ * frozen into `READ_ONLY_LEGACY_ARCHIVE` mode once the sunset is switched on.
27
26
  */
28
27
  declare const DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS: readonly ["fg:t:transfer_v2", "fg:t:transfer_v3", "fg:t:exchange", "fg:t:exchange_v2", "fg:t:setup_swap", "fg:t:retrieve_swap", "fg:t:revoke_swap", "fg:t:acquire_asset_v2", "fg:t:acquire_asset_v3", "fg:t:mint_asset_v2", "fg:t:update_asset_v2", "fg:t:create_factory_v2", "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", "fg:t:close_rollup", "fg:t:migrate_rollup", "fg:t:deposit_token", "fg:t:deposit_token_v2", "fg:t:withdraw_token", "fg:t:withdraw_token_v2", "fg:t:revoke_withdraw"];
29
28
  /**
@@ -93,14 +92,23 @@ declare function resolveDomainAgnosticVNextProtocol(typeUrl: string): VNextCanon
93
92
  declare function getLegacyProtocolReplacementSpec(typeUrl: string): LegacyProtocolReplacementSpec | null;
94
93
  /**
95
94
  * Active Write Pipeline Sunset Gate (`assertLegacyProtocolNotSunset`):
96
- * - When `readOnlyArchiveMode === true` or `currentBlockHeight < sunsetActivationHeight`, allows historical read/replay.
97
- * - When `currentBlockHeight >= sunsetActivationHeight`, fails closed (`FORBIDDEN_LEGACY_PROTOCOL_SUNSET`) on all
98
- * 27 deprecated `V1/V2/V3`, `miotx`, and Rollup write protocols with actionable VNext migration guidance.
95
+ * - When `readOnlyArchiveMode === true`, allows historical read/replay.
96
+ * - Otherwise fails closed (`FORBIDDEN_LEGACY_PROTOCOL_SUNSET`) on all 27 deprecated `V1/V2/V3`, `miotx`, and Rollup
97
+ * write protocols of the v1 branch with actionable VNext migration guidance.
98
+ *
99
+ * #1720 (S4b, bridge/docs/deposit-withdraw-v2-unification.md §7.1): `branch` is required (missing throws, whatever the
100
+ * type) and the blockHeight parameters are gone (CHAIN_DESIGN §1 item 2): the sunset is switched on by wiring the guard
101
+ * (or the add-on's `SUNSET_READ_ONLY_ARCHIVE` mode), not by a height.
99
102
  */
100
103
  declare function assertLegacyProtocolNotSunset(params: {
101
104
  typeUrl: string;
102
- currentBlockHeight: number;
103
- sunsetActivationHeight?: number;
105
+ /**
106
+ * #1692 (bridge/docs/deposit-withdraw-v2-unification.md §7.1): the branch of a `deposit_token_v2` / `withdraw_token_v2`
107
+ * / rollup governance tx (`rollupBranchOf(row itx.rollup names, itx)`). The bridge branch (a deposit with kind 1/2/3
108
+ * or a withdraw on a v2 bridge, bridge governance) reuses the type names, not the retired rollup mechanism: it is
109
+ * never sunset. A tx that names no rollup passes the v1 branch `{ isBridgeV2: false }`.
110
+ */
111
+ branch: RollupBranchInfo;
104
112
  readOnlyArchiveMode?: boolean;
105
113
  }): void;
106
114
  /**
@@ -109,8 +117,8 @@ declare function assertLegacyProtocolNotSunset(params: {
109
117
  * or nested `ContractNFT` `statementTemplates`.
110
118
  */
111
119
  declare function assertTransactionBlockVNextPure(block: TransactionBlockInput, options?: {
112
- currentBlockHeight?: number;
113
- sunsetActivationHeight?: number;
120
+ /** #1720 (S4b): the branch of a rollup-family statement; required when the block has one (missing throws) */
121
+ resolveBranch?: RollupBranchResolver;
114
122
  requireStrictCanonicalWhitelist?: boolean;
115
123
  }): void;
116
124
  interface LegacyTokenAmountEntry {
@@ -145,26 +153,28 @@ interface LegacyTxReadOnlyArchiveSummary {
145
153
  * and Rollup records into a deeply frozen (`Object.freeze`) read-only archive summary (`mode: 'READ_ONLY_LEGACY_ARCHIVE'`).
146
154
  * Enforces strict zero-sum token and asset conservation for historical `transfer_v3` `miotx` records.
147
155
  */
148
- declare function parseLegacyTxReadOnlyArchiveRecord(rawRecord: Record<string, unknown>): LegacyTxReadOnlyArchiveSummary;
156
+ declare function parseLegacyTxReadOnlyArchiveRecord(rawRecord: Record<string, unknown>, /** #1720 (S4b): the branch of the row a rollup record belongs to (`rollupBranchOf`); required for rollup records */
157
+ branch?: RollupBranchInfo): LegacyTxReadOnlyArchiveSummary;
149
158
  /**
150
159
  * Deterministically compiles any legacy `transfer_v2`, `transfer_v3` (`miotx`), `exchange_v2` (`miotx`),
151
160
  * or `acquire_asset_v2` / `acquire_asset_v3` record into a 100% VNext-pure `TransactionBlockInput`
152
161
  * containing only versionless atomic statements (`fg:t:transfer`, `fg:t:acquire_asset`) with explicit
153
162
  * `readSet` / `writeSet` footprints and zero-sum conservation.
154
163
  */
155
- declare function compileLegacyTxToVNextTransactionBlock(rawRecord: Record<string, unknown>): {
164
+ declare function compileLegacyTxToVNextTransactionBlock(rawRecord: Record<string, unknown>, /** #1720 (S4b): forwarded to `parseLegacyTxReadOnlyArchiveRecord`; required for rollup records */
165
+ branch?: RollupBranchInfo): {
156
166
  archiveSummary: LegacyTxReadOnlyArchiveSummary;
157
167
  transactionBlock: TransactionBlockInput;
158
168
  };
159
169
  /**
160
170
  * Executes a VNext `TransactionBlockInput` after enforcing `assertTransactionBlockVNextPure`
161
- * (guaranteeing no deprecated `V1/V2/V3`, `miotx`, or Rollup protocol can execute at or after `sunsetActivationHeight`).
171
+ * (guaranteeing no deprecated `V1/V2/V3`, `miotx`, or Rollup protocol of the v1 branch can execute).
162
172
  */
163
173
  declare function executeVNextTransactionBlock(block: TransactionBlockInput, options: {
164
174
  statedb: Record<string, any>;
165
175
  executeStatement: StatementExecutor;
166
- currentBlockHeight?: number;
167
- sunsetActivationHeight?: number;
176
+ /** #1720 (S4b): see `assertTransactionBlockVNextPure` */
177
+ resolveBranch?: RollupBranchResolver;
168
178
  dryRun?: boolean;
169
179
  }): Promise<TransactionBlockResult>;
170
180
  type CompatibilityAddonMode = 'ADDON_TRANSLATE_AND_EXECUTE' | 'SUNSET_READ_ONLY_ARCHIVE';
@@ -206,7 +216,6 @@ interface CompatibilityAddonMetrics {
206
216
  declare class LegacyProtocolCompatibilityAddon {
207
217
  private mode;
208
218
  private readonly targetRemovalRelease;
209
- private readonly sunsetActivationHeight;
210
219
  private totalTranslatedTxs;
211
220
  private totalPassthroughVNextTxs;
212
221
  private rejectedAfterSunsetCount;
@@ -214,7 +223,6 @@ declare class LegacyProtocolCompatibilityAddon {
214
223
  constructor(options?: {
215
224
  mode?: CompatibilityAddonMode;
216
225
  targetRemovalRelease?: string;
217
- sunsetActivationHeight?: number;
218
226
  });
219
227
  getMode(): CompatibilityAddonMode;
220
228
  setMode(mode: CompatibilityAddonMode): void;
@@ -228,8 +236,13 @@ declare class LegacyProtocolCompatibilityAddon {
228
236
  * domain-coupled statement (`contract_nft`, `give_karma`, `claim_karma`, `evm_bridge_settlement`),
229
237
  * or `TransactionBlockInput` into a 100% pure, domain-agnostic VNext `TransactionBlockInput`.
230
238
  */
231
- translateToVNextTransactionBlock(txOrBlock: Record<string, unknown> | TransactionBlockInput, options?: {
232
- currentBlockHeight?: number;
239
+ translateToVNextTransactionBlock(txOrBlock: Record<string, unknown> | TransactionBlockInput,
240
+ /**
241
+ * #1720 (S4b): `resolveBranch` gives the branch of each rollup-family statement / record (`rollupBranchOf` of the
242
+ * row `itx.rollup` names); required when there is one (missing throws). No blockHeight: the mode is the switch.
243
+ */
244
+ options?: {
245
+ resolveBranch?: RollupBranchResolver;
233
246
  }): CompatibilityTranslationResult;
234
247
  /**
235
248
  * End-to-end execution through the Compatibility Add-On Layer:
@@ -240,7 +253,8 @@ declare class LegacyProtocolCompatibilityAddon {
240
253
  executeWithCompatibilityAddon(txOrBlock: Record<string, unknown> | TransactionBlockInput, options: {
241
254
  statedb: Record<string, any>;
242
255
  executeStatement: StatementExecutor;
243
- currentBlockHeight?: number;
256
+ /** #1720 (S4b): see `translateToVNextTransactionBlock` */
257
+ resolveBranch?: RollupBranchResolver;
244
258
  dryRun?: boolean;
245
259
  }): Promise<{
246
260
  executionResult: TransactionBlockResult;
@@ -248,4 +262,4 @@ declare class LegacyProtocolCompatibilityAddon {
248
262
  }>;
249
263
  }
250
264
  //#endregion
251
- export { CompatibilityAddonMetrics, CompatibilityAddonMode, CompatibilityDeprecationWarning, CompatibilityTranslationResult, DEFAULT_LEGACY_PROTOCOL_SUNSET_HEIGHT, DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS, DEPRECATED_MIOTX_AND_TRADE_TYPE_URLS, DEPRECATED_MIOTX_PROTOCOL_TYPE_URLS, DEPRECATED_ROLLUP_AND_BRIDGE_TYPE_URLS, DEPRECATED_VERSIONED_ASSET_TYPE_URLS, DOMAIN_COUPLED_PROTOCOL_ALIAS_MAP, DeprecatedLegacyProtocolTypeUrl, DomainCoupledProtocolAliasTypeUrl, LegacyMiotxParticipantEntry, LegacyProtocolCompatibilityAddon, LegacyProtocolReplacementSpec, LegacyProtocolSunsetCategory, LegacyTokenAmountEntry, LegacyTxReadOnlyArchiveSummary, MAX_LEGACY_MIOTX_ASSETS_PER_ENTRY, MAX_LEGACY_MIOTX_PARTICIPANTS, MAX_LEGACY_MIOTX_TOKENS_PER_ENTRY, VNEXT_CANONICAL_WRITE_PROTOCOL_TYPE_URLS, VNextCanonicalWriteProtocolTypeUrl, assertLegacyProtocolNotSunset, assertTransactionBlockVNextPure, compileLegacyTxToVNextTransactionBlock, executeVNextTransactionBlock, getLegacyProtocolReplacementSpec, isDeprecatedLegacyWriteProtocol, isDomainCoupledProtocolAlias, isMiotxLegacyProtocol, isVNextCanonicalWriteProtocol, normalizeProtocolTypeUrl, parseLegacyTxReadOnlyArchiveRecord, resolveDomainAgnosticVNextProtocol };
265
+ export { CompatibilityAddonMetrics, CompatibilityAddonMode, CompatibilityDeprecationWarning, CompatibilityTranslationResult, DEPRECATED_LEGACY_PROTOCOL_TYPE_URLS, DEPRECATED_MIOTX_AND_TRADE_TYPE_URLS, DEPRECATED_MIOTX_PROTOCOL_TYPE_URLS, DEPRECATED_ROLLUP_AND_BRIDGE_TYPE_URLS, DEPRECATED_VERSIONED_ASSET_TYPE_URLS, DOMAIN_COUPLED_PROTOCOL_ALIAS_MAP, DeprecatedLegacyProtocolTypeUrl, DomainCoupledProtocolAliasTypeUrl, LegacyMiotxParticipantEntry, LegacyProtocolCompatibilityAddon, LegacyProtocolReplacementSpec, LegacyProtocolSunsetCategory, LegacyTokenAmountEntry, LegacyTxReadOnlyArchiveSummary, MAX_LEGACY_MIOTX_ASSETS_PER_ENTRY, MAX_LEGACY_MIOTX_PARTICIPANTS, MAX_LEGACY_MIOTX_TOKENS_PER_ENTRY, VNEXT_CANONICAL_WRITE_PROTOCOL_TYPE_URLS, VNextCanonicalWriteProtocolTypeUrl, assertLegacyProtocolNotSunset, assertTransactionBlockVNextPure, compileLegacyTxToVNextTransactionBlock, executeVNextTransactionBlock, getLegacyProtocolReplacementSpec, isDeprecatedLegacyWriteProtocol, isDomainCoupledProtocolAlias, isMiotxLegacyProtocol, isVNextCanonicalWriteProtocol, normalizeProtocolTypeUrl, parseLegacyTxReadOnlyArchiveRecord, resolveDomainAgnosticVNextProtocol };