feat(sync): multi-block pre_confirmed chain, poller + storage

clients/feeder/feeder.go

@@ -58,6 +58,11 @@
 		blockIdentifier string,
 		knownTransactionCount uint64,
 	) (starknet.PreConfirmedUpdate, error)
+	PreConfirmedBlockLatest(
+		ctx context.Context,
+		blockIdentifier string,
+		knownTransactionCount uint64,
+	) (starknet.PreConfirmedUpdate, uint64, error)
 	PublicKey(ctx context.Context) (*felt.Felt, error)
 	Signature(ctx context.Context, blockID string) (*starknet.Signature, error)
 	StateUpdate(ctx context.Context, blockID string) (*starknet.StateUpdate, error)
@@ -382,6 +387,45 @@
 	blockIdentifier string,
 	knownTransactionCount uint64,
 ) (starknet.PreConfirmedUpdate, error) {
+	preConfirmedEnvelope, err := c.fetchPreConfirmedUpdate(
+		ctx,
+		blockNumber,
+		blockIdentifier,
+		knownTransactionCount,
+	)
+	if err != nil {
+		return nil, err
+	}
+	return preConfirmedEnvelope.Update, nil
+}
+
+// PreConfirmedBlockLatest fetches the highest pre_confirmed block the server
+// currently exposes. The response carries its block_number so the caller can
+// discover the pre_confirmed tip without tracking  the height itself.
+// Pass an empty identifier and zero txCount for a full reply.
+func (c *Client) PreConfirmedBlockLatest(
+	ctx context.Context,
+	blockIdentifier string,
+	knownTransactionCount uint64,
+) (starknet.PreConfirmedUpdate, uint64, error) {
+	preConfirmedEnvelope, err := c.fetchPreConfirmedUpdate(
+		ctx,
+		"latest",
+		blockIdentifier,
+		knownTransactionCount,
+	)
+	if err != nil {
+		return nil, 0, err
+	}
+	return preConfirmedEnvelope.Update, preConfirmedEnvelope.BlockNumber, nil
+}
+
+func (c *Client) fetchPreConfirmedUpdate(
+	ctx context.Context,
+	blockNumber string,
+	blockIdentifier string,
+	knownTransactionCount uint64,
+) (*starknet.PreConfirmedUpdateEnvelope, error) {
 	if blockIdentifier == "" {
 		blockIdentifier = PreConfirmedBlankIdentifier
 	}
@@ -390,12 +434,7 @@
 		"blockIdentifier":       blockIdentifier,
 		"knownTransactionCount": strconv.FormatUint(knownTransactionCount, 10),
 	})
-
-	env, err := doRequest[starknet.PreConfirmedUpdateEnvelope](ctx, c, queryURL)
-	if err != nil {
-		return nil, err
-	}
-	return env.Update, nil
+	return doRequest[starknet.PreConfirmedUpdateEnvelope](ctx, c, queryURL)
 }
 
 // Deprecated: Transaction calls the get_transaction endpoint which returns

clients/feeder/feeder_test.go

@@ -1321,3 +1321,37 @@ func TestFeederValidation(t *testing.T) {
 		)
 	})
 }
+
+func TestPreConfirmedBlockLatest(t *testing.T) {
+	client := feeder.NewTestClient(t, &networks.Sepolia)
+
+	t.Run("blank identifier returns the full block for a new round", func(t *testing.T) {
+		update, blockNumber, err := client.PreConfirmedBlockLatest(t.Context(), "", 0)
+		require.NoError(t, err)
+		assert.Equal(t, uint64(10936237), blockNumber)
+
+		full, ok := update.(starknet.PreConfirmedBlock)
+		require.True(t, ok, "expected PreConfirmedBlock, got %T", update)
+		assert.Equal(t, "0x1cbe25d9", full.BlockIdentifier)
+		assert.Equal(t, "PRE_CONFIRMED", full.Status)
+		assert.Equal(t, "0.14.2", full.Version)
+		assert.Len(t, full.Transactions, 3)
+	})
+
+	t.Run("matching identifier and txn count returns the appended delta", func(t *testing.T) {
+		update, blockNumber, err := client.PreConfirmedBlockLatest(t.Context(), "0x1cbe25d9", 3)
+		require.NoError(t, err)
+		assert.Equal(t, uint64(10936237), blockNumber)
+
+		delta, ok := update.(starknet.PreConfirmedDeltaUpdate)
+		require.True(t, ok, "expected PreConfirmedDeltaUpdate, got %T", update)
+		assert.Equal(t, "0x1cbe25d9", delta.BlockIdentifier)
+		assert.Len(t, delta.Transactions, 1)
+	})
+
+	t.Run("matching identifier with no appended txns returns no change", func(t *testing.T) {
+		update, _, err := client.PreConfirmedBlockLatest(t.Context(), "0x1cbe25d9", 4)
+		require.NoError(t, err)
+		assert.IsType(t, starknet.PreConfirmedNoChange{}, update)
+	})
+}

clients/feeder/test_feeder.go

@@ -156,12 +156,15 @@ func resolveDirAndQueryArg(t testing.TB, path string, queryMap url.Values) (stri
 		queryArg = "blockHash"
 
 	case strings.HasSuffix(path, "get_preconfirmed_block"):
-		if _, ok := queryMap["blockIdentifier"]; ok {
-			return "pre_confirmed_delta", blockNumberArg, nil
+		// A blank identifier (re)syncs from preconfirmed/<blockNumber>/full;
+		// any other identifier selects the exact response fixture at
+		// preconfirmed/<blockNumber>/<identifier>/<knownTransactionCount>.
+		blockNumber := queryMap.Get(blockNumberArg)
+		if identifier := queryMap.Get("blockIdentifier"); identifier != PreConfirmedBlankIdentifier {
+			return filepath.Join("preconfirmed", blockNumber, identifier), "knownTransactionCount", nil
 		}
-
-		dir = "pre_confirmed"
-		queryArg = blockNumberArg
+		queryMap["preconfirmedFile"] = []string{"full"}
+		return filepath.Join("preconfirmed", blockNumber), "preconfirmedFile", nil
 
 	default:
 		err = errors.New("unknown endpoint")

clients/feeder/testdata/sepolia/preconfirmed/1781802365/0x1857317c/2.json

@@ -0,0 +1,215 @@
+{
+  "transactions": [
+    {
+      "type": "INVOKE_FUNCTION",
+      "resource_bounds": {
+        "L1_GAS": {
+          "max_amount": "0x11170",
+          "max_price_per_unit": "0x8d79883d20000"
+        },
+        "L2_GAS": {
+          "max_amount": "0x5f5e100",
+          "max_price_per_unit": "0xba43b7400"
+        },
+        "L1_DATA_GAS": {
+          "max_amount": "0x2710",
+          "max_price_per_unit": "0x62448724953354"
+        }
+      },
+      "tip": "0x5f5e100",
+      "calldata": [
+        "0x1",
+        "0x35df8ef86553a190f19be56e763442a31f277828039f00b97ac4afdc4ad9cf3",
+        "0x2fd9126ee011f3a837cea02e32ae4ee73342d827e216998e5616bab88d8b7ea",
+        "0x1",
+        "0x2fd9126ee011f3a837cea02e32ae4ee73342d827e216998e5616bab88d8b7ea"
+      ],
+      "sender_address": "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5",
+      "nonce": "0x95eb10",
+      "signature": [
+        "0x694e21e4cd18f496b21fd9ec325400c58c2282bcf1a00cb641bf29255210c88",
+        "0x2a278ea699bad88bd38cd1e7b758229ddf440081248ee31f8b46cb6ac3d007e"
+      ],
+      "nonce_data_availability_mode": 0,
+      "fee_data_availability_mode": 0,
+      "paymaster_data": [],
+      "account_deployment_data": [],
+      "proof_facts": [],
+      "transaction_hash": "0x433b1e9ce02a32d8788f630fbcabf9ae4904a913c4e3803077392f37d2b14fd",
+      "version": "0x3"
+    },
+    {
+      "type": "INVOKE_FUNCTION",
+      "resource_bounds": {
+        "L1_GAS": {
+          "max_amount": "0x11170",
+          "max_price_per_unit": "0x8d79883d20000"
+        },
+        "L2_GAS": {
+          "max_amount": "0x5f5e100",
+          "max_price_per_unit": "0xba43b7400"
+        },
+        "L1_DATA_GAS": {
+          "max_amount": "0x2710",
+          "max_price_per_unit": "0x62448724953354"
+        }
+      },
+      "tip": "0x5f5e100",
+      "calldata": [
+        "0x2",
+        "0x35df8ef86553a190f19be56e763442a31f277828039f00b97ac4afdc4ad9cf3",
+        "0x27c3334165536f239cfd400ed956eabff55fc60de4fb56728b6a4f6b87db01c",
+        "0x3",
+        "0x30a26db8c8e2ca8c5bac843188bd538ace0f09176a519cecf5beb2475204fad",
+        "0xb17d8a2731ba7ca1816631e6be14f0fc1b8390422d649fa27f0fbb0c91eea8",
+        "0x0",
+        "0x35df8ef86553a190f19be56e763442a31f277828039f00b97ac4afdc4ad9cf3",
+        "0x17da35ce4ed77e22e3b9149fd965dba57351a6c29f588a7d245e208d073e4c1",
+        "0x0"
+      ],
+      "sender_address": "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5",
+      "nonce": "0x95eb11",
+      "signature": [
+        "0x684ccb78ae4ac3ba5c5f8cbd0623d43b3ebe29e833df9a6955e16705f1d8a4",
+        "0x1a7feb5abc778a74194bb62f2fa7676c5cffefcaf1177189c336d22c1bb71da"
+      ],
+      "nonce_data_availability_mode": 0,
+      "fee_data_availability_mode": 0,
+      "paymaster_data": [],
+      "account_deployment_data": [],
+      "proof_facts": [],
+      "transaction_hash": "0x518b61ae3d0a3c783d96714d42a67b411db77156c0328c56cc7fcba2672d6b",
+      "version": "0x3"
+    }
+  ],
+  "transaction_receipts": [
+      {
+      "transaction_index": 2,
+      "transaction_hash": "0x433b1e9ce02a32d8788f630fbcabf9ae4904a913c4e3803077392f37d2b14fd",
+      "l2_to_l1_messages": [],
+      "events": [
+        {
+          "from_address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
+          "keys": [
+            "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9",
+            "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5",
+            "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8"
+          ],
+          "data": [
+            "0x1717098adb2b80",
+            "0x0"
+          ]
+        }
+      ],
+      "execution_resources": {
+        "n_steps": 4885,
+        "builtin_instance_counter": {
+          "range_check_builtin": 158,
+          "poseidon_builtin": 18,
+          "pedersen_builtin": 4
+        },
+        "n_memory_holes": 0,
+        "data_availability": {
+          "l1_gas": 0,
+          "l1_data_gas": 128,
+          "l2_gas": 0
+        },
+        "total_gas_consumed": {
+          "l1_gas": 0,
+          "l1_data_gas": 128,
+          "l2_gas": 795835
+        }
+      },
+      "actual_fee": "0x1717098adb2b80",
+      "execution_status": "SUCCEEDED"
+    },
+    {
+      "transaction_index": 3,
+      "transaction_hash": "0x518b61ae3d0a3c783d96714d42a67b411db77156c0328c56cc7fcba2672d6b",
+      "l2_to_l1_messages": [],
+      "events": [
+        {
+          "from_address": "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
+          "keys": [
+            "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9",
+            "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5",
+            "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8"
+          ],
+          "data": [
+            "0x202fd9fdf3b4880",
+            "0x0"
+          ]
+        }
+      ],
+      "execution_resources": {
+        "n_steps": 4912,
+        "builtin_instance_counter": {
+          "range_check_builtin": 158,
+          "poseidon_builtin": 20,
+          "pedersen_builtin": 4
+        },
+        "n_memory_holes": 0,
+        "data_availability": {
+          "l1_gas": 0,
+          "l1_data_gas": 128,
+          "l2_gas": 0
+        },
+        "total_gas_consumed": {
+          "l1_gas": 0,
+          "l1_data_gas": 128,
+          "l2_gas": 17889384
+        }
+      },
+      "actual_fee": "0x202fd9fdf3b4880",
+      "execution_status": "SUCCEEDED"
+    }
+  ],
+  "transaction_state_diffs": [
+    {
+      "storage_diffs": {
+        "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d": [
+          {
+            "key": "0x5496768776e3db30053404f18067d81a6e06f5a2b0de326e21298fd9d569a9a",
+            "value": "0x39ab1bd8e02f99f7fb4fd"
+          },
+          {
+            "key": "0x47146b3357200298e01a27f2994f8b4ab20c6df9b07a31923bf8769cb3e6449",
+            "value": "0x116b05ea4128f31e48f"
+          }
+        ]
+      },
+      "deployed_contracts": [],
+      "declared_classes": [],
+      "migrated_compiled_classes": [],
+      "old_declared_contracts": [],
+      "nonces": {
+        "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5": "0x95eb11"
+      },
+      "replaced_classes": []
+    },
+    {
+      "storage_diffs": {
+        "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d": [
+          {
+            "key": "0x5496768776e3db30053404f18067d81a6e06f5a2b0de326e21298fd9d569a9a",
+            "value": "0x39ab1bf9100997ebafd7d"
+          },
+          {
+            "key": "0x47146b3357200298e01a27f2994f8b4ab20c6df9b07a31923bf8769cb3e6449",
+            "value": "0x116ae5ba672aff69c0f"
+          }
+        ]
+      },
+      "deployed_contracts": [],
+      "declared_classes": [],
+      "migrated_compiled_classes": [],
+      "old_declared_contracts": [],
+      "nonces": {
+        "0x27125dc293a66e3df8784c51ed07c7011cf02f5fe53de3163ae78cbab7e80f5": "0x95eb12"
+      },
+      "replaced_classes": []
+    }
+  ],
+  "block_identifier": "0x1857317c",
+  "changed": true
+}

clients/feeder/testdata/sepolia/preconfirmed/1781802365/0x1857317c/4.json

@@ -0,0 +1,3 @@
+{
+  "changed": false
+}