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_v1(calls: Call | Iterable[Call], *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → SentTransactionResponse#

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

SentTransactionResponse.

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

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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 specified token.

Parameters:

token_address – Address of the ERC20 contract.
chain_id – Identifier of the Starknet chain used. If token_address is not specified it will be used to determine network’s payment token address. If token_address is provided, chain_id will be ignored.
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_v1(compiled_contract: str, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV1#

Create and sign declare transaction version 1.

Parameters:

compiled_contract – string containing a compiled Starknet contract. Supports old contracts.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed Declare transaction.

abstract async sign_declare_v2(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV2#

Create and sign declare transaction version 2 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.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeclareV2 transaction.

abstract async sign_declare_v3(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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_v1(class_hash: int, contract_address_salt: int, constructor_calldata: List[int] | None = None, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeployAccountV1#

Create and sign deploy account transaction version 1.

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.
max_fee – Max fee to be paid for deploying account 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 DeployAccount transaction.

abstract async sign_deploy_account_v3(class_hash: int, contract_address_salt: int, *, constructor_calldata: List[int] | None = None, nonce: int = 0, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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_v1(calls: Call | Iterable[Call], *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → InvokeV1#

Takes calls and creates signed Invoke.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Invoke created from the calls.

abstract async sign_invoke_v3(calls: Call | Iterable[Call], *, nonce: int | None = None, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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: TypedData) → 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.

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

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

Verify a signature of a TypedData dict on Starknet.

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.

__init__(*, address: int | str, client: Client, signer: BaseSigner | None = None, key_pair: KeyPair | None = None, chain: StarknetChainId | None = None)#

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 – ChainId of the chain used to create the default signer.

Example

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

async static deploy_account_v1(*, address: int | str, class_hash: int, salt: int, key_pair: KeyPair, client: Client, chain: StarknetChainId, constructor_calldata: List[int] | None = None, nonce: int = 0, max_fee: int | 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.

If using Client for MAINNET, GOERLI, SEPOLIA or SEPOLIA_INTEGRATION, this method will verify if the address balance is high enough to cover deployment costs.

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.
chain – Id of the Starknet chain used.
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.
max_fee – Max fee to be paid for deployment, must be less or equal to the amount of tokens prefunded.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

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

async static deploy_account_v3(*, address: int | str, class_hash: int, salt: int, key_pair: KeyPair, client: Client, chain: StarknetChainId, constructor_calldata: List[int] | None = None, nonce: int = 0, l1_resource_bounds: ResourceBounds | 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.
chain – Id of the Starknet chain used.
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.
l1_resource_bounds – Max amount and max price per unit of L1 gas (in Fri) 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, chain: StarknetChainId, constructor_calldata: List[int] | None = None, nonce: int = 0, l1_resource_bounds: ResourceBounds | 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_v1(calls: Call | Iterable[Call], *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → SentTransactionResponse#

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

SentTransactionResponse.

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

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

Takes calls and executes transaction.

Parameters:

calls – Single call or list of calls.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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.

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

Checks account’s balance of specified token.

Parameters:

token_address – Address of the ERC20 contract.
chain_id – Identifier of the Starknet chain used. If token_address is not specified it will be used to determine network’s payment token address. If token_address is provided, chain_id will be ignored.
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, chain_id: StarknetChainId | 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 sign_declare_v1(compiled_contract: str, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV1#

Create and sign declare transaction version 1.

Parameters:

compiled_contract – string containing a compiled Starknet contract. Supports old contracts.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed Declare transaction.

sign_declare_v1_sync(compiled_contract: str, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV1#: Synchronous version of the method.

async sign_declare_v2(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV2#

Create and sign declare transaction version 2 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.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Signed DeclareV2 transaction.

sign_declare_v2_sync(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareV2#: Synchronous version of the method.

async sign_declare_v3(compiled_contract: str, compiled_class_hash: int, *, nonce: int | None = None, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → DeclareV3#: Synchronous version of the method.

async sign_deploy_account_v1(class_hash: int, contract_address_salt: int, constructor_calldata: List[int] | None = None, *, nonce: int = 0, max_fee: int | None = None, auto_estimate: bool = False) → DeployAccountV1#

Create and sign deploy account transaction version 1.

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.
max_fee – Max fee to be paid for deploying account 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 DeployAccount transaction.

sign_deploy_account_v1_sync(class_hash: int, contract_address_salt: int, constructor_calldata: List[int] | None = None, *, nonce: int = 0, max_fee: int | None = None, auto_estimate: bool = False) → DeployAccountV1#: 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, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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, l1_resource_bounds: ResourceBounds | 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_v1(calls: Call | Iterable[Call], *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → InvokeV1#

Takes calls and creates signed Invoke.

Parameters:

calls – Single call or list of calls.
nonce – Nonce of the transaction.
max_fee – Max amount of Wei to be paid when executing transaction.
auto_estimate – Use automatic fee estimation, not recommend as it may lead to high costs.

Returns:

Invoke created from the calls.

sign_invoke_v1_sync(calls: Call | Iterable[Call], *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → InvokeV1#: Synchronous version of the method.

async sign_invoke_v3(calls: Call | Iterable[Call], *, nonce: int | None = None, l1_resource_bounds: ResourceBounds | 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.
l1_resource_bounds – Max amount and max price per unit of L1 gas 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, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → InvokeV3#: Synchronous version of the method.

sign_message(typed_data: TypedData) → 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.

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

Example

signature = account.sign_message(
    typed_data=TypedData(
        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},
    )
)

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

Verify a signature of a TypedData dict on Starknet.

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=TypedData(
        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.