Pathfinder release notes

Pathfinder is a Starknet full node giving you a safe view into Starknet.

It provides the following features:

  • Access the full Starknet state history

  • Verifies state using Ethereum

  • Implements the Starknet JSON-RPC API

  • Run Starknet functions without requiring a Starknet transaction

  • Ability to do fee estimation for transactions

See the official Pathfinder Github repository for more details.

[0.6.6] - 2023-07-10 (latest)

Fixed

  • stack overflow while compiling Sierra to CASM

[0.6.5] - 2023-07-07

Fixed

  • pending data from the gateway is inconsistent

  • this could exhibit as RPC data changing status between pending | L2 accepted | not found, especially noticeable for transactions.

Changed

  • substantially increase the character limit of execution errors

  • previously, the RPC would return a highly truncated error message from the execution vm

[0.6.4] - 2023-07-05

Fixed

  • Pending data is not polled for starknet v0.12 due to an HTTP error code change from the gateway.

  • Transaction receipts missing from_address in MSG_TO_L1.

[0.6.3] - 2023-06-29

Fixed

  • Sierra class hash not in declared classes sync bug

Changed

  • use all libfunc list instead of experimental for sierra compilation

[0.6.2] - 2023-06-29

Added

  • starknet_estimateMessageFee for JSON-RPC v0.3.1 to estimate message fee from L1 handler.

  • sync-related metrics

  • current_block: the currently sync’d block height of the node

  • highest_block: the height of the blockchain

  • block_time: timestamp difference between the current block and its parent

  • block_latency: delay between current block being published and sync’d locally

  • block_download: time taken to download current block’s data excluding classes

  • block_processing: time taken to process and store the current block

  • configuration for new block polling interval: --sync.poll-interval <seconds>

  • Starknet v0.12.0 support

  • sierra v2.0.0 support

  • cairo-lang upgraded to 0.12.0a0

Fixed

  • reorgs fail if a class declaration is included in the reorg

  • sync can fail if db connection pool is held saturated by rpc queries

  • uses finalized (reorg-safe) L1 state instead of latest

  • starknet_getEvents times out for queries involving a large block range

Changed

  • dropped upgrade support for pathfinder v0.4 and earlier

  • separate db connection pools rpc, sync and storage

  • increased the number of rpc db connections

[0.6.1] - 2023-06-18

Fixed

  • class hash mismatch for cairo 0 classes with non-ascii text

[0.6.0] - 2023-06-14

Fixed

  • starknet_simulateTransaction requires transactions instead of transaction as input field.

  • gateway’s error message is hidden when submitting a failed transaction

  • starknet_getEvents is very slow for certain filter combinations

Changed

  • default RPC API version changed from v0.2 to v0.3

  • disallow JSON-RPC notification-style requests

[0.5.6] - 2023-05-25

Added

  • Starknet v0.11.2 support

  • Sierra compiler v1.1.0-rc0

  • cairo-lang upgraded to 0.11.2a0

  • Subscription to newHead events via websocket using the method pathfinder_subscribe_newHeads, which can be managed by the following command line options

  • rpc.websocket, which enables websocket transport

  • rpc.websocket.capacity, which sets the maximum number of websocket subscriptions per subscription type

    Authors: [Shramee Srivastav](https://github.com/shramee) and [Matthieu Auger](https://github.com/matthieuauger)

[0.5.5] - 2023-05-18

Added

  • cairo-lang upgraded to 0.11.1.1

Fixed

  • RPC emits connection logs and warnings

  • Fee estimate mismatch between gateway and pathfinder

  • Gateway uses a new gas price sampling algorithm which was incompatible with pathfinders.

  • Fee estimate returns error when submitting Cairo 1.0.0-rc0 classes.

  • Historic L1 handler transactions are served as Invoke V0

  • Older databases contain L1 handler transactions from before L1 handler was a specific transaction type. These were stored as Invoke V0. These are now correctly identified as being L1 Handler transactions.

Fixed

  • RPC emits connection logs and warnings

  • Fee estimate mismatch between gateway and pathfinder

  • Gateway uses a new gas price sampling algorithm which was incompatible with pathfinders.

  • Historic L1 handler transactions are served as Invoke V0

  • Older databases contain L1 handler transactions from before L1 handler was a specific transaction type. These were stored as Invoke V0. These are now correctly identified as being L1 Handler transactions.

v0.5.4

The primary focus of this release is to provide support for Starknet v0.11.1, and will continue to work for v0.11.0. Since this release is required for v0.11.1, you should update your node before the network is updated.

Added

  • Starknet v0.11.1 support

  • CORS support via the rpc.cors-domains configuration option

  • Transaction hashes are now verified as part of the sync process. Previously, these were not verified as the exact algorithm was underdocumented and the transaction format was still evolving.

Fixed

  • RPC server panic for unprefixed unregistered method names

  • Data can temporarily appear to go missing when transitioning from PENDING to ACCEPTED ON L2

  • This was commonly seen when rapidly monitoring a new transaction, which would go from PENDING to TXN_HASH_NOT_FOUND to ACCEPTED_ON_L2 as pathfinder moved the ephemeral pending data to latest data on disk.

v0.5.3

Fixes for minor issues and inconsistencies.

Added

  • max-rpc-connections command-line argument. This sets the maximum number incoming RPC connections the pathfinder node will accept. This defaults to 1024 if not specified.

  • cairo-lang upgraded to 0.11.0.2

Fixed

  • starknet_simulateTransaction data model inconsistency

  • poll-pending default value restored to false

  • incoming RPC connections limited to 100. This limit was accidentily introduced in v0.5.2 as part of a dependency upgrade, whereas before it was unlimited. The default is now 1024 and can be configured using --max-rpc-connections.

  • handling of invalid JSON-RPC requests

v0.5.2

This release fixes a few RPC bugs and adds support for bulk fee estimation and transaction simulation (traces) as part of v0.3 RPC specification.

In addition it also adds a pathfinder_getTransactionStatus endpoint which lets you track a transactions status — including REJECTED and RECEIVED — in the same fashion as the gateway.

Added

  • support starknet_estimateFee in the JSON-RPC v0.3 API

  • supports estimating multiple transactions

  • this includes declaring and immediately using a class (not currently possible via the gateway)

  • support starknet_simulateTransaction for JSON-RPC v0.3

  • supports simulating multiple transactions

  • this includes declaring and immediately using a class (not currently possible via the gateway)

  • support pathfinder_getTransactionStatus which is exposed on all RPC routes

  • this enables querying a transactions current status, including whether the gateway has received or rejected it

Fixed

  • RPC returns int for entrypoint offsets instead of hex

  • RPC rejects Fee values with more than 32 digits

  • RPC does not expose pathfinder_getProof on v0.3 route

v0.5.1

This is a minor bugfix release, primarily to fix an issue with syncing on testnet2.

Fixed

  • pathfinder sometimes spams nethermind L1 nodes

  • pathfinder stops syncing testnet2 at block 95220 due to a Sierra class compilation issue

v0.5.0

Highlights

  • starknet v0.11.0 support

  • RPC API v0.3 partial support

  • removed several deprecated config options

  • requires python 3.9 or 3.10 (no longer 3.8)

Added

  • support for state commitment and class commitment in pathfinder_getProof

  • support for starknet v0.11

  • partial support for RPC specification v0.3

  • exposed on /rpc/v0.3/ route

  • missing support for starknet_estimateFee and starknet_simulate

Changed

  • starknet_call and starknet_estimateFee JSON-RPC methods return more detailed error messages

  • python version requirement has changed to 3.9 or 3.10 (was 3.8 or 3.9 previously)

Fixed

  • RPC accepts hex inputs for Felt without '0x' prefix. This led to confusion especially when passing in a decimal string which would get silently interpretted as hex.

  • using a Nethermind Ethereum endpoint occasionally causes errors such as <block-number> could not be found to be logged.

  • sync can miss new block events by getting stuck waiting for pending data.

Removed

RPC API

We added support for v0.3 and removed v0.1. We still support v0.2 at both /rpc/v0.2 and /rpc (default) routes. In summary:

/                     # serves v0.2
/rpc/v0.2/            # serves v0.2
/rpc/v0.3/            # serves v0.3

We are missing starknet_estimateFee and starknet_simulate support for v0.3, which will be added in an upcoming release.

Python requirement

Note: this only applies if you are building from source. This does not impact docker users.

Pathfinder requires python to support the starknet VM used to simulate starknet transactions and function calls. Previous versions of the VM only worked with python 3.8 or 3.9 which was a hassle because most operating systems no longer directly support it. The new version of the VM bundled with starknet v0.11 now requires python version 3.9 or 3.10.

Configuration changes

Several configuration options are now removed, after they were deprecated in pathfinder v0.4.1. Here is a migration guide:

  • --testnet2: use --network testnet2 instead

  • --integration: use --network integration instead

  • --sequencer-url: use --network custom in combination with --feeder-gateway-url and gateway-url

  • --config: use environment variables or env files as an alternative

v0.4.5

Hotfix for a bug introduced in the previous version v0.4.4, which prevented a new node from syncing on blocks near genesis.

Added

Added Newton FAQ links to readme

Fixed

Node fails to sync old blocks

New contributors

@SecurityQQ made their first contribution in #799

v0.4.4

This minor release contains some nice performance improvements for starknet_call and starknet_estimateFee as well as some minor bug fixes.

Also included is a major new feature: storage proofs - big thanks @pscott for his hard work on this feature! This is available via the pathfinder_getProof method which is served from both the pathfinder and Starknet endpoints for convenience:

<node-url>/rpc/pathfinder/v0.1/pathfinder_getProof
<node-url>/rpc/v0.2/pathfinder_getProof

The method is specified here.

Its results can be used to formally verify what a contract’s storage values are without trusting the pathfinder node.

This is achieved by validating the merkle-proof that pathfinder returns and confirming that it correctly matches the known Starknet state root.

Added

storage proofs via pathfinder_getProof by @pscott

Fixed

  • starknet_getEvents returns all events when from_block="latest"

  • v0.1 starknet_getStateUpdate does not contain nonces

Changed

  • Improved performance for starknet_call and starknet_estimateFee by caching classes

  • Improved performance for starknet_call and starknet_estimateFee by using Rust for hashing

New contributors

@pscott made their first contribution in #726

v0.4.3

The primary purpose of this release is to properly support testnet2 after the Starknet v0.10.3 update.

The v0.10.3 update changed the testnet2 chain ID which impacts transaction signatures which in turn meant that starknet_estimateFee would fail for any signed transaction.

This release updates pathfinder to use the correct chain ID.

Fixed

  • Testnet2 and integration flags are ignored

  • starknet_estimateFee uses wrong chain ID for testnet2

Changed

Updated to cairo-lang 0.10.3

v0.4.2

Contains several bug fixes, mostly hotfixes for bugs introduced in v0.4.1.

Added

Document that --chain-id expects text as input

Fixed

  • Testnet2 and integration L1 addresses are swapped (bug introduced in v0.4.1)

  • Proxy network setups can’t sync historical blocks (bug introduced in v0.4.1)

  • ABI serialization for starknet_estimateFee for declare transactions

v0.4.1

Highlights

  • Soft deprecation of some configuration options

  • Support custom Starknet gateways

  • Pathfinder RPC extensions at /rpc/pathfinder/ with pathfinder_version method

  • starknet_events optimisations

  • fix block timestamp in pending calls

  • Custom Starknet gateway support

This release introduces support for custom Starknets. You can select this network by setting --network custom and specifying the --gateway-url and --feeder-gateway-url options.

Configuration option deprecation

Several configuration options have been soft deprecated. This means using them will continue to work as before (no breaking change), but they will emit a warning when used. They will be removed in a future version, so please migrate to the newer options.

To re-emphasize: your current configuration setup will continue to work as is.

Network selection

--testnet2 and --integration have been deprecated in favor of --network testnet2 and --network integration.

Gateway proxy

--sequencer-url has been deprecated in favor of --network custom along with --gateway-url, --feeder-gateway-url and --chain-id. In addition, you will need to rename your existing database file to custom.sqlite as this will be the expected filename for custom networks.

Configuration file

--config has been deprecated and will not be supported in the future. The utility this provided was valuable. Unfortunately it is starting to severely hinder how fast we can implement configuration changes and we decided to remove it.

We suggest using environment variables along with environment files to configure pathfinder in a similar fashion.

Changed

The following configuration options are now marked as deprecated: --testnet2, --integration, --config, --sequencer-url Optimized starknet_events for queries with both a block range and a from address

Fixed

Block timestamps for pending in starknet_call and starknet_estimateFee were using the latest timestamp instead of the pending one. This meant contracts relying on accurate timestamps could sometimes fail unexpectedly.

Added

  • Custom Starknet support

  • Pathfinder specific RPC extensions hosted at <rpc-url>/rpc/pathfinder/v0.1. Currently, this only contains pathfinder_version which returns the pathfinder version of the node.

v0.4.0- (breaking release)

This release contains a breaking change, and also adds support for Starknet v0.10.2.

The changes themselves are quite simple, but please read through each section as there are some caveats which might impact you when you apply this update.

Default RPC version change

This release changes the version of the RPC that is served at the root route, from v0.1 to v0.2 of the RPC specification. Version v0.1 is still available at the /rpc/v0.1/ endpoint. This is the only breaking change in this release.

Here is a summary of what routes are currently available, and what’s changed:

  • / serves v0.2 (changed from v0.1)

  • /rpc/v0.1 serves v0.1 (no change)

  • /rpc/v0.2 serves v0.2 (no change)

If possible, we recommend that you use the version specific routes as this will prevent such breaking changes from impacting you.

Starknet v0.10.2 support

This release includes an update to the cairo-vm embedded in pathfinder in order to support the upcoming v0.10.2 Starknet release. This bundled vm is a pre-release and may therefore contain differences to the final version used once Starknet updates testnet and mainnet. We will of course issue a new release if / when there is a new vm.

Since these changes are not yet live on testnet nor mainnet, this means upgrading to this release will cause deviations between what pathfinder outputs and what can be expected on the network. More specifically, starknet_estimateFee will compute different fees until the network has upgraded to Starknet v0.10.2.

If you don’t need the RPC route changes, it may be pertinent to delay updating until closer to the v0.10.2 release dates on testnet and mainnet. The expected timeline for these upgrades is ~17/11 for testnets and ~24/11 for mainnet.