module

neo3.api.wrappers

Convenience wrappers for calling smart contracts via RPC.

The most specific wrappers in this module are for NEOs native contracts NeoToken, GasToken, PolicyContract and RoleManagement. The ContractManagement and Ledger contracts are not wrapped. See the FAQ for the reasons.

One step up are wrappers for contracts following the NEP-17 Token standard (NEP17Contract) and NEP-11 NFT standard (NEP11DivisibleContract & NEP11NonDivisibleContract). As last resort there is the GenericContract which can be used for calling arbitrary functions on arbitrary contracts.

Obtaining the execution results of the functions on the wrapped contracts is done through one of 3 methods on the ChainFacade class

1. test_invoke() - does not persist to chain. Costs no gas.
2. invoke() - does persist to chain. Requires signing and costs gas.
3. estimate_gas() - does not persist to chain. Costs no gas.

Example

facade = ChainFacade.node_provider_mainnet()

neo = NeoToken()

result = await facade.test_invoke(neo.candidates_registered())

Classes

• Candidate — Container for holding consensus candidate voting results.
• ChainFacade — The gateway to the network.
• ContractMethodResult — A helper class around the script (VM opcodes) to be executed which allows to forward the annotated return type(ContractMethodResult[T]) of the annotated function f to a consumer function, without having to actually return an instance of T in the implementation of f.
• GasToken — Wrapped GAS token contract.
• GenericContract — Generic class to call arbitrary methods on a smart contract.
• InvokeReceipt — Transaction submission results.
• NEP11DivisibleContract — Base class for divisible NFTs.
• NEP11NonDivisibleContract — Base class for non-divisible NFTs.
• NEP17Contract — Base class for calling NEP-17 compliant smart contracts.
• NeoToken — Wrapped NEO token contract.
• PolicyContract — Wrapper around the native contract that manages system policies.
• RoleContract — Wrapper around the native Role management contract.

class

neo3.api.wrappers.Candidate(public_key, votes)

Container for holding consensus candidate voting results.

Attributes

• address — NEO address of the candidate.
• public_key — public key of the candidate.
• votes — number of votes the candidate has.

class

neo3.api.wrappers.ChainFacade(rpc_host, receipt_retry_delay=None, receipt_timeout=None)

The gateway to the network.

Abstracts away the logic for talking to the data provider (NodeRPC only atm).

Methods

• add_signer(func, signer) — Add a Signer which will automatically be included when the various invoke functions.
• estimate_gas(f, signers) (int) — Estimate the gas price for calling the contract method.
• invoke(f, signers, network_fee, system_fee, append_network_fee, append_system_fee) (InvokeReceipt) — Call a contract method and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.
• invoke_fast(f, signers, network_fee, system_fee, append_network_fee, append_system_fee) (UInt256) — Call a contract method and persist results on the chain. Costs GAS.
• invoke_multi(f, signers, network_fee, system_fee, append_network_fee, append_system_fee, _post_processing) (Sequence) — Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.
• invoke_multi_fast(f, signers, network_fee, system_fee, append_network_fee, append_system_fee) (UInt256) — Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Does not wait for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.
• invoke_multi_raw(f, signers, network_fee, system_fee, append_network_fee, append_system_fee) (Sequence) — Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Do not wait for tx to be included in a block. Do not post process the execution results according to the post-processing function of f if present.
• invoke_raw(f, signers, network_fee, system_fee, append_network_fee, append_system_fee) (InvokeReceipt) — Call a contract method and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Does not post processes the execution results.
• test_invoke(f, signers) (ReturnType) — Call a contract method in read-only mode.This does not persist any state on the actual chain and therefore does not require signing or paying GAS.
• test_invoke_multi(f, signers) (Sequence) — Call all contract methods in one go (concurrently) and return the list of results.
• test_invoke_raw(f, signers) (ExecutionResult) — Call a contract method in read-only mode.This does not persist any state on the actual chain and therefore does not require signing or paying GAS. Does not post process the execution results.
• node_provider_mainnet() — Create a facade pre-configured to N3 MainNet.
• node_provider_testnet() — Create a facade pre-configured to N3 TestNet.

method

add_signer(func, signer)

Add a Signer which will automatically be included when the various invoke functions.

method

estimate_gas(f, signers=None) → int

Estimate the gas price for calling the contract method.

method

invoke(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0)

Call a contract method and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.

Parameters

• f (ContractMethodResult) — function to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (InvokeReceipt)

A transaction receipt. The state field of the receipt indicates if the transaction script executedsuccessfully. The remaining fields provide additional information such as notifications that happened in the contract.

See Also

invoke_fast() - does not wait for a receipt.invoke_raw() - does not wait for a transaction receipt, does not perform post-processing of the execution results.

method

invoke_fast(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0)

Call a contract method and persist results on the chain. Costs GAS.

Parameters

• f (ContractMethodResult) — function to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (UInt256)

a transaction ID if accepted by the network. Acceptance is does not guarantee successful execution.Acceptance means there are no transaction format errors. Use invoke() to wait for a receipt. The state field of the receipt indicates if the transaction script executed successfully.

See Also

invoke() - waits for a transaction receipt, performs post-processing of the execution results.invoke_raw() - does not wait for a transaction receipt, does not perform post-processing of the execution results.

method

invoke_multi(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0, _post_processing=True)

Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.

Parameters

• f (list) — list of functions to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (Sequence)

a list with the results of all exected functions.

See Also

test_invoke_multi - free equivalent for read only operations or testing.invoke_multi_fast - does not wait for a receipt. invoke_multi_raw - does not wait for a transaction receipt, does not perform post-processing of the execution results.

method

invoke_multi_fast(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0)

Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Does not wait for tx to be included in a block. Automatically post processes the execution results according to the post-processing function of f if present.

Parameters

• f (list) — list of functions to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (UInt256)

a transaction ID if accepted by the network. Acceptance is does not guarantee successful execution.Acceptance means there are no transaction format errors. Use invoke() to wait for a receipt. The state field of the receipt indicates if the transaction script executed successfully.

See Also

test_invoke_fast - free equivalent for read only operations or testing.invoke_multi - waits for a transaction receipt, performs post-processing of the execution results. invoke_multi_raw - does not wait for a transaction receipt, does not perform post-processing of the execution results.

method

invoke_multi_raw(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0)

Call all contract methods (concatenated) in one go and persist results on the chain. Costs GAS.Do not wait for tx to be included in a block. Do not post process the execution results according to the post-processing function of f if present.

Parameters

• f (list) — list of functions to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (Sequence)

a list with the results of all exected functions.

See Also

test_invoke_raw - free equivalent for read only operations or testing.invoke_multi - waits for a transaction receipt, performs post-processing of the execution results. invoke_multi_fast - does not wait for a receipt.

method

invoke_raw(f, signers=None, network_fee=0, system_fee=0, append_network_fee=0, append_system_fee=0)

Call a contract method and persist results on the chain. Costs GAS.Waits for tx to be included in a block. Does not post processes the execution results.

Parameters

• f (ContractMethodResult) — function to call.
• signers (Optional, optional) — manually set the list of signers.
• network_fee (int, optional) — manually set the network fee.
• system_fee (int, optional) — manually set the system fee.
• append_network_fee (int, optional) — increase the calculated network fee with this amount.
• append_system_fee (int, optional) — increase the calculated system fee with this amount.

Returns (InvokeReceipt)

A transaction receipt. The state field of the receipt indicates if the transaction script executedsuccessfully. The remaining fields provide additional information such as notifications that happened in the contract.

See Also

invoke() - waits for a transaction receipt, performs post-processing of the execution resultsinvoke_fast() - does not wait for a receipt.

classmethod

node_provider_mainnet()

Create a facade pre-configured to N3 MainNet.

classmethod

node_provider_testnet()

Create a facade pre-configured to N3 TestNet.

method

test_invoke(f, signers=None) → ReturnType

Call a contract method in read-only mode.This does not persist any state on the actual chain and therefore does not require signing or paying GAS.

Parameters

• f (ContractMethodResult) — function to call.
• signers (Optional, optional) — manually set the list of signers.

See Also

invoke() - persists state.

method

test_invoke_multi(f, signers=None) → Sequence

Call all contract methods in one go (concurrently) and return the list of results.

Parameters

• f (list) — list of functions to call.
• signers (Optional, optional) — manually set the list of signers.

See Also

invoke_multi() - persists state.

method

test_invoke_raw(f, signers=None) → ExecutionResult

Call a contract method in read-only mode.This does not persist any state on the actual chain and therefore does not require signing or paying GAS. Does not post process the execution results.

Parameters

• f (ContractMethodResult) — function to call.
• signers (Optional, optional) — manually set the list of signers.

See Also

invoke_raw() - persists state.

class

neo3.api.wrappers.ContractMethodResult(script, execution_processor=None, return_count=1)

Bases

typing.Generic

A helper class around the script (VM opcodes) to be executed which allows to forward the annotated return type(ContractMethodResult[T]) of the annotated function f to a consumer function, without having to actually return an instance of T in the implementation of f.

Example: def get_name() -> ContractMethodResult[str]: script = vm.ScriptBuilder().emit_contract_call(some_hash, "name") return ContractMethodResult(script, unwrap.as_str)

def consumer(f: ContractMethodResult[ReturnType]) -> ReturnType:
    res = rpc.invoke_script(f.script)
    return f.execution_processor(res) # unwraps the result as a string

x = consumer(get_name())
type(x) # str

Methods

• __init_subclass__(*args, **kwargs) — This method is called when a class is subclassed.
• __class_getitem__(cls, params) — Parameterizes a generic class.

staticmethod

__class_getitem__(cls, params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ....

classmethod

__init_subclass__(*args, **kwargs)

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

enum

neo3.api.wrappers.DesignateRole()

Bases

enum.IntEnum int enum.ReprEnum enum.Enum

Special role that can be assigned to nodes in the network by the consensus committee.

Members

• NEO_FS_ALPHABET_NODE (int) — 0x10
• ORACLE (int) — 0x8
• STATE_VALIDATOR (int) — 0x4

class

neo3.api.wrappers.GasToken()

Bases

neo3.api.wrappers.NEP17Contract neo3.api.wrappers._TokenContract neo3.api.wrappers.GenericContract

Wrapped GAS token contract.

Methods

• balance_of(account) (ContractMethodResult) — Get the balance for the given account.
• balance_of_friendly(account) (ContractMethodResult) — Get the balance for the given account while taking the token decimals into account.
• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• decimals() (ContractMethodResult) — Get the amount of decimals.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• symbol() (ContractMethodResult) — User-friendly name of the token.
• total_supply() (ContractMethodResult) — Get the total token supply in the NEO system.
• transfer(source, destination, amount, data) (ContractMethodResult) — Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.
• transfer_friendly(source, destination, amount, data) — Transfer amount of tokens from source account to destination account.
• transfer_multi(source, destinations, amount, data, abort_on_failure) (ContractMethodResult) — Transfer amount of tokens from source to each account in destinations.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

balance_of(account) → ContractMethodResult

Get the balance for the given account.

Note

The returned value does not take the token decimals into account. e.g. for the GAS token you want to de the result by 10**8 (as the Gas token has 8 decimals).

Raises

• ValueError — if account is an invalid NeoAddress format.

method

balance_of_friendly(account) → ContractMethodResult

Get the balance for the given account while taking the token decimals into account.

Uses the token decimals to convert to the user end representation.

Raises

• ValueError — if account is an invalid NeoAddress format.

method

transfer(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.

For this to pass while using test_invoke(), make sure to add a Signer with a script hash equal to the source account. i.e.

source = <source_script_hash>
signer = verification.Signer(source, payloads.WitnessScope.CALLED_BY_ENTRY)
await facade.test_invoke(token.transfer(source, destination, 10), signers=[signer]))

Raises

• ValueError — if source or destination is an invalid NeoAddress format

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

method

transfer_friendly(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.

Same as transfer but does not require manually convert amount if the token uses decimals.

Returns

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

Raises

• ValueError — if source or destination is an invalid NeoAddress format

method

transfer_multi(source, destinations, amount, data=None, abort_on_failure=False)

Transfer amount of tokens from source to each account in destinations.

Parameters

• source (neo3.core.types.uint.uint160 | str) — account to take funds from.
• destinations (Sequence) — accounts to send funds to.
• amount (int) — how much to transfer.
• data (Union, optional) — forward to onNEP17Payment handler if applicable.
• abort_on_failure (bool, optional) — if True aborts the whole transaction if any of the transfers fails.

Raises

• ValueError — if any of the destinations is supplied as NeoAddress but is an invalid address format.

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if all transfers are successful. False otherwise.

method

decimals() → ContractMethodResult

Get the amount of decimals.

Use this with the result of balance_of to display the correct user representation.

method

symbol() → ContractMethodResult

User-friendly name of the token.

method

total_supply() → ContractMethodResult

Get the total token supply in the NEO system.

class

neo3.api.wrappers.GenericContract(contract_hash)

Generic class to call arbitrary methods on a smart contract.

Methods

• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

dataclass

neo3.api.wrappers.InvokeReceipt(tx_hash, included_in_block, confirmations, gas_consumed, state, exception, notifications, result)

Bases

typing.Generic

Transaction submission results.

Parameters

• tx_hash (UInt256) — Unique identifier.
• included_in_block (int) — The block height/index the transaction is included in.
• confirmations (int) — Number of blocks after accepting the transaction.
• gas_consumed (int) — The total gas cost for block inclusion and script execution.
• state (VMState) — HALT = success, Others = failure.
• exception (Optional) — Virtual Machine exception.
• notifications (list) — Smart contract notifications.
• result (ReturnType) — Script excution result.

Attributes

• confirmations (int) — Number of blocks after accepting the transaction.
• exception (Optional) — Virtual Machine exception.
• gas_consumed (int) — The total gas cost for block inclusion and script execution.
• included_in_block (int) — The block height/index the transaction is included in.
• notifications (list) — Smart contract notifications.
• result (ReturnType) — Script excution result.
• state (VMState) — HALT = success, Others = failure.
• tx_hash (UInt256) — Unique identifier.

Methods

• __init_subclass__(*args, **kwargs) — This method is called when a class is subclassed.
• __class_getitem__(cls, params) — Parameterizes a generic class.

staticmethod

__class_getitem__(cls, params)

Parameterizes a generic class.

At least, parameterizing a generic class is the main thing this method does. For example, for some generic class Foo, this is called when we do Foo[int] - there, with cls=Foo and params=int.

However, note that this method is also called when defining generic classes in the first place with class Foo(Generic[T]): ....

classmethod

__init_subclass__(*args, **kwargs)

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

class

neo3.api.wrappers.NEP11DivisibleContract(contract_hash)

Bases

neo3.api.wrappers._NEP11Contract neo3.api.wrappers._TokenContract neo3.api.wrappers.GenericContract

Base class for divisible NFTs.

The NEP-11 ownerOf method is named owners_of in this wrapper.

Methods

• balance_of(owner, token_id) (ContractMethodResult) — Get the token balance for the given owner.
• balance_of_friendly(owner, token_id) (ContractMethodResult) — Get the balance for the given account and convert the result into the user representation.
• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• decimals() (ContractMethodResult) — Get the amount of decimals.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• owners_of(token_id) (ContractMethodResult) — Get a list of account script hashes that own a part of token_id.
• properties(token_id) (ContractMethodResult) — Get all properties for the given NFT.
• symbol() (ContractMethodResult) — User-friendly name of the token.
• token_ids_owned_by(owner) (ContractMethodResult) — Get an iterator containing all token ids owned by the specified address.
• tokens(limit, start_index) (ContractMethodResult) — Get all tokens minted by the contract.
• tokens_count() — Count all tokens minted by the contract
• total_owned_by(owner) (ContractMethodResult) — Get the total amount of NFTs owned for the given account.
• total_supply() (ContractMethodResult) — Get the total token supply in the NEO system.
• transfer(source, destination, amount, token_id, data) (ContractMethodResult) — Transfer amount of token_id from source account to destination account.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

balance_of(owner, token_id) → ContractMethodResult

Get the token balance for the given owner.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

balance_of_friendly(owner, token_id) → ContractMethodResult

Get the balance for the given account and convert the result into the user representation.

Uses the token decimals to convert to the user end representation.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

owners_of(token_id) → ContractMethodResult

Get a list of account script hashes that own a part of token_id.

method

transfer(source, destination, amount, token_id, data=None)

Transfer amount of token_id from source account to destination account.

For this to pass while using test_invoke(), make sure to add a Signer with a script hash equal to the source account. i.e.

source = <source_script_hash>
signer = verification.Signer(source, payloads.WitnessScope.CALLED_BY_ENTRY)
await facade.test_invoke(token.transfer(source, destination, 10), signers=[signer]))

Raises

• ValueError — if source or destination is an invalid NeoAddress format.

Returns (ContractMethodResult)

True if token fractions transferred successful. False otherwise.

method

decimals() → ContractMethodResult

Get the amount of decimals.

A zero return value indicates a non-divisible NFT. A bigger than zero return value indicates a divisible NFTs.

method

properties(token_id) → ContractMethodResult

Get all properties for the given NFT.

Note

This is an optional method and may not exist on the contract.

method

token_ids_owned_by(owner) → ContractMethodResult

Get an iterator containing all token ids owned by the specified address.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

tokens(limit=2000, start_index=0) → ContractMethodResult

Get all tokens minted by the contract.

limit: the maximum tokens to return. start_index: where to start collecting results from (see Note1)

Note1: There is a limit on the returned items in the virtual machine (default: 2048) to avoid too much compute being used. The limit here is set slightly lower on purpose to allow other necessary items in the VM. If the contract returns more than 2000 items you need to call the method again providing the start_index parameter. The tokens_count method can be used to get the size of the iterator.

Note2: This is an optional method in the NEP-11 standard and can thus fail.

method

tokens_count()

Count all tokens minted by the contract

Note

This depends on the optional tokens method and can thus fail.

method

total_owned_by(owner) → ContractMethodResult

Get the total amount of NFTs owned for the given account.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

symbol() → ContractMethodResult

User-friendly name of the token.

method

total_supply() → ContractMethodResult

Get the total token supply in the NEO system.

class

neo3.api.wrappers.NEP11NonDivisibleContract(contract_hash)

Bases

neo3.api.wrappers._NEP11Contract neo3.api.wrappers._TokenContract neo3.api.wrappers.GenericContract

Base class for non-divisible NFTs.

Methods

• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• decimals() (ContractMethodResult) — Get the amount of decimals.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• owner_of(token_id) (ContractMethodResult) — Get the owner of the given token.
• properties(token_id) (ContractMethodResult) — Get all properties for the given NFT.
• symbol() (ContractMethodResult) — User-friendly name of the token.
• token_ids_owned_by(owner) (ContractMethodResult) — Get an iterator containing all token ids owned by the specified address.
• tokens(limit, start_index) (ContractMethodResult) — Get all tokens minted by the contract.
• tokens_count() — Count all tokens minted by the contract
• total_owned_by(owner) (ContractMethodResult) — Get the total amount of NFTs owned for the given account.
• total_supply() (ContractMethodResult) — Get the total token supply in the NEO system.
• transfer(destination, token_id, data) (ContractMethodResult) — Transfer token_id to destination account.The source account will be the account that pays for the fees (a.k.a. the transaction.sender).
• transfer_multi(destinations, token_ids, data, abort_on_failure) (ContractMethodResult) — Transfer multiple token_ids to multiple destinations. Destination and token_ids are paired in order.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

owner_of(token_id) → ContractMethodResult

Get the owner of the given token.

method

transfer(destination, token_id, data=None)

Transfer token_id to destination account.The source account will be the account that pays for the fees (a.k.a. the transaction.sender).

For this to pass while using test_invoke(), make sure to add a Signer with a script hash equal to the source account. i.e.

signer = verification.Signer(source_account, payloads.WitnessScope.CALLED_BY_ENTRY)
await facade.test_invoke(token.transfer(destination, token_id, 10), signers=[signer]))

Raises

• ValueError — if destination is an invalid NeoAddress format.

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

method

transfer_multi(destinations, token_ids, data=None, abort_on_failure=False)

Transfer multiple token_ids to multiple destinations. Destination and token_ids are paired in order.

Parameters

• destinations (Sequence) — accounts to send tokens to.
• token_ids (list) — list of token ids.
• data (Union, optional) — forward to onNEP17Payment handler if applicable.
• abort_on_failure (bool, optional) — if True aborts the whole transaction if any of the transfers fails.

Raises

• ValueError — if any of the destinations is supplied as NeoAddress but is an invalid address format.

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if all transfers are successful. False otherwise.

method

decimals() → ContractMethodResult

Get the amount of decimals.

A zero return value indicates a non-divisible NFT. A bigger than zero return value indicates a divisible NFTs.

method

properties(token_id) → ContractMethodResult

Get all properties for the given NFT.

Note

This is an optional method and may not exist on the contract.

method

token_ids_owned_by(owner) → ContractMethodResult

Get an iterator containing all token ids owned by the specified address.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

tokens(limit=2000, start_index=0) → ContractMethodResult

Get all tokens minted by the contract.

limit: the maximum tokens to return. start_index: where to start collecting results from (see Note1)

Note1: There is a limit on the returned items in the virtual machine (default: 2048) to avoid too much compute being used. The limit here is set slightly lower on purpose to allow other necessary items in the VM. If the contract returns more than 2000 items you need to call the method again providing the start_index parameter. The tokens_count method can be used to get the size of the iterator.

Note2: This is an optional method in the NEP-11 standard and can thus fail.

method

tokens_count()

Count all tokens minted by the contract

Note

This depends on the optional tokens method and can thus fail.

method

total_owned_by(owner) → ContractMethodResult

Get the total amount of NFTs owned for the given account.

Raises

• ValueError — if owner is an invalid NeoAddress format.

method

symbol() → ContractMethodResult

User-friendly name of the token.

method

total_supply() → ContractMethodResult

Get the total token supply in the NEO system.

class

neo3.api.wrappers.NEP17Contract(contract_hash)

Bases

neo3.api.wrappers._TokenContract neo3.api.wrappers.GenericContract

Base class for calling NEP-17 compliant smart contracts.

Methods

• balance_of(account) (ContractMethodResult) — Get the balance for the given account.
• balance_of_friendly(account) (ContractMethodResult) — Get the balance for the given account while taking the token decimals into account.
• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• decimals() (ContractMethodResult) — Get the amount of decimals.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• symbol() (ContractMethodResult) — User-friendly name of the token.
• total_supply() (ContractMethodResult) — Get the total token supply in the NEO system.
• transfer(source, destination, amount, data) (ContractMethodResult) — Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.
• transfer_friendly(source, destination, amount, data) — Transfer amount of tokens from source account to destination account.
• transfer_multi(source, destinations, amount, data, abort_on_failure) (ContractMethodResult) — Transfer amount of tokens from source to each account in destinations.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

balance_of(account) → ContractMethodResult

Get the balance for the given account.

Note

The returned value does not take the token decimals into account. e.g. for the GAS token you want to de the result by 10**8 (as the Gas token has 8 decimals).

Raises

• ValueError — if account is an invalid NeoAddress format.

method

balance_of_friendly(account) → ContractMethodResult

Get the balance for the given account while taking the token decimals into account.

Uses the token decimals to convert to the user end representation.

Raises

• ValueError — if account is an invalid NeoAddress format.

method

transfer(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.

For this to pass while using test_invoke(), make sure to add a Signer with a script hash equal to the source account. i.e.

source = <source_script_hash>
signer = verification.Signer(source, payloads.WitnessScope.CALLED_BY_ENTRY)
await facade.test_invoke(token.transfer(source, destination, 10), signers=[signer]))

Raises

• ValueError — if source or destination is an invalid NeoAddress format

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

method

transfer_friendly(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.

Same as transfer but does not require manually convert amount if the token uses decimals.

Returns

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

Raises

• ValueError — if source or destination is an invalid NeoAddress format

method

transfer_multi(source, destinations, amount, data=None, abort_on_failure=False)

Transfer amount of tokens from source to each account in destinations.

Parameters

• source (neo3.core.types.uint.uint160 | str) — account to take funds from.
• destinations (Sequence) — accounts to send funds to.
• amount (int) — how much to transfer.
• data (Union, optional) — forward to onNEP17Payment handler if applicable.
• abort_on_failure (bool, optional) — if True aborts the whole transaction if any of the transfers fails.

Raises

• ValueError — if any of the destinations is supplied as NeoAddress but is an invalid address format.

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if all transfers are successful. False otherwise.

method

decimals() → ContractMethodResult

Get the amount of decimals.

Use this with the result of balance_of to display the correct user representation.

method

symbol() → ContractMethodResult

User-friendly name of the token.

method

total_supply() → ContractMethodResult

Get the total token supply in the NEO system.

class

neo3.api.wrappers.NeoToken()

Bases

neo3.api.wrappers.NEP17Contract neo3.api.wrappers._TokenContract neo3.api.wrappers.GenericContract

Wrapped NEO token contract.

Methods

• balance_of(account) (ContractMethodResult) — Get the balance for the given account.
• balance_of_friendly(account) (ContractMethodResult) — Get the balance for the given account while taking the token decimals into account.
• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• candidate_register(public_key) (ContractMethodResult) — Register as a consensus candidate.
• candidate_registration_price() (ContractMethodResult) — Get the amount of GAS to pay to register as consensus candidate.
• candidate_unregister(public_key) (ContractMethodResult) — Unregister as a consensus candidate.
• candidate_vote(voter, candidate) (ContractMethodResult) — Cast a vote for candidate to become a consensus node.
• candidate_votes(candidate) (ContractMethodResult) — Get the total vote count for candidate.
• candidates_registered() (ContractMethodResult) — Get the first 256 registered candidates.
• decimals() (ContractMethodResult) — Get the amount of decimals.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• get_gas_per_block() (ContractMethodResult) — Get the amount of GAS generated in each block.
• get_unclaimed_gas(account, end) (ContractMethodResult) — Get the amount of unclaimed GAS.
• symbol() (ContractMethodResult) — User-friendly name of the token.
• total_supply() (ContractMethodResult) — Get the total token supply in the NEO system.
• transfer(source, destination, amount, data) (ContractMethodResult) — Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.
• transfer_friendly(source, destination, amount, data) — Transfer amount of tokens from source account to destination account.
• transfer_multi(source, destinations, amount, data, abort_on_failure) (ContractMethodResult) — Transfer amount of tokens from source to each account in destinations.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

balance_of(account) → ContractMethodResult

Get the balance for the given account.

Note

The returned value does not take the token decimals into account. e.g. for the GAS token you want to de the result by 10**8 (as the Gas token has 8 decimals).

Raises

• ValueError — if account is an invalid NeoAddress format.

method

balance_of_friendly(account) → ContractMethodResult

Get the balance for the given account while taking the token decimals into account.

Uses the token decimals to convert to the user end representation.

Raises

• ValueError — if account is an invalid NeoAddress format.

method

transfer(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.Forward data to onNEP17Payment handler if applicable.

For this to pass while using test_invoke(), make sure to add a Signer with a script hash equal to the source account. i.e.

source = <source_script_hash>
signer = verification.Signer(source, payloads.WitnessScope.CALLED_BY_ENTRY)
await facade.test_invoke(token.transfer(source, destination, 10), signers=[signer]))

Raises

• ValueError — if source or destination is an invalid NeoAddress format

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

method

transfer_friendly(source, destination, amount, data=None)

Transfer amount of tokens from source account to destination account.

Same as transfer but does not require manually convert amount if the token uses decimals.

Returns

The return value after invoking with invoke() or test_invoke() is True if the token transferred successful. False otherwise.

Raises

• ValueError — if source or destination is an invalid NeoAddress format

method

transfer_multi(source, destinations, amount, data=None, abort_on_failure=False)

Transfer amount of tokens from source to each account in destinations.

Parameters

• source (neo3.core.types.uint.uint160 | str) — account to take funds from.
• destinations (Sequence) — accounts to send funds to.
• amount (int) — how much to transfer.
• data (Union, optional) — forward to onNEP17Payment handler if applicable.
• abort_on_failure (bool, optional) — if True aborts the whole transaction if any of the transfers fails.

Raises

• ValueError — if any of the destinations is supplied as NeoAddress but is an invalid address format.

Returns (ContractMethodResult)

The return value after invoking with invoke() or test_invoke() is True if all transfers are successful. False otherwise.

method

candidate_register(public_key)

Register as a consensus candidate.

See Also

Account.public_key

Returns (ContractMethodResult)

True if successful. False otherwise.

method

candidate_registration_price() → ContractMethodResult

Get the amount of GAS to pay to register as consensus candidate.

method

candidate_unregister(public_key)

Unregister as a consensus candidate.

See Also

Account.public_key

Returns (ContractMethodResult)

True if successful. False otherwise.

method

candidate_vote(voter, candidate)

Cast a vote for candidate to become a consensus node.

Parameters

• voter (neo3.core.types.uint.uint160 | str) — the account to vote from.
• candidate (ECPoint) — who to vote on.

Raises

• ValueError — if voter is an invalid NeoAddress format.

Returns (ContractMethodResult)

True if vote cast successful. False otherwise.

method

candidate_votes(candidate) → ContractMethodResult

Get the total vote count for candidate.

method

candidates_registered() → ContractMethodResult

Get the first 256 registered candidates.

method

get_gas_per_block() → ContractMethodResult

Get the amount of GAS generated in each block.

method

get_unclaimed_gas(account, end=None) → ContractMethodResult

Get the amount of unclaimed GAS.

Parameters

• account (neo3.core.types.uint.uint160 | str) — for whom.
• end (Optional, optional) — up to which block height to calculate the GAS bonus. Omit to calculate to the current chain height.

Raises

• ValueError — if account is an invalid NeoAddress format.

method

decimals() → ContractMethodResult

Get the amount of decimals.

Use this with the result of balance_of to display the correct user representation.

method

symbol() → ContractMethodResult

User-friendly name of the token.

method

total_supply() → ContractMethodResult

Get the total token supply in the NEO system.

class

neo3.api.wrappers.PolicyContract()

Bases

neo3.api.wrappers.GenericContract

Wrapper around the native contract that manages system policies.

Note

Functions that only consensus committee members can use are not implemented.

Methods

• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• exec_fee_factor() (ContractMethodResult) — The system fee multiplier for transactions.
• fee_per_byte() (ContractMethodResult) — The fee per transaction byte.
• is_blocked(script_hash) (ContractMethodResult) — Check if an account or contract is blocked on the network.
• storage_price() (ContractMethodResult) — The price per byte of smart contract storage.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

exec_fee_factor() → ContractMethodResult

The system fee multiplier for transactions.

method

fee_per_byte() → ContractMethodResult

The fee per transaction byte.

method

is_blocked(script_hash) → ContractMethodResult

Check if an account or contract is blocked on the network.

method

storage_price() → ContractMethodResult

The price per byte of smart contract storage.

class

neo3.api.wrappers.RoleContract()

Bases

neo3.api.wrappers.GenericContract

Wrapper around the native Role management contract.

Methods

• call_function(name, args) (ContractMethodResult) — Call a method on the contract.
• destroy(destroy_method) (ContractMethodResult) — Destroy the contract on chain.
• get_designated_by_role(role, block_index) (ContractMethodResult) — Gets the public keys registered for a given role at a given height.
• update(update_method, nef, manifest, data) (ContractMethodResult) — Update this contract on chain with a new manifest and/or contract (NEF).
• deploy(nef, manifest, data) (ContractMethodResult) — Deploy a smart contract to the chain.

method

call_function(name, args=None) → ContractMethodResult

Call a method on the contract.

Parameters

• name — the method name to call as defined in the manifest.
• args (Union, optional) — optional list of arguments the function expects.

staticmethod

deploy(nef, manifest, data=None)

Deploy a smart contract to the chain.

Parameters

• nef (NEF) — compiled contract.
• manifest (ContractManifest) — contract manifest file.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

Returns (ContractMethodResult)

contract hash.

method

destroy(destroy_method='destroy') → ContractMethodResult

Destroy the contract on chain.

This will permanently block the contract hash on the network.

Parameters

• destroy_method (str, optional) — override with name of the destroy function on the contract. Default signature is destroy().

method

update(update_method='update', nef=None, manifest=None, data=None) → ContractMethodResult

Update this contract on chain with a new manifest and/or contract (NEF).

Assumes the update method on the contract uses the standard arguments; nef, manifest and (optional) data. If it uses custom arguments use call_function instead.

Parameters

• update_method (str, optional) — override with name of the update function on the contract.
• nef (Optional, optional) — compiled contract.
• manifest (Optional, optional) — contract manifest.
• data (Union, optional) — data that is passed to the _deploy method of the smart contract (if the method exists).

method

get_designated_by_role(role, block_index) → ContractMethodResult

Gets the public keys registered for a given role at a given height.