Add toJSON() method for BAL (#4246)

* New toJSON() method for BAL

* Spelling fix

Author: holgerd77

packages/util/src/bal.ts

@@ -454,6 +454,69 @@ export class BlockLevelAccessList {
    * Per EIP-7928: "if the account had a positive balance pre-transaction,
    * the balance change to zero MUST be recorded."
    */
+  /**
+   * Converts the internal representation to the JSON format (BALJSONBlockAccessList).
+   * Inverse of createBlockLevelAccessListFromJSON().
+   */
+  public toJSON(): BALJSONBlockAccessList {
+    const result: BALJSONBlockAccessList = []
+
+    for (const [address, access] of Object.entries(this.accesses)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .filter(([addr]) => addr !== systemAddress)) {
+      const storageChanges: BALJSONSlotChanges[] = (
+        Object.entries(access.storageChanges) as [BALStorageKeyHex, BALRawStorageChange[]][]
+      )
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([slot, changes]) => ({
+          slot,
+          slotChanges: changes
+            .sort((a, b) => a[0] - b[0])
+            .map(([index, value]) => ({
+              blockAccessIndex: indexToHex(index),
+              postValue: padToEvenHex(bytesToHex(value)),
+            })),
+        }))
+
+      const storageReads: BALStorageKeyHex[] = Array.from(access.storageReads).sort((a, b) =>
+        Number(
+          (a === '0x' ? 0n : hexToBigInt(a as `0x${string}`)) -
+            (b === '0x' ? 0n : hexToBigInt(b as `0x${string}`)),
+        ),
+      )
+
+      const balanceChanges: BALJSONBalanceChange[] = Array.from(access.balanceChanges.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([index, balance]) => ({
+          blockAccessIndex: indexToHex(index),
+          postBalance: balance,
+        }))
+
+      const nonceChanges: BALJSONNonceChange[] = Array.from(access.nonceChanges.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([index, nonce]) => ({
+          blockAccessIndex: indexToHex(index),
+          postNonce: nonce,
+        }))
+
+      const codeChanges: BALJSONCodeChange[] = access.codeChanges.map(([index, code]) => ({
+        blockAccessIndex: indexToHex(index),
+        newCode: bytesToHex(code),
+      }))
+
+      result.push({
+        address: address as BALAddressHex,
+        nonceChanges,
+        balanceChanges,
+        codeChanges,
+        storageChanges,
+        storageReads,
+      })
+    }
+
+    return result
+  }
+
   public cleanupSelfdestructed(addresses: Array<BALAddressHex>): void {
     for (const address of addresses) {
       const access = this.accesses[address]
@@ -641,5 +704,9 @@ function normalizeStorageKeyHex(hex: PrefixedHexString): BALStorageKeyHex {
   return `0x${padToEven(stripped)}` as BALStorageKeyHex
 }
 
+function indexToHex(index: BALAccessIndexNumber): BALAccessIndexHex {
+  return padToEvenHex(`0x${index.toString(16)}`) as BALAccessIndexHex
+}
+
 // Address to ignore
 const systemAddress = '0xfffffffffffffffffffffffffffffffffffffffe'

packages/util/test/bal.spec.ts

@@ -5,8 +5,9 @@ import {
   BlockLevelAccessList,
   createBlockLevelAccessList,
   createBlockLevelAccessListFromJSON,
+  createBlockLevelAccessListFromRLP,
 } from '../src/bal.ts'
-import { bytesToHex } from '../src/bytes.ts'
+import { bytesToHex, hexToBytes } from '../src/bytes.ts'
 import { KECCAK256_RLP_ARRAY_S } from '../src/constants.ts'
 import type { PrefixedHexString } from '../src/types.ts'
 import bal_all_transaction_types from './testdata/bal/bal_all_transaction_types.json' with {
@@ -124,4 +125,60 @@ describe('JSON', () => {
     assert.deepEqual(bytesToHex(bal.serialize()), balAllTransactionTypesRLP)
     assert.deepEqual(bytesToHex(bal.hash()), balAllTransactionTypesHash)
   })
+
+  it('toJSON() should produce correct JSON from Accesses data', () => {
+    // bal_simple and bal_all_transaction_types use even-padded hex,
+    // so toJSON() output should match the JSON test data directly.
+    let bal = new BlockLevelAccessList(balSimple)
+    assert.deepEqual(bal.toJSON(), bal_simple as BALJSONBlockAccessList)
+
+    bal = new BlockLevelAccessList(balAllTransactionTypes)
+    assert.deepEqual(bal.toJSON(), bal_all_transaction_types as BALJSONBlockAccessList)
+  })
+
+  it('toJSON() roundtrip: JSON -> internal -> toJSON()', () => {
+    // For already-normalized JSON (even-padded hex), toJSON() output matches input.
+    let bal = createBlockLevelAccessListFromJSON(bal_simple as BALJSONBlockAccessList)
+    assert.deepEqual(bal.toJSON(), bal_simple as BALJSONBlockAccessList)
+
+    bal = createBlockLevelAccessListFromJSON(bal_all_transaction_types as BALJSONBlockAccessList)
+    assert.deepEqual(bal.toJSON(), bal_all_transaction_types as BALJSONBlockAccessList)
+
+    // bal_empty_block_no_coinbase uses un-normalized hex (e.g. "0x0" vs "0x00"),
+    // so direct JSON comparison won't match. Verify semantic roundtrip instead:
+    // JSON -> internal -> toJSON() -> internal -> RLP/hash must still match.
+    bal = createBlockLevelAccessListFromJSON(bal_empty_block_no_coinbase as BALJSONBlockAccessList)
+    const roundtripJSON = bal.toJSON()
+    const bal2 = createBlockLevelAccessListFromJSON(roundtripJSON)
+    assert.deepEqual(bal2.accesses, balEmptyBlockNoCoinbase)
+    assert.deepEqual(bytesToHex(bal2.serialize()), balEmptyBlockNoCoinbaseRLP)
+    assert.deepEqual(bytesToHex(bal2.hash()), balEmptyBlockNoCoinbaseHash)
+  })
+})
+
+describe('RLP', () => {
+  it('serialize() should produce correct RLP output', () => {
+    let bal = new BlockLevelAccessList(balSimple)
+    assert.deepEqual(bytesToHex(bal.serialize()), balSimpleRLP)
+
+    bal = new BlockLevelAccessList(balEmptyBlockNoCoinbase)
+    assert.deepEqual(bytesToHex(bal.serialize()), balEmptyBlockNoCoinbaseRLP)
+
+    bal = new BlockLevelAccessList(balAllTransactionTypes)
+    assert.deepEqual(bytesToHex(bal.serialize()), balAllTransactionTypesRLP)
+  })
+
+  it('serialize() roundtrip: RLP -> internal -> serialize()', () => {
+    let bal = createBlockLevelAccessListFromRLP(hexToBytes(balSimpleRLP))
+    assert.deepEqual(bytesToHex(bal.serialize()), balSimpleRLP)
+    assert.deepEqual(bytesToHex(bal.hash()), balSimpleHash)
+
+    bal = createBlockLevelAccessListFromRLP(hexToBytes(balEmptyBlockNoCoinbaseRLP))
+    assert.deepEqual(bytesToHex(bal.serialize()), balEmptyBlockNoCoinbaseRLP)
+    assert.deepEqual(bytesToHex(bal.hash()), balEmptyBlockNoCoinbaseHash)
+
+    bal = createBlockLevelAccessListFromRLP(hexToBytes(balAllTransactionTypesRLP))
+    assert.deepEqual(bytesToHex(bal.serialize()), balAllTransactionTypesRLP)
+    assert.deepEqual(bytesToHex(bal.hash()), balAllTransactionTypesHash)
+  })
 })