Contract#

class starknet_py.contract.Contract#

Cairo contract’s model.

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

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="https://your.node.url"),
        key_pair=KeyPair(12, 34),
        chain=StarknetChainId.SEPOLIA,
    ),
    cairo_version=0,
)
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, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: 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.

  • resource_bounds – Resource limits (L1 and L2) used when executing this transaction.

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

  • tip – The tip amount to be added to the transaction fee.

  • auto_estimate_tip – Use automatic tip estimation. Using this option may lead to higher costs.

Returns:

DeclareResult instance.

Example

# here `contract` is a dict containing sierra and casm artifacts
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)),
)
declare_result = await Contract.declare_v3(
    account,
    compiled_contract=contract["sierra"],
    compiled_contract_casm=contract["casm"],
    resource_bounds=resource_bounds,
)
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, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: bool = False) → DeclareResult#

Synchronous version of the method.

async static deploy_contract_v3(account: BaseAccount, class_hash: int | str, abi: List | None = None, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x02ceed65a4bd731034c01113685c831b01c15d7d432f71afb1cf1634b53a2125', cairo_version: int = 1, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True, tip: int | None = None, auto_estimate_tip: bool = False) → 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/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.

  • resource_bounds – Resource limits (L1 and L2) 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.

  • tip – The tip amount to be added to the transaction fee.

  • auto_estimate_tip – Use automatic tip estimation. Using this option may lead to higher costs.

Returns:

DeployResult instance.

Example

abi = create_sierra_compiled_contract(
    compiled_contract=compiled_contract
).parsed_abi
resource_bounds = ResourceBoundsMapping(
    l1_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
    l2_gas=ResourceBounds(max_amount=int(1e10), max_price_per_unit=int(1e17)),
    l1_data_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
)
deploy_result = await Contract.deploy_contract_v3(
    class_hash=class_hash,
    account=account,
    abi=abi,
    resource_bounds=resource_bounds,
)
static deploy_contract_v3_sync(account: BaseAccount, class_hash: int | str, abi: List | None = None, constructor_args: List | Dict | None = None, *, deployer_address: int | str = '0x02ceed65a4bd731034c01113685c831b01c15d7d432f71afb1cf1634b53a2125', cairo_version: int = 1, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, salt: int | None = None, unique: bool = True, tip: int | None = None, auto_estimate_tip: bool = False) → 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['l1_accepted', 'pre_confirmed', 'latest'] | None = None, **kwargs) → TupleDataclass | Tuple#

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['l1_accepted', 'pre_confirmed', 'latest'] | None = None, **kwargs) → TupleDataclass | Tuple#

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_v3(*args, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: bool = False, nonce: int | None = None, proof_facts: List[int] | None = None, proof: str | 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:

  • resource_bounds – Resource limits (L1 and L2) used when executing this transaction.

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

  • tip – The tip amount to be added to the transaction fee.

  • auto_estimate_tip – Use automatic tip estimation. Using this option may lead to higher costs.

  • nonce – Nonce of the transaction.

  • proof_facts – Optional proof facts for the transaction.

  • proof – Optional base64-encoded proof for the transaction.

Returns:

InvokeResult.

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)),
)
invoke_result = map_contract.functions["put"].invoke_v3(
    key=10,
    value=20,
    resource_bounds=resource_bounds,
)
invoke_v3_sync(*args, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: bool = False, nonce: int | None = None, proof_facts: List[int] | None = None, proof: str | 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_v3(*args, resource_bounds: ResourceBoundsMapping | None = None, tip: int | 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:

  • resource_bounds – Resource limits (L1 and L2) used when executing this transaction.

  • tip – The tip amount to be added to the transaction fee.

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 = 1) → 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['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → TupleDataclass | Tuple#

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['l1_accepted', 'pre_confirmed', '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['l1_accepted', 'pre_confirmed', 'latest'] | None = None) → List[int]#

Synchronous version of the method.

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

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['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', '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” / “pre_confirmed” for the latest / pre_confirmed block), default is “pre_confirmed”.

  • 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['l1_accepted', 'pre_confirmed', 'latest'] | None = None, block_number: int | Literal['l1_accepted', 'pre_confirmed', 'latest'] | None = None, *, nonce: int | None = None) → EstimatedFee#

Synchronous version of the method.

async invoke(resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, *, nonce: int | None = None, tip: int | None = None, auto_estimate_tip: bool = False, proof_facts: List[int] | None = None, proof: str | None = None) → InvokeResult#

Send an Invoke transaction version 3 for the prepared data.

Parameters:

  • resource_bounds – Resource limits (L1 and L2) 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.

  • tip – The tip amount to be added to the transaction fee.

  • auto_estimate_tip – Use automatic tip estimation. Using this option may lead to higher costs.

  • proof_facts – Optional proof facts for the transaction.

  • proof – Optional base64-encoded proof for the transaction.

Returns:

InvokeResult.

Example

resource_bounds = ResourceBoundsMapping(
    l1_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
    l2_gas=ResourceBounds(max_amount=int(1e10), max_price_per_unit=int(1e20)),
    l1_data_gas=ResourceBounds(max_amount=int(1e5), max_price_per_unit=int(1e13)),
)
invoke_result = await prepared_function_call.invoke(resource_bounds=resource_bounds)
# resource_bounds can be estimated automatically
invoke_result = await prepared_function_call.invoke(auto_estimate=True)
# or if resource_bounds was specified in prepared_function_call
invoke_result = await prepared_function_call.invoke()
invoke_sync(resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, *, nonce: int | None = None, tip: int | None = None, auto_estimate_tip: bool = False, proof_facts: List[int] | None = None, proof: str | 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: 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_v3(*, deployer_address: int | str = '0x02ceed65a4bd731034c01113685c831b01c15d7d432f71afb1cf1634b53a2125', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: 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/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.

  • resource_bounds – Resource limits (L1 and L2) used when executing this transaction.

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

  • tip – The tip amount to be added to the transaction fee.

  • auto_estimate_tip – Use automatic tip estimation. Using this option may lead to higher costs.

Returns:

DeployResult instance.

deploy_v3_sync(*, deployer_address: int | str = '0x02ceed65a4bd731034c01113685c831b01c15d7d432f71afb1cf1634b53a2125', salt: int | None = None, unique: bool = True, constructor_args: List | Dict | None = None, nonce: int | None = None, resource_bounds: ResourceBoundsMapping | None = None, auto_estimate: bool = False, tip: int | None = None, auto_estimate_tip: 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: DeclareV3 = None#

A Declare transaction that has been sent.