v0.4.0

⚠️ 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.

⚠️ Please take note of the following ⚠️

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.

Full Changelog: v0.3.8...v0.4.0

v0.3.8

This release adds support for the second Starknet testnet running on top of Ethereum Goerli. It also contains some fixes and improvements for various JSON-RPC methods and an internal change in how we set up and start Python subprocesses.

Fixes

• JSON-RPC 0.1: starknet_getStateUpdate now supports fetching the pending state update.
• JSON-RPC 0.2: starknet_getBlockWithTxHashes and starknet_getBlockWithTxs returns block not found when requesting the pending block and no pending block is currently available. Previously these methods were falling back to returning the latest block instead.
• JSON-RPC 0.1 and 0.2: starknet_getTransactionReceipt now has improved performance.

Added

• --testnet2 command line flag can be specified to use the second Starknet testnet.

Full Changelog: v0.3.7...v0.3.8

v0.3.7

This release adds support for estimating DEPLOY_ACCOUNT transactions and fixes an issue with the starknet_estimateFee and starknet_call calls.

Changed

• We have internally upgraded to using the latest cairo-lang package available, version 0.10.1.

Fixes

• starknet_estimateFee and starknet_call now works with the block_id parameter specified as a block number.

Added

• starknet_estimateFee now supports estimating DEPLOY_ACCOUNT transactions introduced in Starknet 0.10.1.

Full Changelog: v0.3.6...v0.3.7

v0.3.6

Starknet 0.10.1 support

This release enables support for Starknet 0.10.1. Starknet 0.10.1 introduces a new transaction type: DEPLOY_ACCOUNT. The addition of the new transaction type is a backward incompatible change. We strongly urge you to upgrade before Starknet 0.10.1 is released.

Previous versions of pathfinder will no longer be able to sync on blocks from Starknet version 0.10.1 and onwards.

JSON-RPC API

To keep backward compatibility with existing JSON-RPC clients we have decided to expose multiple versions of the JSON-RPC specification. We're keeping our implementation of the 0.1.0 specification while adding support for the upcoming 0.2.1 release.

The path of the URL used to access the JSON-RPC server determines which version of the API is served:

• the 0.1.0 API is exposed on the / and /rpc/v0.1 paths
• the 0.2.1-rc1 API is exposed on the /rpc/v0.2 path

Support for version 0.2.1-rc1 of the Starknet JSON-RPC API

We have added an implementation for this new release of the specification. This is still a work in progress: we continue working on adding missing functionality. Known deviations from the specification are:

• starknet_estimateFee does not support estimating DEPLOY_ACCOUNT transactions.

JSON-RPC API v0.1.0 changes

DEPLOY_ACCOUNT transactions

To be able to represent DEPLOY_ACCOUNT transactions we're deviating from 0.1.0 JSON-RPC specification. We represent the DEPLOY_ACCOUNT transaction type as the DEPLOY_ACCOUNT_TXN type as defined in version 0.2.1-rc1 of the specification.

starknet_addInvokeTransaction can now submit version 1 transactions

Version 1 invoke transactions cannot be submitted without a nonce so we have added an optional nonce parameter to the method. This is a deviation from the 0.1.0 specification but it's a compatible change. See issue #632 for more details.

More metrics

Pathfinder already provided some metrics to get better insight into the performance of the JSON-RPC interface. This release adds metrics that provide information about the communication with the Starknet gateway. Please check our documentation for more information.

Full Changelog: v0.3.5...v0.3.6

v0.3.5

This release fixes an issue with the starknet_estimateFee call. Previously a version 0 invoke transaction with a version field set to a query version (>2**128) caused an internal error.

Changed

• Improved performance for operations involving a lot of Stark hash calculations, like syncing.
• Improved performance for starknet_call and starknet_estimateFee calls for transactions involving a lot of storage accesses.

Fixes

• starknet_estimateFee now works for version 0 invoke transactions using a query version.

Added

• New metrics for external python subprocesses
  • extpy_processes_launched_total
  • extpy_processes_exited_total
  • extpy_processes_failed_total

Full Changelog: v0.3.4...v0.3.5

v0.3.4

This release upgrades our internal starknet-vm from 0.9.1 to 0.10. It should now be possible to use starknet_call and starknet_estimateFee on the new transaction types

In addition, this release also performs a database migration to remove some extra bogus events that slipped in with the StarkNet 0.10 update on testnet. This migration may take a while to perform, and depends on how many blocks you sync'd during the affected period. The migration will log progress and an ETA.

Changed

• internal starknet-vm upgrade to latest 0.10 version
• entry_point_selector is now an optional parameter for starknet_estimateFee in order to allow for the new StarkNet 0.10 invoke transaction type.

Fixed

• starknet_estimateFee does not accept nonce parameter
• V1 invoke transactions returned 0 for nonce and version fields
• Some starknet_call and starknet_estimateFee queries return internal error involving 'compiler_version': ['Unknown field.']
  • This was less a bug, and more a result of upgrading our internal-vm
• add a work-around for StarkNet gateway bug where the nonce field is missing for historic L1_HANDLER transactions
• blocks with a hash mismatch are accepted

Full Changelog: v0.3.3...v0.3.4

v0.3.3

Class hash mismatch bug

The focus of this minor release is to fix a bug in our class hash algorithm introduced by some backwards incompatible changes from StarkNet 0.10. You may have seen this bug preventing your sync from progressing, with this warning being logged:

WARN L2 sync process terminated with: Deploying new contracts for block StarknetBlockNumber(322614)

Caused by:
    0: Download and compress contract ContractAddress(0x03DA98FD5A98D49819E38840D0AED1D5A61E14753358456C61224A5850E841C1)
    1: Class hash mismatch for contract ContractAddress(0x03DA98FD5A98D49819E38840D0AED1D5A61E14753358456C61224A5850E841C1)

This has now been fixed.

Fixed

• class hash mismatch

Full Changelog: v0.3.2...v0.3.3

v0.3.2

StarkNet 0.10 support

This release enables support for StarkNet 0.10. This version is compatible with both StarkNet 0.9.1 and 0.10 and we urge you to update before StarkNet 0.10 is released.

Previous versions of pathfinder will no longer be able to sync on blocks from StarkNet version 0.10 and onwards.

JSON-RPC changes

We have attempted to keep changes to the JSON-RPC API minimal in order to stay aligned with the JSON-RPC specification version 0.1.0. However, this was not 100% possible as StarkNet 0.10 adds new features incompatible with the specification.

This situation will be improved once version 0.2.0 of the JSON-RPC specification is released.

The changes and impacts are detailed below.

L1 Handler transaction

StarkNet 0.10 introduces a new transaction type; L1 Handler -- we have added this to our transaction enum list where applicable. We have taken the new type from the release candidate of the JSON-RPC specification v0.2.0 which you can see here.

starknet_call and starknet_estimateFee

Our internal version of the starknet-vm is still lagging behind on v0.9.1. This means that newer StarkNet transactions (version 1) are unlikely to work when calling starknet_call and starknet_estimateFee. We will address this in an upcoming release.

Prometheus metrics support

We now provide Prometheus metrics! These are available via the route <monitoring-address>/metrics when the monitoring API is enabled.

Monitoring can be enabled by specifying the --monitor-address.

Currently metrics comprise the rpc_method_calls_total counters, where label key method should be used to point to the counter for a particular RPC method, for example: rpc_method_calls_total{method="starknet_getBlockWithTxs"}.

Added

• Support for StarkNet 0.10
• Support for Prometheus metrics

Fixed

• Potential DoS loop when gateway responses are not parseable (e.g. due to a major StarkNet update :P).
• JSON-RPC starknet_getEvents does not use snake case for from_block and to_block. This was incorrectly using fromBlock and toBlock -- these are still allowed in order to not break anyone using the old form. This compatibility may be removed in a future breaking release.
• various readme documentation fixes
  • document monitoring API
  • update starknet discord link (previous one was no longer valid)
  • improve docker instructions to use the same UID/GID

Full Changelog: v0.3.1...v0.3.2

Acknowledgements

@fracek for the first attempt at introducing metrics to the project.

v0.3.1

Important bug fix update

This point release contains an important fix for a state hash collision and should be applied as fast as possible.

This update also contains a couple of smaller features like a basic monitoring API.

The bug

The bug occurs due to a rare hash collision in the merkle state tree. Unfortunately, it silently corrupts the database in a non-recoverable way. This means that all databases should be considered suspect and you should re-sync from scratch after updating. To make this process easier, we have provided snapshots for both mainnet and testnet.

While this bug has been present in all versions of pathfinder, it only became possible to trigger this bug in the past week on StarkNet.

Naming change

You may have noticed that we have dropped the -alpha suffix from this release. This was mistakenly used in our prior releases due to a misunderstanding of how this semantic versioning naming worked. According to semver it is meant to indicate a pre-release of that version i.e. v0.1.1-alpha is a pre-release and one should expect a non-alpha v0.1.1 to follow at some stage. However, we simply wanted to use it to indicate that pathfinder is still in alpha -- this is however adequately indicated by the 0.x.y version number already.

We have therefore decided to drop the -alpha suffix in order to cause less confusion :)

Added

Monitoring endpoint

You can now enable a monitoring endpoint using --monitor-address IP:PORT. This adds /health and /ready queries which can be used to monitor the health and readiness of your pathfinder node. For more information see our readme.

Changed

• No longer store leaf nodes. This is a minor (1-2%) reduction in database size.

Fixed

• Minimum Rust version by @haritowa in 506
• Rare database migration bug for the events schema
• Less rare database migration bug involving max fee for historical blocks

New Contributors

• @haritowa made their first contribution in #506

Full Changelog: v0.3.0-alpha...v0.3.1

v0.3.0-alpha

⚠️ This release contains breaking changes ⚠️

Database

This release adds support for starknet_getStateUpdate. Unfortunately the data required to serve this data is not present in existing pathfinder databases. This means that in order to support this query for all blocks, you will need to re-sync your node. If you do not do this, then this query won't succeed for blocks that your node has already downloaded.

We will provide updated snapshots in order to speed up this re-sync process.

JSON-RPC API

The JSON-RPC API has been updated to conform to the first formal StarkNet JSON-RPC specification. Our readme contains all the relevant information and links to the new API.

The specific changes, additions and removals are listed in the relevant sections below.

pending support

Pathfinder supports querying the pending StarkNet state. See our readme for specifics on what this is.

The breaking change is two-fold:

1. Previously, pathfinder simply proxied pending queries to the gateway. This is fundamentally against how pathfinder is supposed to operate as no validation or verification of the result was possible. Instead, pathfinder now periodically polls the pending data and verifies it locally in-so-far as possible.
2. pending support is disabled by default and can be enabled with --poll-pending=true option

Sqlite-WAL

We've had the --sqlite-wal=true|false option available for a while now. In this release we've changed the default from false to true. The only reason to keep this set to false should be if you are using network storage. Enabling this option improves our database's read and write concurrency.

added

• JSON-RPC API
  • starknet_getBlockWithTxHashes
  • starknet_getBlockWithTxs
  • starknet_getStateUpdate
  • starknet_getTransactionByBlockIdAndIndex
  • starknet_getBlockTransactionCount
  • starknet_getNonce
  • starknet_blockHashAndNumber
  • starknet_pendingTransactions
  • starknet_getEvents
• docker-compose by @sven-hash #487
• Support pending locally (see our readme for more info)

changed

• JSON-RPC API
  • starknet_getStorageAt
  • starknet_getClassHashAt
  • starknet_getClassAt
  • starknet_call
  • starknet_estimateFee
  • starknet_addDeployTransaction (now accepts optional abi field)
  • starknet_addDeclareTransaction (now accepts optional abi field)

removed

• JSON-RPC API
  • starknet_getBlockByHash
  • starknet_getBlockByNumber
  • starknet_getTransactionByBlockHashAndIndex
  • starknet_getTransactionByBlockNumberAndIndex
  • starknet_getCode
  • starknet_getBlockTransactionCountByHash
  • starknet_getBlockTransactionCountByNumber
• proxying pending queries to the gateway

fixed

• rare database locked error when spawning python processes
• broken pipe exceptions from python processes

New Contributors

• @sven-hash made their first contribution in #487

Full Changelog: v0.2.6-alpha...v0.3.0-alpha