feat: bindings to getExpectedWithdrawals and native tweaks

- add bindings to it
- don't heap allocate for `withdrawals_results` since it is capped at
  `preset.MAX_WITHDRAWALS_PER_PAYLOAD == 16`. This is about max ~800 bytes
  on mainnet preset
- add assertions to assert the above

Author: spiral-ladder

bench/state_transition/process_block.zig

@@ -79,7 +79,6 @@ fn ProcessWithdrawalsBench(comptime fork: ForkSeq) type {
             const state = cloned.state.castToFork(fork);
             state_transition.getExpectedWithdrawals(
                 fork,
-                allocator,
                 cloned.epoch_cache,
                 state,
                 &withdrawals_result,
@@ -347,7 +346,6 @@ fn ProcessBlockSegmentedBench(comptime fork: ForkSeq) type {
                 defer withdrawal_balances.deinit();
                 state_transition.getExpectedWithdrawals(
                     fork,
-                    allocator,
                     epoch_cache,
                     state,
                     &withdrawals_result,

bindings/napi/BeaconStateView.zig

@@ -1284,8 +1284,56 @@ pub fn getSyncCommitteesWitness(_: *const BeaconStateView) !js.Value {
     return throwNotImpl(js.Value, "getSyncCommitteesWitness not implemented");
 }
 
-pub fn getExpectedWithdrawals(_: *const BeaconStateView) !js.Value {
-    return throwNotImpl(js.Value, "getExpectedWithdrawals not implemented");
+/// Compute expected withdrawals for the next payload (capella+).
+/// Returns: { expectedWithdrawals: Withdrawal[], processedPartialWithdrawalsCount, processedValidatorSweepCount,
+///           processedBuilderWithdrawalsCount, processedBuildersSweepCount }
+/// The latter two are Gloas-only — always 0 here since Zig STF doesn't process Gloas yet.
+pub fn getExpectedWithdrawals(self: *const BeaconStateView) !js.Value {
+    const env = js.env();
+    const cached_state = try self.requireState();
+    const fork_seq = cached_state.state.forkSeq();
+
+    // We also check this within the native fn itself but this lets us avoid allocating an `AutoHashMap` early.
+    if (fork_seq.lt(.capella)) {
+        return throwNullAs(js.Value, "INVALID_FORK", "getExpectedWithdrawals only supported capella+");
+    }
+
+    var withdrawals_buf: [preset.MAX_WITHDRAWALS_PER_PAYLOAD]ct.capella.Withdrawal.Type = undefined;
+    var withdrawals_result = st.WithdrawalsResult{
+        .withdrawals = ct.capella.Withdrawals.Type.initBuffer(&withdrawals_buf),
+    };
+
+    var withdrawal_balances = std.AutoHashMap(ct.primitive.ValidatorIndex.Type, usize).init(allocator);
+    defer withdrawal_balances.deinit();
+
+    switch (fork_seq) {
+        inline .capella, .deneb, .electra, .fulu => |f| {
+            try st.getExpectedWithdrawals(
+                f,
+                cached_state.epoch_cache,
+                cached_state.state.castToFork(f),
+                &withdrawals_result,
+                &withdrawal_balances,
+            );
+        },
+        else => unreachable,
+    }
+
+    const obj = try env.createObject();
+
+    const withdrawals_arr = try env.createArray();
+    for (withdrawals_result.withdrawals.items, 0..) |*w, i| {
+        const w_value = try sszValueToNapiValue(env, ct.capella.Withdrawal, w);
+        try withdrawals_arr.setElement(@intCast(i), w_value);
+    }
+    try obj.setNamedProperty("expectedWithdrawals", withdrawals_arr);
+    try obj.setNamedProperty("processedPartialWithdrawalsCount", try env.createUint32(@intCast(withdrawals_result.processed_partial_withdrawals_count)));
+    try obj.setNamedProperty("processedValidatorSweepCount", try env.createUint32(@intCast(withdrawals_result.sampled_validators)));
+    // TODO(bing): Implement when we support Gloas.
+    try obj.setNamedProperty("processedBuilderWithdrawalsCount", try env.createUint32(0));
+    try obj.setNamedProperty("processedBuildersSweepCount", try env.createUint32(0));
+
+    return js_types.wrap(js.Value, obj);
 }
 
 fn requireState(self: *const BeaconStateView) !*CachedBeaconState {

bindings/src/index.d.ts

@@ -271,6 +271,25 @@ declare class BeaconStateView {
   // biome-ignore lint/suspicious/noExplicitAny: stub
   getExpectedWithdrawals(): any;
   getSingleProof(gindex: bigint): Uint8Array[];
+  // getSyncCommitteesWitness(): any;
+  /**
+   * Compute expected withdrawals for the next payload (capella+).
+   *
+   * processedBuilderWithdrawalsCount is withdrawals coming from builder payment since gloas (EIP-7732)
+   * processedPartialWithdrawalsCount is withdrawals coming from EL since electra (EIP-7002)
+   * processedBuildersSweepCount is withdrawals from builder sweep since gloas (EIP-7732)
+   * processedValidatorSweepCount is withdrawals coming from validator sweep
+
+   * TODO(bing): `processedBuilderWithdrawalsCount` and `processedBuildersSweepCount` are Gloas-only
+   * and always 0 here since Zig STF doesn't process Gloas yet.
+   */
+  getExpectedWithdrawals(): {
+    expectedWithdrawals: {index: number; validatorIndex: number; address: Uint8Array; amount: number}[];
+    processedBuilderWithdrawalsCount: number;
+    processedPartialWithdrawalsCount: number;
+    processedBuildersSweepCount: number;
+    processedValidatorSweepCount: number;
+  };
   // createMultiProof(descriptor: Uint8Array): CompactMultiProof;
 
   computeUnrealizedCheckpoints(): {

src/state_transition/block/process_block.zig

@@ -71,7 +71,6 @@ pub fn processBlock(
 
                 try getExpectedWithdrawals(
                     fork,
-                    allocator,
                     epoch_cache,
                     state,
                     &withdrawals_result,

src/state_transition/block/process_withdrawals.zig

@@ -82,18 +82,20 @@ pub fn processWithdrawals(
     }
 }
 
-// Consumer should deinit WithdrawalsResult with .deinit() after use
+/// Called by the block proposer to find a list of withdrawals to include in the block.
+///
+/// This list is assumed to be bounded by `preset.MAX_WITHDRAWALS_PER_PAYLOAD`.
+///
+/// Caller should deinit `withdrawal_balances` with .deinit() after use.
 pub fn getExpectedWithdrawals(
     comptime fork: ForkSeq,
-    allocator: Allocator,
     epoch_cache: *const EpochCache,
     state: *BeaconState(fork),
     withdrawals_result: *WithdrawalsResult,
     withdrawal_balances: *std.AutoHashMap(ValidatorIndex, usize),
 ) !void {
-    if (comptime fork.lt(.capella)) {
-        return error.InvalidForkSequence;
-    }
+    std.debug.assert(withdrawals_result.withdrawals.capacity == preset.MAX_WITHDRAWALS_PER_PAYLOAD);
+    if (comptime fork.lt(.capella)) return error.InvalidForkSequence;
 
     const epoch = epoch_cache.epoch;
     var withdrawal_index = try state.nextWithdrawalIndex();
@@ -134,7 +136,7 @@ pub fn getExpectedWithdrawals(
                 const withdrawable_balance = if (balance_over_min_activation_balance < withdrawal.amount) balance_over_min_activation_balance else withdrawal.amount;
                 var execution_address: ExecutionAddress = undefined;
                 @memcpy(&execution_address, validator.withdrawal_credentials[12..]);
-                try withdrawals_result.withdrawals.append(allocator, .{
+                withdrawals_result.withdrawals.appendAssumeCapacity(.{
                     .index = withdrawal_index,
                     .validator_index = withdrawal.validator_index,
                     .address = execution_address,
@@ -179,7 +181,7 @@ pub fn getExpectedWithdrawals(
         if (withdrawable_epoch <= epoch) {
             var execution_address: ExecutionAddress = undefined;
             @memcpy(&execution_address, withdrawal_credentials[12..]);
-            try withdrawals_result.withdrawals.append(allocator, .{
+            withdrawals_result.withdrawals.appendAssumeCapacity(.{
                 .index = withdrawal_index,
                 .validator_index = validator_index,
                 .address = execution_address,
@@ -195,7 +197,7 @@ pub fn getExpectedWithdrawals(
             const partial_amount = balance - effective_balance;
             var execution_address: ExecutionAddress = undefined;
             @memcpy(&execution_address, withdrawal_credentials[12..]);
-            try withdrawals_result.withdrawals.append(allocator, .{
+            withdrawals_result.withdrawals.appendAssumeCapacity(.{
                 .index = withdrawal_index,
                 .validator_index = validator_index,
                 .address = execution_address,
@@ -242,7 +244,6 @@ test "process withdrawals - sanity" {
 
     try getExpectedWithdrawals(
         .electra,
-        allocator,
         test_state.cached_state.epoch_cache,
         test_state.cached_state.state.castToFork(.electra),
         &withdrawals_result,

test/spec/runner/operations.zig

@@ -279,7 +279,6 @@ pub fn TestCase(comptime fork: ForkSeq, comptime operation: Operation) type {
 
                     try state_transition.getExpectedWithdrawals(
                         fork,
-                        allocator,
                         epoch_cache,
                         state,
                         &withdrawals_result,