repository·development·Indexed 42 days ago
https://github.com/software-mansion/starknet.pyA comprehensive Python SDK for interacting with the Starknet blockchain. It provides high-level abstractions for managing accounts, interacting with smart contracts, and communicating with Starknet full nodes via FullNodeClient. The SDK supports declaring and deploying contracts, executing multicalls for gas optimization, and parsing Starknet ABIs (v0, v1, and v2). Version 0.30.0.
A KeyPair consists of a private key and a public key.
In starknet.py, the KeyPair class (from starknet_py.net.signer.key_pair) is a prerequisite for creating Account objects and StarkCurveSigner objects.
Starting with version 0.29.0, the hash function for contract declaration is automatically selected based on the Starknet/RPC version:
Because Starknet proxy implementations vary, starknet.py uses a mechanism called ProxyCheck to identify and resolve proxies. Contract.from_address iterates through available proxy_checks to find the implementation's address or class_hash.
By default, proxy_config includes:
ArgentProxyCheck: Resolves Argent Proxy implementations.OpenZeppelinProxyCheck: Resolves OpenZeppelin Proxy implementations.Note: StarknetEthProxyCheck has been removed as StarkGate ETH Token is no longer a proxy.
By default, an Account uses the signing method of OpenZeppelin's account contract. If you need to use a different signing algorithm, you can create an Account instance by providing a custom Signer implementation.
# Example of creating an Account with a custom Signer implementation
# (Refer to test_custom_signer.py for specific implementation details)The Deployer class is used to deploy contracts if you already have an account. starknet.py assumes the UDC implementation is compatible with OpenZeppelin's UDC implementation.
The Deployer is also designed to work with multicalls, allowing you to deploy a contract and call its methods within the same atomic transaction.
# Example of deploying with UDC
# (Refer to test_deploying_with_udc.py for implementation details)
# Example of deploying and calling methods in a single multicall
# (Refer to test_deploying_in_multicall.py for implementation details)starknet.py provides mechanisms to serialize Python values into Cairo-compatible values and deserialize Cairo values back into Python types. This is essential for interacting with Starknet contracts via function calls or processing contract events.
| Expected Cairo type | Accepted Python types | Example Python values |
|---|---|---|
felt | int | 0, 1213124124 (must be in range [0;P)) |
tuple | any iterable of matching size | (1, 2, (9, 8)) |
named tuple | dict, NamedTuple, or TupleDataclass | {"a": 1, "b": 2} |
struct | dict with keys matching struct | {"key_1": 2, "key_2": (1, 2, 3)} |
pointer/array | any iterable | [1, 2, 3] (automatically fills parameter_len) |
uint256 | int or dict with "low" and "high" keys | 340282366920938463463374607431768211583 or {"low": 12, "high": 13} |
| Cairo type | Python type |
|---|---|
felt | int |
tuple | tuple |
named tuple | TupleDataclass |
struct | dict |
pointer/array | list |
uint256 | int |
Client class in starknet_py.net.client serves as the base class for all clients interacting with the Starknet network. For most standard use cases, you should use FullNodeClient, which is the primary implementation of this interface. It provides the necessary methods to communicate with a Starknet node to perform network operations.To execute state-changing transactions, you often need to prepare them before sending.
PreparedFunctionCall: Used for preparing a standard function call.PreparedFunctionInvokeV3: Used for preparing function invokes specifically for transaction version 1 (which includes a __validate__ function).These objects allow you to construct the transaction parameters (calldata, etc.) before signing and broadcasting them via an Account.
The starknet_py.abi.v2.Abi model is the most comprehensive representation of a contract's ABI. It provides access to the following components:
functions: The contract's callable functions.constructor: The constructor definition.l1_handler: L1 handlers for cross-layer communication.events: The events emitted by the contract.defined_structures: Custom structures defined in the ABI.defined_enums: Custom enums defined in the ABI.interfaces: Interfaces implemented or used.implementations: Implementation details.Each Function and Event within the Abi object contains its own specific metadata and properties.
SNIP-9 standard. Account provides methods to sign transactions that can later be executed by a different account. In this pattern, the signer does not need to be funded with tokens because the executor pays the transaction fee.When subscribing to block headers, events, or transaction statuses, the network may undergo reorganizations (e.g., when a block is replaced by a different canonical block). To handle these updates, provide a custom callback function to the on_reorg parameter in your subscription methods.
async def my_reorg_handler(reorg_info):
print(f"Chain reorg detected: {reorg_info}")
await client.subscribe_new_heads(on_reorg=my_reorg_handler)If you cannot use the DeployAccount transaction, there are two other programmatic ways to create an account, though both require an existing account to initiate the process: