Contract#

class starknet_py.contract.Contract#

Cairo contract’s model.

__init__(address: int | str, abi: list, provider: BaseAccount | Client, *, cairo_version: int = 0)#

Should be used instead of from_address when ABI is known statically.

Arguments provider and client are mutually exclusive and cannot be provided at the same time.

Parameters:

  • address – contract’s address.

  • abi – contract’s abi.

  • provider – BaseAccount or Client used to perform transactions.

  • cairo_version – Version of the Cairo in which contract is written.

Example

contract = Contract(
    address=0x123,
    abi=[
        {
            "inputs": [{"name": "amount", "type": "felt"}],
            "name": "increase_balance",
            "outputs": [],
            "type": "function",
        },
    ],
    provider=Account(
        address=0x321,
        client=FullNodeClient(node_url="your.node.url"),
        key_pair=KeyPair(12, 34),
        chain=StarknetChainId.GOERLI,
    ),
)
static compute_address(salt: int, compiled_contract: str, constructor_args: List | Dict | None = None, deployer_address: int = 0) → int#

Computes address for given contract.

Parameters:

  • salt – int

  • compiled_contract – String containing compiled contract.

  • constructor_args – A list or dict of arguments for the constructor.

  • deployer_address – Address of the deployer (if not provided default 0 is used).

Returns:

Contract’s address.

Example

address = Contract.compute_address(
    salt=1, compiled_contract=compiled_contract, constructor_args=[1, 2, [2]]
)
static compute_contract_hash(compiled_contract: str) → int#

Computes hash for given contract.

Parameters:

compiled_contract – String containing compiled contract.

Returns:

Class_hash of the contract.

async static declare_v1(account: BaseAccount, compiled_contract: str, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareResult#

Declares a contract.

Parameters:

  • account – BaseAccount used to sign and send declare transaction.

  • compiled_contract – String containing 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 recommended, as it may lead to high costs).

Returns:

DeclareResult instance.

static declare_v1_sync(account: BaseAccount, compiled_contract: str, *, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareResult#

Synchronous version of the method.

async static declare_v2(account: BaseAccount, compiled_contract: str, *, compiled_contract_casm: str | None = None, compiled_class_hash: int | None = None, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareResult#

Declares a contract.

Parameters:

  • account – BaseAccount used to sign and send declare transaction.

  • compiled_contract – String containing compiled contract.

  • compiled_contract_casm – String containing the content of the starknet-sierra-compile (.casm file).

  • compiled_class_hash – Hash of the compiled_contract_casm.

  • nonce – Nonce of the transaction.

  • max_fee – Max amount of Wei to be paid when executing transaction.

  • auto_estimate – Use automatic fee estimation (not recommended, as it may lead to high costs).

Returns:

DeclareResult instance.

static declare_v2_sync(account: BaseAccount, compiled_contract: str, *, compiled_contract_casm: str | None = None, compiled_class_hash: int | None = None, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeclareResult#

Synchronous version of the method.

async static declare_v3(account: BaseAccount, compiled_contract: str, *, compiled_contract_casm: str | None = None, compiled_class_hash: int | None = None, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → DeclareResult#

Declares a contract.

Parameters:

  • account – BaseAccount used to sign and send declare transaction.

  • compiled_contract – String containing compiled contract.

  • compiled_contract_casm – String containing the content of the starknet-sierra-compile (.casm file).

  • compiled_class_hash – Hash of the compiled_contract_casm.

  • 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 recommended, as it may lead to high costs).

Returns:

DeclareResult instance.

static declare_v3_sync(account: BaseAccount, compiled_contract: str, *, compiled_contract_casm: str | None = None, compiled_class_hash: int | None = None, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → DeclareResult#

Synchronous version of the method.

async static deploy_contract_v1(account: BaseAccount, class_hash: int | str, abi: List, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', cairo_version: int = 0, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True) → DeployResult#

Deploys a contract through Universal Deployer Contract.

Parameters:

  • account – BaseAccount used to sign and send deploy transaction.

  • class_hash – The class_hash of the contract to be deployed.

  • abi – An abi of the contract to be deployed.

  • constructor_args – a list or dict of arguments for the constructor.

  • deployer_address – Address of the UDC. Is set to the address of the default UDC (same address on mainnet/goerli/sepolia) by default. Must be set when using custom network other than ones listed above.

  • cairo_version – Version of the Cairo in which contract is written. By default, it is set to 0.

  • nonce – Nonce of the transaction.

  • max_fee – Max amount of Wei to be paid when executing transaction.

  • auto_estimate – Use automatic fee estimation (not recommended, as it may lead to high costs).

  • salt – Optional salt. Random value is selected if it is not provided.

  • unique – Determines if the contract should be salted with the account address.

Returns:

DeployResult instance.

static deploy_contract_v1_sync(account: BaseAccount, class_hash: int | str, abi: List, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', cairo_version: int = 0, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True) → DeployResult#

Synchronous version of the method.

async static deploy_contract_v3(account: BaseAccount, class_hash: int | str, abi: List, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', cairo_version: int = 1, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True) → DeployResult#

Deploys a contract through Universal Deployer Contract.

Parameters:

  • account – BaseAccount used to sign and send deploy transaction.

  • class_hash – The class_hash of the contract to be deployed.

  • abi – An abi of the contract to be deployed.

  • constructor_args – a list or dict of arguments for the constructor.

  • deployer_address – Address of the UDC. Is set to the address of the default UDC (same address on mainnet/goerli/sepolia) by default. Must be set when using custom network other than ones listed above.

  • cairo_version – Version of the Cairo in which contract is written. By default, it is set to 1.

  • 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 recommended, as it may lead to high costs).

  • salt – Optional salt. Random value is selected if it is not provided.

  • unique – Determines if the contract should be salted with the account address.

Returns:

DeployResult instance.

static deploy_contract_v3_sync(account: BaseAccount, class_hash: int | str, abi: List, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', cairo_version: int = 1, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True) → DeployResult#

Synchronous version of the method.

async static from_address(address: int | str, provider: BaseAccount | Client | None = None, proxy_config: bool | ProxyConfig = False) → Contract#

Fetches ABI for given contract and creates a new Contract instance with it. If you know ABI statically you should create Contract’s instances directly instead of using this function to avoid unnecessary API calls.

Raises:

  • ContractNotFoundError – when contract is not found.

  • TypeError – when given client’s get_class_by_hash method does not return abi.

  • ProxyResolutionError – when given ProxyChecks were not sufficient to resolve proxy’s implementation.

Parameters:

  • address – Contract’s address.

  • provider – BaseAccount or Client.

  • proxy_config –

    Proxy resolving config If set to True, will use default proxy checks starknet_py.proxy.proxy_check.OpenZeppelinProxyCheck and starknet_py.proxy.proxy_check.ArgentProxyCheck.

    If set to False, Contract.from_address() will not resolve proxies.

    If a valid starknet_py.contract_abi_resolver.ProxyConfig is provided, will use its values instead.

Returns:

an initialized Contract instance.

Example

address = 1 or 0x1 or "0x1"
contract = await Contract.from_address(address=address, provider=account)
# or if the contract is a proxy (read more about resolving proxies in the `Guide`)
config = True
contract = await Contract.from_address(
    address=address, provider=account, proxy_config=config
)
static from_address_sync(address: int | str, provider: BaseAccount | Client = None, proxy_config: bool | ProxyConfig = False) → Contract#

Synchronous version of the method.

property address: int#

Address of the contract.

property functions: Dict[str, ContractFunction]#
Returns:

All functions exposed from a contract.

ContractFunction#

class starknet_py.contract.ContractFunction#
async call(*args, block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None, **kwargs) → TupleDataclass#

Call contract’s function. *args and **kwargs are translated into Cairo calldata. The result is translated from Cairo data to python values. Equivalent of .prepare_call(*args, **kwargs).call().

Parameters:

  • block_hash – Block hash to perform the call to the contract at specific point of time.

  • block_number – Block number to perform the call to the contract at specific point of time.

Returns:

TupleDataclass representing call result.

Example

call_result = map_contract.functions["get"].call(key=10)
# or when call has to be done at specific block
call_result = map_contract.functions["get"].call(key=10, block_number="latest")
call_sync(*args, block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None, **kwargs) → TupleDataclass#

Synchronous version of the method.

static get_selector(function_name: str)#
Parameters:

function_name – Contract function’s name.

Returns:

A Starknet integer selector for this function inside the contract.

Example

selector = ContractFunction.get_selector("get")
async invoke_v1(*args, max_fee: int | None = None, auto_estimate: bool = False, nonce: int | None = None, **kwargs) → InvokeResult#

Invoke contract’s function. *args and **kwargs are translated into Cairo calldata. Equivalent of .prepare_invoke_v1(*args, **kwargs).invoke().

Parameters:

  • max_fee – Max amount of Wei to be paid when executing transaction.

  • auto_estimate – Use automatic fee estimation (not recommended, as it may lead to high costs).

  • nonce – Nonce of the transaction.

Returns:

InvokeResult.

Example

invoke_result = map_contract.functions["put"].invoke_v1(
    key=10, value=20, max_fee=int(1e15)
)
invoke_v1_sync(*args, max_fee: int | None = None, auto_estimate: bool = False, nonce: int | None = None, **kwargs) → InvokeResult#

Synchronous version of the method.

async invoke_v3(*args, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, nonce: int | None = None, **kwargs) → InvokeResult#

Invoke contract’s function. *args and **kwargs are translated into Cairo calldata. Equivalent of .prepare_invoke_v3(*args, **kwargs).invoke().

Parameters:

  • 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 recommended, as it may lead to high costs).

  • nonce – Nonce of the transaction.

Returns:

InvokeResult.

Example

invoke_result = map_contract.functions["put"].invoke_v3(
    key=10,
    value=20,
    l1_resource_bounds=ResourceBounds(
        max_amount=5000, max_price_per_unit=int(1e12)
    ),
)
invoke_v3_sync(*args, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, nonce: int | None = None, **kwargs) → InvokeResult#

Synchronous version of the method.

prepare_call(*args, **kwargs) → PreparedFunctionCall#

*args and **kwargs are translated into Cairo calldata. Creates a PreparedFunctionCall instance which exposes calldata for every argument and adds more arguments when calling methods.

Returns:

PreparedFunctionCall.

prepare_invoke_v1(*args, max_fee: int | None = None, **kwargs) → PreparedFunctionInvokeV1#

*args and **kwargs are translated into Cairo calldata. Creates a PreparedFunctionInvokeV1 instance which exposes calldata for every argument and adds more arguments when calling methods.

Parameters:

max_fee – Max amount of Wei to be paid when executing transaction.

Returns:

PreparedFunctionCall.

Example

prepared_function_call = map_contract.functions["put"].prepare_invoke_v1(
    key=10, value=20
)
prepare_invoke_v3(*args, l1_resource_bounds: ResourceBounds | None = None, **kwargs) → PreparedFunctionInvokeV3#

*args and **kwargs are translated into Cairo calldata. Creates a PreparedFunctionInvokeV3 instance which exposes calldata for every argument and adds more arguments when calling methods.

Parameters:

l1_resource_bounds – Max amount and max price per unit of L1 gas (in Fri) used when executing this transaction.

Returns:

PreparedFunctionInvokeV3.

Example

prepared_function_call = map_contract.functions["put"].prepare_invoke_v3(
    key=10, value=20
)

ContractData#

class starknet_py.contract.ContractData#

Basic data of a deployed contract.

static from_abi(address: int, abi: list, cairo_version: int = 0) → ContractData#

Create ContractData from ABI.

Parameters:

  • address – Address of the deployed contract.

  • abi – Abi of the contract.

  • cairo_version – Version of the Cairo in which contract is written.

Returns:

ContractData instance.

property parsed_abi: Abi | Abi | Abi#

Abi parsed into proper dataclass.

Returns:

Abi

PreparedFunctionCall#

class starknet_py.contract.PreparedFunctionCall#

Prepared date to call a contract function.

async call(block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → TupleDataclass#

Calls a method.

Parameters:

  • block_hash – Optional block hash.

  • block_number – Optional block number.

Returns:

TupleDataclass representing call result.

Example

response = await prepared_function_call.call(block_number="latest")
# or
response = await prepared_function_call.call()
async call_raw(block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → List[int]#

Calls a method without translating the result into python values.

Parameters:

  • block_hash – Optional block hash.

  • block_number – Optional block number.

Returns:

list of ints.

Example

raw_response = await prepared_function_call.call_raw(block_number="latest")
# or
raw_response = await prepared_function_call.call_raw()
call_raw_sync(block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → List[int]#

Synchronous version of the method.

call_sync(block_hash: str | None = None, block_number: int | Literal['pending', 'latest'] | None = None) → TupleDataclass#

Synchronous version of the method.

PreparedFunctionInvokeV1#

class starknet_py.contract.PreparedFunctionInvokeV1#

Prepared date to send an InvokeV1 transaction.

async estimate_fee(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None, *, nonce: int | None = None) → EstimatedFee#

Estimate fee for prepared function call.

Parameters:

  • block_hash – Estimate fee at specific block hash.

  • block_number – Estimate fee at given block number (or “latest” / “pending” for the latest / pending block), default is “pending”.

  • nonce – Nonce of the transaction.

Returns:

Estimated amount of the transaction cost, either in Wei or Fri associated with executing the specified transaction.

estimate_fee_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None, *, nonce: int | None = None) → EstimatedFee#

Synchronous version of the method.

async invoke(max_fee: int | None = None, auto_estimate: bool = False, *, nonce: int | None = None) → InvokeResult#

Send an Invoke transaction version 1 for the prepared data.

Parameters:

  • max_fee – Max amount of Wei to be paid when executing transaction.

  • auto_estimate – Use automatic fee estimation (not recommended, as it may lead to high costs).

  • nonce – Nonce of the transaction.

Returns:

InvokeResult.

Example

invoke_result = await prepared_function_call.invoke(max_fee=int(1e15))
# max_fee can be estimated automatically
invoke_result = await prepared_function_call.invoke(auto_estimate=True)
# or if max_fee was specified in prepared_function_call
invoke_result = await prepared_function_call.invoke()
invoke_sync(max_fee: int | None = None, auto_estimate: bool = False, *, nonce: int | None = None) → InvokeResult#

Synchronous version of the method.

PreparedFunctionInvokeV3#

class starknet_py.contract.PreparedFunctionInvokeV3#

Prepared date to send an InvokeV3 transaction.

async estimate_fee(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None, *, nonce: int | None = None) → EstimatedFee#

Estimate fee for prepared function call.

Parameters:

  • block_hash – Estimate fee at specific block hash.

  • block_number – Estimate fee at given block number (or “latest” / “pending” for the latest / pending block), default is “pending”.

  • nonce – Nonce of the transaction.

Returns:

Estimated amount of the transaction cost, either in Wei or Fri associated with executing the specified transaction.

estimate_fee_sync(block_hash: int | str | Literal['pending', 'latest'] | None = None, block_number: int | Literal['pending', 'latest'] | None = None, *, nonce: int | None = None) → EstimatedFee#

Synchronous version of the method.

async invoke(l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, *, nonce: int | None = None) → InvokeResult#

Send an Invoke transaction version 3 for the prepared data.

Parameters:

  • 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 recommended, as it may lead to high costs).

  • nonce – Nonce of the transaction.

Returns:

InvokeResult.

Example

invoke_result = await prepared_function_call.invoke(
    l1_resource_bounds=ResourceBounds(max_amount=5000, max_price_per_unit=int(1e12))
)
# l1_resource_bounds can be estimated automatically
invoke_result = await prepared_function_call.invoke(auto_estimate=True)
# or if l1_resource_bounds was specified in prepared_function_call
invoke_result = await prepared_function_call.invoke()
invoke_sync(l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False, *, nonce: int | None = None) → InvokeResult#

Synchronous version of the method.

InvokeResult#

class starknet_py.contract.InvokeResult#

Result of the Invoke transaction.

contract: ContractData = None#

Additional information about the Contract that made the transaction.

invoke_transaction: InvokeV1 | InvokeV3 = None#

A InvokeTransaction instance used.

DeployResult#

class starknet_py.contract.DeployResult#

Result of the contract deployment.

deployed_contract: Contract = None#

A Contract instance representing the deployed contract.

DeclareResult#

class starknet_py.contract.DeclareResult#

Result of the Declare transaction.

async deploy_v1(*, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeployResult#

Deploys a contract.

Parameters:

  • deployer_address – Address of the UDC. Is set to the address of the default UDC (same address on mainnet/goerli/sepolia) by default. Must be set when using custom network other than ones listed above.

  • salt – Optional salt. Random value is selected if it is not provided.

  • unique – Determines if the contract should be salted with the account address.

  • constructor_args – a list or dict of arguments for the constructor.

  • nonce – Nonce of the transaction with call to deployer.

  • max_fee – Max amount of Wei to be paid when executing transaction.

  • auto_estimate – Use automatic fee estimation (not recommended, as it may lead to high costs).

Returns:

DeployResult instance.

deploy_v1_sync(*, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, max_fee: int | None = None, auto_estimate: bool = False) → DeployResult#

Synchronous version of the method.

async deploy_v3(*, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → DeployResult#

Deploys a contract.

Parameters:

  • deployer_address – Address of the UDC. Is set to the address of the default UDC (same address on mainnet/goerli/sepolia) by default. Must be set when using custom network other than ones listed above.

  • salt – Optional salt. Random value is selected if it is not provided.

  • unique – Determines if the contract should be salted with the account address.

  • constructor_args – a list or dict of arguments for the constructor.

  • nonce – Nonce of the transaction with call to deployer.

  • 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 recommended, as it may lead to high costs).

Returns:

DeployResult instance.

deploy_v3_sync(*, deployer_address: int | str = '0x041a78e741e5aF2fEc34B695679bC6891742439f7AFB8484Ecd7766661aD02BF', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, l1_resource_bounds: ResourceBounds | None = None, auto_estimate: bool = False) → DeployResult#

Synchronous version of the method.

class_hash: int = None#

Class hash of the declared contract.

compiled_contract: str = None#

Compiled contract that was declared.

declare_transaction: DeclareV1 | DeclareV2 | DeclareV3 = None#

A Declare transaction that has been sent.