feat(portal): opt-in PORTAL_ALLOW_MISSING_ACCESS_LIST for RPCs that omit accessList

The fork's hardened RPC-path accessList-required check (in standardizeTransactions,
added by every wiring patch) crashes any app whose RPC/proxy omits the spec-required
accessList on typed-envelope txs. In practice this hits SQD's own zkSync RPC proxy,
which returns type-0x2 txs with no accessList key at all (verified 11/11 across 50
blocks) — a fork-introduced regression vs stock ponder on a supported chain.

The guard is right in general (it prevents fabricating an empty/NULL access list over
a real one, #27/#32), so keep it as the default. Add an opt-in knob (default OFF,
matching the PORTAL_* boolean convention):
  - unset  → unchanged loud RpcProviderError, whose meta now NAMES the knob;
  - set    → the missing value flows through and stores as an honest NULL (as the
             Portal path already does for column-less datasets, #110/#111).

Read once per standardizeTransactions call (hoisted above the tx loop — cheap, and
toggleable per call in tests). Applied to all 5 tracked wiring patches (0.15.17,
0.16.6-0.16.9), regenerated per PUBLISHING.md. Adds 3 tests to realtime-standardize
covering: default-throws-and-names-knob, knob-passes-through-to-NULL on 0x1/2/3/4,
and knob-preserves-a-present-list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011h8zdhxsC8A2bcFqZRcjeB

Author: abernatskiy

portal/realtime-standardize.test.ts

@@ -117,3 +117,86 @@ test('type-0x2 with accessList ([] and non-empty) passes through unchanged and e
     encodeTransaction({ transaction: outFull[0]!, chainId: 1 }).accessList,
   ).toBe(JSON.stringify(list));
 });
+
+// ─────────────────────── (f) opt-in: PORTAL_ALLOW_MISSING_ACCESS_LIST ───────────────────────
+// The default guard is right for a compliant provider, but SQD's own zkSync RPC proxy returns
+// EIP-1559 (0x2) txs with NO `accessList` key at all — so on that documented-supported endpoint
+// the guard crashes the whole app. `PORTAL_ALLOW_MISSING_ACCESS_LIST` (default OFF) lets an
+// operator who knows the omission is legitimate proceed and store the honest NULL, exactly as the
+// Portal path already does for datasets that lack the column entirely (#27, #110/#111).
+
+// Run `body` with the knob forced to `value`, restoring the prior env afterwards (no cross-test leak).
+const withKnob = (value: string | undefined, body: () => void): void => {
+  const prev = process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST;
+  if (value === undefined) {
+    delete process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST;
+  } else {
+    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST = value;
+  }
+
+  try {
+    body();
+  } finally {
+    if (prev === undefined) {
+      delete process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST;
+    } else {
+      process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST = prev;
+    }
+  }
+};
+
+// The loud default error must NAME the escape hatch — an operator hitting the zkSync crash needs to
+// be told the exact knob, not left to grep the source. The guidance rides on `RpcProviderError.meta`
+// (surfaced by the logger, like every other error here), not the terse message line.
+test('default (knob unset) → missing accessList still throws, and the guidance names the knob', () => {
+  withKnob(undefined, () => {
+    const t = tx({ type: '0x2' });
+    expect(() => standardize(t)).toThrowError(/transaction\.accessList/);
+
+    let meta: string[] = [];
+    try {
+      standardize(t);
+    } catch (err) {
+      meta = (err as { meta?: string[] }).meta ?? [];
+    }
+
+    expect(meta.join(' ')).toMatch(/PORTAL_ALLOW_MISSING_ACCESS_LIST/);
+  });
+});
+
+// With the knob set, EVERY typed envelope missing accessList flows through instead of throwing, and
+// the absent value stays `undefined` → encodeTransaction maps it to a NULL (honest absence, not []).
+test('knob set → missing accessList on 0x1/0x2/0x3/0x4 passes through, encodes to NULL', () => {
+  withKnob('1', () => {
+    for (const type of ['0x1', '0x2', '0x3', '0x4']) {
+      const t = tx({ type });
+      expect(() => standardize(t)).not.toThrow();
+      const out = standardize(t);
+      expect(out[0]!.accessList).toBeUndefined();
+      expect(
+        encodeTransaction({ transaction: out[0]!, chainId: 1 }).accessList,
+      ).toBeNull();
+    }
+  });
+});
+
+// The knob is an escape hatch for ABSENT lists only — it must never fabricate or drop a REAL one:
+// a present access list still round-trips unchanged when the knob is on.
+test('knob set → a present accessList is still preserved unchanged', () => {
+  withKnob('1', () => {
+    const list = [
+      {
+        address: '0x000000000000000000000000000000000000dead',
+        storageKeys: [
+          '0x0000000000000000000000000000000000000000000000000000000000000001',
+        ],
+      },
+    ];
+    const t = tx({ type: '0x2', accessList: list });
+    const out = standardize(t);
+    expect(out[0]!.accessList).toEqual(list);
+    expect(
+      encodeTransaction({ transaction: out[0]!, chainId: 1 }).accessList,
+    ).toBe(JSON.stringify(list));
+  });
+});

portal/wiring/0.15.17.patch

@@ -41,7 +41,7 @@ index acea95b..c502c66 100644
    pollingInterval: number;
    finalityBlockCount: number;
 diff --git a/packages/core/src/rpc/actions.ts b/packages/core/src/rpc/actions.ts
-index 32ba7a8..0dabd74 100644
+index 32ba7a8..c443cb6 100644
 --- a/packages/core/src/rpc/actions.ts
 +++ b/packages/core/src/rpc/actions.ts
 @@ -1,6 +1,8 @@
@@ -192,7 +192,22 @@ index 32ba7a8..0dabd74 100644
  /**
   * Helper function for "eth_getTransactionReceipt" request.
   */
-@@ -893,6 +1017,33 @@ export const standardizeTransactions = (
+@@ -787,6 +911,14 @@ export const standardizeTransactions = (
+     { method: "eth_getBlockByNumber" | "eth_getBlockByHash" }
+   >,
+ ): SyncTransaction[] => {
++  // PORTAL_ALLOW_MISSING_ACCESS_LIST — opt-in to consuming from a non-standard RPC provider (e.g.
++  // SQD's zkSync proxy) that omits the spec-required `accessList` on typed-envelope txs. Default
++  // OFF: a missing accessList is a loud RpcProviderError (below). When set, the missing value is
++  // allowed through and stored as an honest NULL. Read once per call — cheap, hoisted above the
++  // loop — so ops can flip it via env without a rebuild, and tests can toggle it per call. (issue #27)
++  const allowMissingAccessList = Boolean(
++    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST,
++  );
+   const transactionIds = new Set<Hex>();
+ 
+   for (const transaction of transactions) {
+@@ -893,6 +1025,38 @@ export const standardizeTransactions = (
        transaction.gas = "0x0";
      }
 
@@ -203,9 +218,12 @@ index 32ba7a8..0dabd74 100644
 +    // defaulting to `[]`, which would fabricate an empty list over a real one. Legacy (0x0), OP
 +    // deposit (0x7e), and unknown/system envelopes (e.g. Arbitrum internals) carry no access list
 +    // and are left untouched. An explicit `accessList: null` is treated the same as an omitted key
-+    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud.
++    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud —
++    // UNLESS the operator opts in via PORTAL_ALLOW_MISSING_ACCESS_LIST (see above), in which case
++    // the missing value flows through to that honest NULL by design.
 +    const txType: string | undefined = transaction.type;
 +    if (
++      !allowMissingAccessList &&
 +      (txType === "0x1" ||
 +        txType === "0x2" ||
 +        txType === "0x3" ||
@@ -216,7 +234,9 @@ index 32ba7a8..0dabd74 100644
 +        `Invalid RPC response: 'transaction.accessList' is a required property on type ${txType} transactions`,
 +      );
 +      error.meta = [
-+        "Please report this error to the RPC operator.",
++        "This RPC provider omits the spec-required 'accessList' on typed transactions. If that is " +
++          "expected for this endpoint (e.g. SQD's zkSync proxy), set PORTAL_ALLOW_MISSING_ACCESS_LIST=1 " +
++          "to store the missing access list as NULL and continue; otherwise report this to the RPC operator.",
 +        requestText(request),
 +      ];
 +      error.stack = undefined;

portal/wiring/0.16.6.patch

@@ -41,7 +41,7 @@ index acea95b..c502c66 100644
    pollingInterval: number;
    finalityBlockCount: number;
 diff --git a/packages/core/src/rpc/actions.ts b/packages/core/src/rpc/actions.ts
-index 64bbcbe..bb3d6ad 100644
+index 64bbcbe..25c301c 100644
 --- a/packages/core/src/rpc/actions.ts
 +++ b/packages/core/src/rpc/actions.ts
 @@ -1,6 +1,8 @@
@@ -192,7 +192,22 @@ index 64bbcbe..bb3d6ad 100644
  /**
   * Helper function for "eth_getTransactionReceipt" request.
   */
-@@ -893,6 +1017,33 @@ export const standardizeTransactions = (
+@@ -787,6 +911,14 @@ export const standardizeTransactions = (
+     { method: "eth_getBlockByNumber" | "eth_getBlockByHash" }
+   >,
+ ): SyncTransaction[] => {
++  // PORTAL_ALLOW_MISSING_ACCESS_LIST — opt-in to consuming from a non-standard RPC provider (e.g.
++  // SQD's zkSync proxy) that omits the spec-required `accessList` on typed-envelope txs. Default
++  // OFF: a missing accessList is a loud RpcProviderError (below). When set, the missing value is
++  // allowed through and stored as an honest NULL. Read once per call — cheap, hoisted above the
++  // loop — so ops can flip it via env without a rebuild, and tests can toggle it per call. (issue #27)
++  const allowMissingAccessList = Boolean(
++    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST,
++  );
+   const transactionIds = new Set<Hex>();
+ 
+   for (const transaction of transactions) {
+@@ -893,6 +1025,38 @@ export const standardizeTransactions = (
        transaction.gas = "0x0";
      }
 
@@ -203,9 +218,12 @@ index 64bbcbe..bb3d6ad 100644
 +    // defaulting to `[]`, which would fabricate an empty list over a real one. Legacy (0x0), OP
 +    // deposit (0x7e), and unknown/system envelopes (e.g. Arbitrum internals) carry no access list
 +    // and are left untouched. An explicit `accessList: null` is treated the same as an omitted key
-+    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud.
++    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud —
++    // UNLESS the operator opts in via PORTAL_ALLOW_MISSING_ACCESS_LIST (see above), in which case
++    // the missing value flows through to that honest NULL by design.
 +    const txType: string | undefined = transaction.type;
 +    if (
++      !allowMissingAccessList &&
 +      (txType === "0x1" ||
 +        txType === "0x2" ||
 +        txType === "0x3" ||
@@ -216,7 +234,9 @@ index 64bbcbe..bb3d6ad 100644
 +        `Invalid RPC response: 'transaction.accessList' is a required property on type ${txType} transactions`,
 +      );
 +      error.meta = [
-+        "Please report this error to the RPC operator.",
++        "This RPC provider omits the spec-required 'accessList' on typed transactions. If that is " +
++          "expected for this endpoint (e.g. SQD's zkSync proxy), set PORTAL_ALLOW_MISSING_ACCESS_LIST=1 " +
++          "to store the missing access list as NULL and continue; otherwise report this to the RPC operator.",
 +        requestText(request),
 +      ];
 +      error.stack = undefined;

portal/wiring/0.16.7.patch

@@ -41,7 +41,7 @@ index acea95b..c502c66 100644
    pollingInterval: number;
    finalityBlockCount: number;
 diff --git a/packages/core/src/rpc/actions.ts b/packages/core/src/rpc/actions.ts
-index 64bbcbe..bb3d6ad 100644
+index 64bbcbe..25c301c 100644
 --- a/packages/core/src/rpc/actions.ts
 +++ b/packages/core/src/rpc/actions.ts
 @@ -1,6 +1,8 @@
@@ -192,7 +192,22 @@ index 64bbcbe..bb3d6ad 100644
  /**
   * Helper function for "eth_getTransactionReceipt" request.
   */
-@@ -893,6 +1017,33 @@ export const standardizeTransactions = (
+@@ -787,6 +911,14 @@ export const standardizeTransactions = (
+     { method: "eth_getBlockByNumber" | "eth_getBlockByHash" }
+   >,
+ ): SyncTransaction[] => {
++  // PORTAL_ALLOW_MISSING_ACCESS_LIST — opt-in to consuming from a non-standard RPC provider (e.g.
++  // SQD's zkSync proxy) that omits the spec-required `accessList` on typed-envelope txs. Default
++  // OFF: a missing accessList is a loud RpcProviderError (below). When set, the missing value is
++  // allowed through and stored as an honest NULL. Read once per call — cheap, hoisted above the
++  // loop — so ops can flip it via env without a rebuild, and tests can toggle it per call. (issue #27)
++  const allowMissingAccessList = Boolean(
++    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST,
++  );
+   const transactionIds = new Set<Hex>();
+ 
+   for (const transaction of transactions) {
+@@ -893,6 +1025,38 @@ export const standardizeTransactions = (
        transaction.gas = "0x0";
      }
 
@@ -203,9 +218,12 @@ index 64bbcbe..bb3d6ad 100644
 +    // defaulting to `[]`, which would fabricate an empty list over a real one. Legacy (0x0), OP
 +    // deposit (0x7e), and unknown/system envelopes (e.g. Arbitrum internals) carry no access list
 +    // and are left untouched. An explicit `accessList: null` is treated the same as an omitted key
-+    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud.
++    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud —
++    // UNLESS the operator opts in via PORTAL_ALLOW_MISSING_ACCESS_LIST (see above), in which case
++    // the missing value flows through to that honest NULL by design.
 +    const txType: string | undefined = transaction.type;
 +    if (
++      !allowMissingAccessList &&
 +      (txType === "0x1" ||
 +        txType === "0x2" ||
 +        txType === "0x3" ||
@@ -216,7 +234,9 @@ index 64bbcbe..bb3d6ad 100644
 +        `Invalid RPC response: 'transaction.accessList' is a required property on type ${txType} transactions`,
 +      );
 +      error.meta = [
-+        "Please report this error to the RPC operator.",
++        "This RPC provider omits the spec-required 'accessList' on typed transactions. If that is " +
++          "expected for this endpoint (e.g. SQD's zkSync proxy), set PORTAL_ALLOW_MISSING_ACCESS_LIST=1 " +
++          "to store the missing access list as NULL and continue; otherwise report this to the RPC operator.",
 +        requestText(request),
 +      ];
 +      error.stack = undefined;

portal/wiring/0.16.8.patch

@@ -41,7 +41,7 @@ index acea95b..c502c66 100644
    pollingInterval: number;
    finalityBlockCount: number;
 diff --git a/packages/core/src/rpc/actions.ts b/packages/core/src/rpc/actions.ts
-index 64bbcbe..bb3d6ad 100644
+index 64bbcbe..25c301c 100644
 --- a/packages/core/src/rpc/actions.ts
 +++ b/packages/core/src/rpc/actions.ts
 @@ -1,6 +1,8 @@
@@ -192,7 +192,22 @@ index 64bbcbe..bb3d6ad 100644
  /**
   * Helper function for "eth_getTransactionReceipt" request.
   */
-@@ -893,6 +1017,33 @@ export const standardizeTransactions = (
+@@ -787,6 +911,14 @@ export const standardizeTransactions = (
+     { method: "eth_getBlockByNumber" | "eth_getBlockByHash" }
+   >,
+ ): SyncTransaction[] => {
++  // PORTAL_ALLOW_MISSING_ACCESS_LIST — opt-in to consuming from a non-standard RPC provider (e.g.
++  // SQD's zkSync proxy) that omits the spec-required `accessList` on typed-envelope txs. Default
++  // OFF: a missing accessList is a loud RpcProviderError (below). When set, the missing value is
++  // allowed through and stored as an honest NULL. Read once per call — cheap, hoisted above the
++  // loop — so ops can flip it via env without a rebuild, and tests can toggle it per call. (issue #27)
++  const allowMissingAccessList = Boolean(
++    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST,
++  );
+   const transactionIds = new Set<Hex>();
+ 
+   for (const transaction of transactions) {
+@@ -893,6 +1025,38 @@ export const standardizeTransactions = (
        transaction.gas = "0x0";
      }
 
@@ -203,9 +218,12 @@ index 64bbcbe..bb3d6ad 100644
 +    // defaulting to `[]`, which would fabricate an empty list over a real one. Legacy (0x0), OP
 +    // deposit (0x7e), and unknown/system envelopes (e.g. Arbitrum internals) carry no access list
 +    // and are left untouched. An explicit `accessList: null` is treated the same as an omitted key
-+    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud.
++    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud —
++    // UNLESS the operator opts in via PORTAL_ALLOW_MISSING_ACCESS_LIST (see above), in which case
++    // the missing value flows through to that honest NULL by design.
 +    const txType: string | undefined = transaction.type;
 +    if (
++      !allowMissingAccessList &&
 +      (txType === "0x1" ||
 +        txType === "0x2" ||
 +        txType === "0x3" ||
@@ -216,7 +234,9 @@ index 64bbcbe..bb3d6ad 100644
 +        `Invalid RPC response: 'transaction.accessList' is a required property on type ${txType} transactions`,
 +      );
 +      error.meta = [
-+        "Please report this error to the RPC operator.",
++        "This RPC provider omits the spec-required 'accessList' on typed transactions. If that is " +
++          "expected for this endpoint (e.g. SQD's zkSync proxy), set PORTAL_ALLOW_MISSING_ACCESS_LIST=1 " +
++          "to store the missing access list as NULL and continue; otherwise report this to the RPC operator.",
 +        requestText(request),
 +      ];
 +      error.stack = undefined;

portal/wiring/0.16.9.patch

@@ -41,7 +41,7 @@ index acea95b..c502c66 100644
    pollingInterval: number;
    finalityBlockCount: number;
 diff --git a/packages/core/src/rpc/actions.ts b/packages/core/src/rpc/actions.ts
-index 64bbcbe..bb3d6ad 100644
+index 64bbcbe..25c301c 100644
 --- a/packages/core/src/rpc/actions.ts
 +++ b/packages/core/src/rpc/actions.ts
 @@ -1,6 +1,8 @@
@@ -192,7 +192,22 @@ index 64bbcbe..bb3d6ad 100644
  /**
   * Helper function for "eth_getTransactionReceipt" request.
   */
-@@ -893,6 +1017,33 @@ export const standardizeTransactions = (
+@@ -787,6 +911,14 @@ export const standardizeTransactions = (
+     { method: "eth_getBlockByNumber" | "eth_getBlockByHash" }
+   >,
+ ): SyncTransaction[] => {
++  // PORTAL_ALLOW_MISSING_ACCESS_LIST — opt-in to consuming from a non-standard RPC provider (e.g.
++  // SQD's zkSync proxy) that omits the spec-required `accessList` on typed-envelope txs. Default
++  // OFF: a missing accessList is a loud RpcProviderError (below). When set, the missing value is
++  // allowed through and stored as an honest NULL. Read once per call — cheap, hoisted above the
++  // loop — so ops can flip it via env without a rebuild, and tests can toggle it per call. (issue #27)
++  const allowMissingAccessList = Boolean(
++    process.env.PORTAL_ALLOW_MISSING_ACCESS_LIST,
++  );
+   const transactionIds = new Set<Hex>();
+ 
+   for (const transaction of transactions) {
+@@ -893,6 +1025,38 @@ export const standardizeTransactions = (
        transaction.gas = "0x0";
      }
 
@@ -203,9 +218,12 @@ index 64bbcbe..bb3d6ad 100644
 +    // defaulting to `[]`, which would fabricate an empty list over a real one. Legacy (0x0), OP
 +    // deposit (0x7e), and unknown/system envelopes (e.g. Arbitrum internals) carry no access list
 +    // and are left untouched. An explicit `accessList: null` is treated the same as an omitted key
-+    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud.
++    // (`== null`): encode.ts maps both to the same permanent NULL, so both must fail loud —
++    // UNLESS the operator opts in via PORTAL_ALLOW_MISSING_ACCESS_LIST (see above), in which case
++    // the missing value flows through to that honest NULL by design.
 +    const txType: string | undefined = transaction.type;
 +    if (
++      !allowMissingAccessList &&
 +      (txType === "0x1" ||
 +        txType === "0x2" ||
 +        txType === "0x3" ||
@@ -216,7 +234,9 @@ index 64bbcbe..bb3d6ad 100644
 +        `Invalid RPC response: 'transaction.accessList' is a required property on type ${txType} transactions`,
 +      );
 +      error.meta = [
-+        "Please report this error to the RPC operator.",
++        "This RPC provider omits the spec-required 'accessList' on typed transactions. If that is " +
++          "expected for this endpoint (e.g. SQD's zkSync proxy), set PORTAL_ALLOW_MISSING_ACCESS_LIST=1 " +
++          "to store the missing access list as NULL and continue; otherwise report this to the RPC operator.",
 +        requestText(request),
 +      ];
 +      error.stack = undefined;