Accounts

class ape_starknet.accounts.BaseStarknetAccount

Base Starknet Account

property address_int: int

The account’s address to as an integer.

call(txn: TransactionAPI, send_everything: bool = False, **signer_options) → ReceiptAPI

Make a transaction call.

Raises:

  • AccountsError – When the nonce is invalid or the sender does not have enough funds.

  • TransactionError – When the required confirmations are negative.

  • SignatureError – When the user does not sign the transaction.

Parameters:

  • txn (TransactionAPI) – An invoke-transaction.

  • send_everything (bool) – True will send the difference from balance and fee. Defaults to False.

  • **signer_options – Additional kwargs given to the signer to modify the signing operation.

Returns:

ReceiptAPI

check_signature(data: Union[int, List[int], TransactionAPI, StarknetSignableMessage], signature: Optional[Tuple[int, int]] = None) → bool

Verify a message or transaction was signed by this account.

Parameters:

  • data (Union[SignableMessage, TransactionAPI]) – # noqa: E501 The message or transaction to verify.

  • signature (Optional[MessageSignature]) – The signature to check.

Returns:

True if the data was signed by this account. False otherwise.

Return type:

bool

property class_hash: int

The class hash of the contract.

property constructor_calldata: List[Any]

The list representing the function parameters.

declare(contract_type: ContractType)

Declares a contract.

Parameters:

contract_type (ContractType) – Type of contract.

property default_address: ChecksumAddress

The contract address if you are to use the default salt for the account.

property default_address_int: int

The contract address (int) calculated from the class hash, root contract address salt, and constructor calldata.

deploy(contract: Union[ContractContainer, BaseStarknetAccount], *args, publish: bool = False, **kwargs) → Union[ContractInstance, ReceiptAPI]

Create a smart contract on the blockchain. The smart contract must compile before deploying and a provider must be active.

Parameters:

  • contract (ContractContainer) – The type of contract to deploy.

  • publish (bool) – Set to True to attempt explorer contract verification. Defaults to False.

Returns:

An instance of the deployed contract.

Return type:

ContractInstance

deploy_account(funder: Optional[BaseStarknetAccount] = None, salt: Optional[int] = None, calldata: Optional[List] = None) → ReceiptAPI

Deploys this account.

Parameters:

  • funder (Optional[BaseStarknetAccount]) – An account to use to assist in funding the deployment. Only requests transfer if needed.

  • salt (Optional[int]) – Contract address salt. Needed if wanting to deploy to a different address.

  • calldata (Optional[List]) – Custom calldata to provide. Defaults to the calldata in the keyfile, if found. Else, uses what is expected per the class hash, such as the public key.

Returns:

The receipt from the DeployAccountTransaction.

Return type:

ReceiptAPI

property deployed: bool

Checks to see if the account is deployed on the network.

Parameters:

network_name (Optional[str]) – Name of network that address is deployed on.

Returns:

bool

property deployments: List[StarknetAccountDeployment]

List of deployments

Returns:

List[StarknetAccountDeployment]

get_contract_address(salt: Optional[int] = None) → int

Calculate a contract address for the given account’s salt, class hash, and constructor data.

Parameters:

salt (Optional[salt]) – Salt to use. Defaults to the root account salt. Note: accounts use a root default salt to have consistent addresses accross different networks.

Returns:

The contract address.

Return type:

int

get_fee_estimate(txn: TransactionAPI) → int

Get the estimate fee cost for transaction.

Parameters:

txn (TransactionAPI) – Transaction

Returns:

Value of estimated gas cost.

Return type:

int

handle_signature(sign_result, txn: TransactionAPI) → TransactionAPI

Checks and assigns signature to transaction.

Parameters:

  • sign_result – The results of the attempt to sign the transaction.

  • txn (TransactionAPI) – Transaction

Returns:

Transaction with signature

Return type:

TransactionAPI

prepare_transaction(txn: TransactionAPI) → TransactionAPI

Set default values on a transaction.

Raises:

  • AccountsError – When the account cannot afford the transaction or the nonce is invalid.

  • TransactionError – When given negative required confirmations.

Parameters:

txn (TransactionAPI) – The transaction to prepare.

Returns:

TransactionAPI

property public_key: str

The public key of the account.

property salt: int

The salt is used to determine the contract address. If you change the salt but keep the class hash and calldata the same, you will get a new address. To keep addresses consistent across networks, a single salt value exists at the root of an account. However, when deploying an account on live networks, you will have the option to change the salt for each deployment.

transfer(account: Union[str, ChecksumAddress, BaseAddress], value: Optional[Union[str, int]] = None, data: Optional[Union[bytes, str]] = None, **kwargs) → ReceiptAPI

Send funds to an account.

Parameters:

  • account (str) – The account to send funds to.

  • value (str) – The amount to send.

  • data (str) – Extra data to include in the transaction.

Returns:

ReceiptAPI

class ape_starknet.accounts.StarknetAccountContainer(*, data_folder: Path, account_type: Type[AccountAPI], ephemeral_accounts: Dict[str, Dict] = {}, cached_accounts: Dict[str, StarknetKeyfileAccount] = {})

Starknet Account Container

property accounts: Iterator[AccountAPI]

Iterate over available accounts.

Returns:

Iterator[AccountAPI]

property aliases: Iterator[str]

Iterate over all available aliases.

Returns:

Iterator[str]

cached_accounts: Dict[str, StarknetKeyfileAccount]

Accounts created in a live network that persist in key-files.

create_account(alias: str, class_hash: int = 3146761231686369291210245479075933162526514193311043598334639064078158562617, salt: Optional[int] = None, private_key: Optional[str] = None, constructor_calldata: Optional[List[int]] = None, allow_local_file_store: bool = False) → BaseStarknetAccount

Create an account within the parameters given or generated.

NOTE: Defaults to True for all non-local networks and False for local networks.

Parameters:

  • alias (str) – A shortened-name for quicker access to the account.

  • class_hash (int) – A hash chain of the definition of the class.

  • salt (Optional[int]) – Contract address salt. Needed if wanting to deploy to a different address.

  • private_key (Optional[str]) – Set private key manually or leave blank to generate one randomly.

  • constructor_calldata (Optional[List[int]]) – List representing the function parameters.

  • allow_local_file_store (bool) – Allow for account to be stored on local file.

Returns:

BaseStarknetAccount

delete_account(alias: str, address: Optional[Union[ChecksumAddress, int]] = None, networks: Optional[Union[str, List[str]]] = None, leave_unlocked: Optional[bool] = None)

Delete an account.

Parameters:

  • alias (str) – A shortened-name for quicker access to the account.

  • address (Optional[Union[AddressType, int]]) – The address of the account to be deleted Defaults to None.

  • networks (Optional[Union[str, List[str]]]) – The network(s) for the accounts to be deleted from. Defaults to None.

  • leave_unlocked (bool) – Option to leave account unlocked for future interactions. Defaults to None.

ephemeral_accounts: Dict[str, Dict]

Local-network accounts that do not persist.

get_account(address: Union[ChecksumAddress, int]) → BaseStarknetAccount

Get account based on address.

Parameters:

address (Union[AddressType, int]) – Address of the account.

Returns:

BaseStarknetAccount

import_account(alias: str, class_hash: int, private_key: Union[int, str], deployments: Optional[List[StarknetAccountDeployment]] = None, constructor_calldata: Optional[List] = None, salt: Optional[int] = None, allow_local_file_store: bool = False) → BaseStarknetAccount

Import deployed starknet account.

Parameters:

  • alias (str) – A shortened-name for quicker access to the account.

  • class_hash (int) – Class hash of contract.

  • private_key (Union[int, str]) – Private key for account.

  • deployments (Optional[List[StarknetAccountDeployment]]) – The network deployment status of the account.

  • constructor_calldata (Optional[List[int]]) – List representing the function parameters.

  • salt (Optional[int]) – Contract address salt. Needed if wanting to deploy to a different address.

  • allow_local_file_store (bool) – Allows to store in local file store.

Returns:

BaseStarknetAccount

load(alias: str) → BaseStarknetAccount

Loads an account based on alias.

Parameters:

alias (str) – A shortened-name for quicker access to the account.

Returns:

BaseStarknetAccount

property provider_config: ProviderConfig

Provider network configuration

Returns:

ProviderConfig

property test_accounts: List[StarknetDevelopmentAccount]

Makes a list of test accounts.

Returns:

List[StarknetDevelopmentAccount]

class ape_starknet.accounts.StarknetAccountDeployment(*, network_name: str, contract_address: ChecksumAddress, salt: Optional[int] = None)

Starknet Account Deployment

class ape_starknet.accounts.StarknetDevelopmentAccount(*, address: Optional[ChecksumAddress] = None, private_key: str, public_key: str, class_hash: int = 3146761231686369291210245479075933162526514193311043598334639064078158562617, constructor_calldata: Optional[List[Any]] = None, custom_salt: Optional[int] = None, is_deployed: bool = False)

Starknet Development Account

add_deployment(network_name: str, contract_address: int, salt: int)

Add deployment if network is connected to local network.

Parameters:

  • network_name (str) – Name of connected network

  • contract_address (int) – Address for account.

  • salt (int) – Contract address salt. Needed if wanting to deploy to a different address.

Raises:

ValueError – When not connected to the local network.

property address: ChecksumAddress

The address of this account. Subclasses must override and provide this value.

property class_hash: int

The class hash of the contract.

property constructor_calldata: List[Any]

The list representing the function parameters.

contract_address: Optional[ChecksumAddress]

The contract address of the account. If not set, calculates it based on other properties.

property deployments: List[StarknetAccountDeployment]

Gets list of deployments.

Returns:

List[StarknetAccountDeployment]

private_key: str

The account’s private key.

pub_key: str

The public key of the account. Aliased from public_key because that is a @property in the base class.

property public_key: str

The public key of the account.

property salt: int

The salt is used to determine the contract address. If you change the salt but keep the class hash and calldata the same, you will get a new address. To keep addresses consistent across networks, a single salt value exists at the root of an account. However, when deploying an account on live networks, you will have the option to change the salt for each deployment.

sign_message(msg: StarknetSignableMessage) → Optional[Tuple[int, int]]

Sign a message.

Parameters:

msg (SignableMessage) – The message to sign. See these docs # noqa: E501 for more type information on this type.

Returns:

The signed message.

Return type:

MessageSignature (optional)

sign_transaction(txn: TransactionAPI, **signer_options) → Optional[TransactionAPI]

Sign a transaction.

Parameters:

  • txn (TransactionAPI) – The transaction to sign.

  • **signer_options – Additional kwargs given to the signer to modify the signing operation.

Returns:

A signed transaction.

The TransactionAPI returned by this method may not correspond to txn given as input, however returning a properly-formatted transaction here is meant to be executed. Returns None if the account does not have a transaction it wishes to execute.

Return type:

TransactionAPI (optional)

class ape_starknet.accounts.StarknetKeyfileAccount(*, key_file_path: Path, locked: bool = True)

Starknet Keyfile Account

property account_data: Dict

Get the account data of a single account.

add_deployment(network_name: str, contract_address: int, salt: int, leave_unlocked: Optional[bool] = None)

Add deployment status for account.

Parameters:

  • network_name (str) – Name of connected network.

  • contract_address (str) – Contract address for account.

  • salt (int) – Contract address salt. Needed if wanting to deploy to a different address.

  • leave_unlocked (Optional[bool]) – Option to leave account unlocked after deployment.

property address: ChecksumAddress

The address of this account. Subclasses must override and provide this value.

property alias: Optional[str]

A shortened-name for quicker access to the account.

change_password(leave_unlocked: Optional[bool] = None)

Change password for account. NOTE: User must enter passphrase even if unlocked

Parameters:

leave_unlocked (Optional[bool]) – Option to leave account unlocked after changing password.

property class_hash: int

The class hash of the contract.

property constructor_calldata: List[Any]

The list representing the function parameters.

delete(address: Optional[Union[ChecksumAddress, int]] = None, networks: Optional[Union[str, List[str]]] = None, leave_unlocked: Optional[bool] = None)

Delete an account.

Parameters:

  • address (Optional[Union[AddressType, int]]) – Address of account. Defaults to None.

  • networks (Optional[Union[str, List[str]]]) – List of networks to delete account from. Defaults to None.

  • leave_unlocked (Optional[bool]) – Option to leave account unlocked. Defaults to None.

property deployed: bool

Checks to see if the account is deployed on the network.

Parameters:

network_name (Optional[str]) – Name of network that address is deployed on.

Returns:

bool

property deployments: List[StarknetAccountDeployment]

List of deployments

Returns:

List[StarknetAccountDeployment]

classmethod from_file(path: Path)

Retrieve account from file.

Parameters:

path (Path) – Location of file where account is saved.

get_deployment(network_name: str) → Optional[StarknetAccountDeployment]

Gets deployment status from the network.

Parameters:

network_name (str) – Name of network being looked at for deployment status.

Returns:

Optional[StarknetAccountDeployment]

property keyfile_data: Dict

Keyfile data for accounts saved as a dictionary.

lock()

Lock the account and removes cached key and passphrase.

property nonce: int

The number of transactions associated with the address.

prepare_transaction(txn: TransactionAPI) → TransactionAPI

Set default values on a transaction.

Raises:

  • AccountsError – When the account cannot afford the transaction or the nonce is invalid.

  • TransactionError – When given negative required confirmations.

Parameters:

txn (TransactionAPI) – The transaction to prepare.

Returns:

TransactionAPI

property public_key: str

The public key of the account.

property salt: int

The salt is used to determine the contract address. If you change the salt but keep the class hash and calldata the same, you will get a new address. To keep addresses consistent across networks, a single salt value exists at the root of an account. However, when deploying an account on live networks, you will have the option to change the salt for each deployment.

set_autosign(enabled: bool, passphrase: Optional[str] = None)

Unlock keyfile accounts with set autosign message.

Parameters:

  • enabled (bool) – Set True/False to enable autosign for account.

  • passphrase (Optional[str]) – Set passphrase to unlock account if password exists.

sign_message(msg: StarknetSignableMessage) → Optional[Tuple[int, int]]

Sign a message.

Parameters:

msg (SignableMessage) – The message to sign. See these docs # noqa: E501 for more type information on this type.

Returns:

The signed message.

Return type:

MessageSignature (optional)

sign_transaction(txn: TransactionAPI, **signer_optins: Any) → Optional[TransactionAPI]

Sign a transaction.

Parameters:

  • txn (TransactionAPI) – The transaction to sign.

  • **signer_options – Additional kwargs given to the signer to modify the signing operation.

Returns:

A signed transaction.

The TransactionAPI returned by this method may not correspond to txn given as input, however returning a properly-formatted transaction here is meant to be executed. Returns None if the account does not have a transaction it wishes to execute.

Return type:

TransactionAPI (optional)

unlock(prompt: Optional[str] = None, passphrase: Optional[str] = None)

Unlock an account.

Parameters:

  • prompt (Optional[str]) – Prompt message. Defaults to None.

  • passphrase (Optional[str]) – Passphrase that is used to unlock the account. Defaults to None.