Account#

BaseAccount interface#

class starknet_py.net.account.base_account.BaseAccount#

Base class for all account implementations.

Signs, prepares and executes transactions.

Estimates the resources required by a given sequence of transactions when applied on a given state. If one of the transactions reverts or fails due to any reason (e.g. validation failure or an internal error), a TRANSACTION_EXECUTION_ERROR is returned. For v0-2 transactions the estimate is given in Wei, and for v3 transactions it is given in Fri.

Parameters:

tx – Transaction or list of transactions to estimate
skip_validate – Flag checking whether the validation part of the transaction should be executed
block_hash – Block hash or literals “pending” or “latest”
block_number – Block number or literals “pending” or “latest”

Returns:

Estimated fee or list of estimated fees for each transaction

abstract async execute_v3(calls: Call | Iterable[Call], *, resource_bounds: ResourceBoundsMapping | None = None, nonce: int | None = None, auto_estimate: bool = False) → SentTransactionResponse#

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
nonce – Nonce of the transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

SentTransactionResponse.

Checks account’s balance of the specified token. By default, it uses the L2 ETH address for mainnet and sepolia networks.

Parameters:

token_address – Address of the ERC20 contract.
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”

Returns:

Token balance.

Get the current nonce of the account.

Parameters:

block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”

Returns:

nonce of the account.

abstract async sign_declare_v3(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeclareV3#

Create and sign declare transaction version 3 using sierra contract.

Parameters:

compiled_contract – string containing a compiled Starknet contract. Supports new contracts (compiled to sierra).
compiled_class_hash – a class hash of the sierra compiled contract used in the declare transaction. Computed from casm compiled contract.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeclareV3 transaction.

abstract async sign_deploy_account_v3(class_hash: int, contract_address_salt: int, *, constructor_calldata: List[int] | None = None, nonce: int = 0, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeployAccountV3#

Create and sign deploy account transaction version 3.

Parameters:

class_hash – Class hash of the contract class to be deployed.
contract_address_salt – A salt used to calculate deployed contract address.
constructor_calldata – Calldata to be ed to contract constructor and used to calculate deployed contract address.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction. Enough tokens must be prefunded before sending the transaction for it to succeed.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeployAccountV3 transaction.

abstract async sign_for_fee_estimate(transaction: TypeAccountTransaction) → TypeAccountTransaction#

Sign a transaction for a purpose of only fee estimation. Should use a transaction version that is not executable on Starknet, calculated like transaction.version + 2 ** 128.

Parameters:: transaction – Transaction to be signed.
Returns:: A signed Transaction that can only be used for fee estimation and cannot be executed.

abstract async sign_invoke_v3(calls: Call | Iterable[Call], *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → InvokeV3#

Takes calls and creates signed Invoke.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Invoke created from the calls.

abstract sign_message(typed_data: TypedDataDict) → List[int]#

Sign an TypedData TypedDict for off-chain usage with the Starknet private key and return the signature. This adds a message prefix, so it can’t be interchanged with transactions. Both v0 and v1 domain revision versions are supported.

Parameters:: typed_data – TypedData TypedDict to be signed.
Returns:: The signature of the TypedData TypedDict.

abstract verify_message(typed_data: TypedDataDict, signature: List[int]) → bool#

Verify a signature of a TypedData dict on Starknet. Both v0 and v1 domain revision versions are supported.

Parameters:

typed_data – TypedData TypedDict to be verified.
signature – signature of the TypedData TypedDict.

Returns:

true if the signature is valid, false otherwise.

abstract property address: int#: Get the address of the account

abstract property cairo_version: int#: Get Cairo version of the account.

abstract property client: Client#: Get the Client used by the Account.

BaseAccount default implementation#

class starknet_py.net.account.account.Account#

Default Account implementation.

Parameters:

address – Address of the account contract.
client – Instance of Client which will be used to add transactions.
signer – Custom signer to be used by Account. If none is provided, default starknet_py.net.signer.stark_curve_signer.StarkCurveSigner is used.
key_pair – Key pair that will be used to create a default Signer.
chain –
Chain ID associated with the account. This can be supplied in multiple formats:
- an enum starknet_py.net.models.StarknetChainId
- a string name (e.g. ‘SN_SEPOLIA’)
- a hexadecimal value (e.g. ‘0x1’)
- an integer (e.g. 1)

Example

account = Account(
    address=0x123,
    client=FullNodeClient(node_url="https://your.node.url"),
    key_pair=KeyPair(12, 34),
    chain=StarknetChainId.SEPOLIA,
)

async static deploy_account_v3(*, address: int | str, class_hash: int, salt: int, key_pair: KeyPair, client: Client, constructor_calldata: List[int] | None = None, nonce: int = 0, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → AccountDeploymentResult#

Deploys an account contract with provided class_hash on Starknet and returns an AccountDeploymentResult that allows waiting for transaction acceptance.

Provided address must be first prefunded with enough tokens, otherwise the method will fail.

Parameters:

address – Calculated and prefunded address of the new account.
class_hash – Class hash of the account contract to be deployed.
salt – Salt used to calculate the address.
key_pair – KeyPair used to calculate address and sign deploy account transaction.
client – Client instance used for deployment.
constructor_calldata – Optional calldata to account contract constructor. If None is passed, [key_pair.public_key] will be used as calldata.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) used when executing this transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

static deploy_account_v3_sync(*, address: int | str, class_hash: int, salt: int, key_pair: KeyPair, client: Client, constructor_calldata: List[int] | None = None, nonce: int = 0, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → AccountDeploymentResult#: Synchronous version of the method.

Parameters:

tx – Transaction or list of transactions to estimate
skip_validate – Flag checking whether the validation part of the transaction should be executed
block_hash – Block hash or literals “pending” or “latest”
block_number – Block number or literals “pending” or “latest”

Returns:

Estimated fee or list of estimated fees for each transaction

estimate_fee_sync(tx: AccountTransaction | List[AccountTransaction], skip_validate: bool = False, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → EstimatedFee | List[EstimatedFee]#: Synchronous version of the method.

async execute_v3(calls: Call | Iterable[Call], *, resource_bounds: ResourceBoundsMapping | None = None, nonce: int | None = None, auto_estimate: bool = False) → SentTransactionResponse#

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
nonce – Nonce of the transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

SentTransactionResponse.

Example

resource_bounds = ResourceBoundsMapping(
    l1_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
    l2_gas=ResourceBounds(max_amount=int(1e9), max_price_per_unit=int(1e17)),
    l1_data_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
)
resp = await account.execute_v3(
    Call(
        to_addr=contract_address,
        selector=get_selector_from_name("increase_balance"),
        calldata=[123],
    ),
    resource_bounds=resource_bounds,
)
# or
resp = await account.execute_v3(calls=[call1, call2], auto_estimate=True)

execute_v3_sync(calls: Call | Iterable[Call], *, resource_bounds: ResourceBoundsMapping | None = None, nonce: int | None = None, auto_estimate: bool = False) → SentTransactionResponse#: Synchronous version of the method.

Checks account’s balance of the specified token. By default, it uses the L2 ETH address for mainnet and sepolia networks.

Parameters:

token_address – Address of the ERC20 contract.
block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”

Returns:

Token balance.

Example

eth_balance = await account.get_balance()
# or with custom token contract address
token_address = 0x1 or 1 or "0x1"
balance = await account.get_balance(token_address)

get_balance_sync(token_address: int | str | None = None, *, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → int#: Synchronous version of the method.

Get the current nonce of the account.

Parameters:

block_hash – Block’s hash or literals “pending” or “latest”
block_number – Block’s number or literals “pending” or “latest”

Returns:

nonce.

get_nonce_sync(*, block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → int#: Synchronous version of the method.

async get_outside_execution_nonce(retry_count=10) → int#: Generate special valid nonce for outside execution calls.

get_outside_execution_nonce_sync(retry_count=10) → int#: Synchronous version of the method.

async sign_declare_v3(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeclareV3#

Create and sign declare transaction version 3 using sierra contract.

Parameters:

compiled_contract – string containing a compiled Starknet contract. Supports new contracts (compiled to sierra).
compiled_class_hash – a class hash of the sierra compiled contract used in the declare transaction. Computed from casm compiled contract.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeclareV3 transaction.

sign_declare_v3_sync(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeclareV3#: Synchronous version of the method.

async sign_deploy_account_v3(class_hash: int, contract_address_salt: int, *, constructor_calldata: List[int] | None = None, nonce: int = 0, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeployAccountV3#

Create and sign deploy account transaction version 3.

Parameters:

class_hash – Class hash of the contract class to be deployed.
contract_address_salt – A salt used to calculate deployed contract address.
constructor_calldata – Calldata to be ed to contract constructor and used to calculate deployed contract address.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction. Enough tokens must be prefunded before sending the transaction for it to succeed.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeployAccountV3 transaction.

sign_deploy_account_v3_sync(class_hash: int, contract_address_salt: int, *, constructor_calldata: List[int] | None = None, nonce: int = 0, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → DeployAccountV3#: Synchronous version of the method.

async sign_for_fee_estimate(transaction: TypeAccountTransaction) → TypeAccountTransaction#

Sign a transaction for a purpose of only fee estimation. Should use a transaction version that is not executable on Starknet, calculated like transaction.version + 2 ** 128.

Parameters:: transaction – Transaction to be signed.
Returns:: A signed Transaction that can only be used for fee estimation and cannot be executed.

sign_for_fee_estimate_sync(transaction: TypeAccountTransaction) → TypeAccountTransaction#: Synchronous version of the method.

async sign_invoke_v3(calls: Call | Iterable[Call], *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → InvokeV3#

Takes calls and creates signed Invoke.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
resource_bounds – Resource limits (L1 and L2) that can be used in this transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Invoke created from the calls.

sign_invoke_v3_sync(calls: Call | Iterable[Call], *, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False) → InvokeV3#: Synchronous version of the method.

sign_message(typed_data: TypedData | TypedDataDict) → List[int]#

Parameters:: typed_data – TypedData TypedDict to be signed.
Returns:: The signature of the TypedData TypedDict.

Example

signature = account.sign_message(
    typed_data=TypedDataDict(
        types={
            "StarkNetDomain": [
                {"name": "name", "type": "felt"},
                {"name": "version", "type": "felt"},
                {"name": "chainId", "type": "felt"},
            ],
            "Example": [
                {"name": "value", "type": "felt"},
            ],
        },
        primaryType="Example",
        domain={"name": "StarkNet Example", "version": "1", "chainId": "1"},
        message={"value": 1},
    )
)

async sign_outside_execution_call(calls: Call | Iterable[Call], execution_time_bounds: OutsideExecutionTimeBounds, *, caller: int | str = 308399107364216179017042, nonce: int | None = None, interface_version: OutsideExecutionInterfaceID | None = None) → Call#

Creates a call for an outcide execution (SNIP-9 specification).

Parameters:

calls – Single call or list of calls to be executed by outside caller.
execution_time_bounds – Execution time bounds for the call.
caller – Address of the caller. IMPORTANT! By default it is ANY_CALLER.
nonce – Nonce for the transaction. Is populated automatically if not provided.
interface_version – Outside execution interface version. Method will check which version account supports and use the highest one and populate the value.

sign_outside_execution_call_sync(calls: Call | Iterable[Call], execution_time_bounds: OutsideExecutionTimeBounds, *, caller: int | str = 308399107364216179017042, nonce: int | None = None, interface_version: OutsideExecutionInterfaceID | None = None) → Call#: Synchronous version of the method.

async supports_interface(interface_id: OutsideExecutionInterfaceID) → bool#: Check if the account supports the given outside execution interface. Part of ISRC5 standard.

supports_interface_sync(interface_id: OutsideExecutionInterfaceID) → bool#: Synchronous version of the method.

verify_message(typed_data: TypedData | TypedDataDict, signature: List[int]) → bool#

Verify a signature of a TypedData dict on Starknet. Both v0 and v1 domain revision versions are supported.

Parameters:

typed_data – TypedData TypedDict to be verified.
signature – signature of the TypedData TypedDict.

Returns:

true if the signature is valid, false otherwise.

Example

is_correct = account.verify_message(
    typed_data=TypedDataDict(
        types={
            "StarkNetDomain": [
                {"name": "name", "type": "felt"},
                {"name": "version", "type": "felt"},
                {"name": "chainId", "type": "felt"},
            ],
            "Example": [
                {"name": "value", "type": "felt"},
            ],
        },
        primaryType="Example",
        domain={"name": "StarkNet Example", "version": "1", "chainId": "1"},
        message={"value": 1},
    ),
    signature=[12, 34],
)

ESTIMATED_FEE_MULTIPLIER: float = 1.5#: Amount by which each estimated fee is multiplied when using auto_estimate.

ESTIMATED_UNIT_PRICE_MULTIPLIER: float = 1.5#: Values by which each estimated max_amount and max_price_per_unit are multiplied when using auto_estimate. Used only for V3 transactions

property address: int#: Get the address of the account

property cairo_version: int#: Get Cairo version of the account.

property client: Client#: Get the Client used by the Account.

Account deployment#

Result of the Account deployment.

class starknet_py.net.account.account_deployment_result.AccountDeploymentResult#

Result of the Account.deploy_account method.

async wait_for_acceptance(check_interval: float = 2, retries: int = 500) → TypeSentTransaction#: Waits for transaction to be accepted on chain till ACCEPTED status. Returns a new SentTransaction instance, does not mutate original instance.

wait_for_acceptance_sync(check_interval: float = 2, retries: int = 500) → TypeSentTransaction#: Synchronous version of the method.

account: Account = None#: Account instance created during the deployment.

block_number: int | None = None#: Number of the block in which transaction was included.

hash: int#: Hash of the transaction.

status: str | None = None#: Status of the transaction.