High-level interfaces

PyTezos client

class pytezos.client.PyTezosClient(context: ExecutionContext | None = None)

Entry point for a developer, start your script with:

from pytezos import pytezos

account = <function PyTezosClient.account> Shortcut for RPC contract request.  :param account_id: tz/KT address, leave None to show info about current key

activate_account = <function ContentMixin.activate_account> Activate recommended allocations for contributions to the TF fundraiser.  More info https://activate.tezos.com/  :param activation_code: Secret code from pdf, leave empty for autocomplete :param pkh: Public key hash, leave empty for autocomplete :returns: dict or OperationGroup

activate_protocol = <function PyTezosClient.activate_protocol> Initiate user-activated upgrade (sandbox only)  :param protocol_hash: Protocol hash :rtype: BlockHeader

bake_block = <function PyTezosClient.bake_block> Create and inject new block with operations from mempool  :param min_fee: filter operations by fee (default is 0) :rtype: BlockHeader

balance = <function PyTezosClient.balance> Get account balance.  :return: amount in tez

ballot = <function ContentMixin.ballot> Vote for a proposal in a given voting period.  Can only be submitted during Testing_vote or Promotion_vote periods, and only once per period. More info https://tezos.gitlab.io/master/whitedoc/voting.html  :param proposal: Hash of the proposal :param ballot: 'Yay', 'Nay' or 'Pass' :param source: Public key hash (of the signatory), leave None for autocomplete :param period: Number of the current voting period, leave None for autocomplete :returns: dict or OperationGroup

bulk = <function PyTezosClient.bulk> Batch multiple operations and contract calls in a single operation group  :param operations: a tuple of operations or contract calls :rtype: OperationGroup

check_message = <function PyTezosClient.check_message> Check message signature  :param message: Signed operation :param public_key: Signer's public key :param signature: Message signature :param block: Specify block, defaults to genesis

contract = <function PyTezosClient.contract> Get a high-level interface for a given smart contract id.  :param address: KT address of a smart contract :rtype: ContractInterface

delegation = <function ContentMixin.delegation> Delegate funds or register yourself as a delegate.  :param delegate: tz address of delegate, leave None to register yourself as a delegate :param source: Address from which funds will be delegated, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

double_baking_evidence = <function ContentMixin.double_baking_evidence> Provide evidence of double baking (two different blocks at the same height).  :param bh1: First block hash :param bh2: Second block hash :returns: dict or OperationGroup

double_endorsement_evidence = <function ContentMixin.double_endorsement_evidence> Provide evidence of double endorsement (endorsing two different blocks at the same block height).  Inline endorsement format:  .. code-block:: python  { "branch": $block_hash, "operations": { "kind": "endorsement", "level": integer ∈ [-2^31-2, 2^31+2] }, "signature"?: $Signature }  :param op1: Inline endorsement :param op2: Inline endorsement :returns: dict or OperationGroup

endorsement = <function ContentMixin.endorsement> Endorse a block.  :param level: Endorsed level :returns: dict or OperationGroup

endorsement_with_slot = <function ContentMixin.endorsement_with_slot> Wrap endorsement  :param endorsement: Inlined endorsement :param slot: Minimum of the slots endorsed :returns: dict or OperationGroup

failing_noop = <function ContentMixin.failing_noop> Operation to sign arbitrary data without the risk it will be used onchain.  :param arbitrary: Message to sign :returns: dict or OperationGroup

now = <function PyTezosClient.now> Timestamp of the latest block + block time (UTC).

operation = <function PyTezosClient.operation> Create an operation group with single content.  :param content: Operation body (depending on `kind`) :rtype: OperationGroup

operation_group = <function PyTezosClient.operation_group> Create new operation group (multiple contents).  You can leave all fields empty in order to create an empty operation group.  :param protocol: Leave None for autocomplete, unless you know what you are doing :param branch: Leave None for autocomplete :param contents: List of operation contents (optional) :param signature: Can be set later :rtype: OperationGroup

origination = <function ContentMixin.origination> Deploy smart contract (scriptless KT accounts are not used for delegation since Babylon).  :param script: {"code": $Micheline, "storage": $Micheline} :param balance: Amount transferred on the balance, WARNING: there is no default way to withdraw funds. More info: https://tezos.stackexchange.com/questions/1315/can-i-withdraw-funds-from-an-empty-smart-contract :param delegate: Set contract delegate, default None :param source: Address from which funds will be sent, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

proposals = <function ContentMixin.proposals> Submit and/or upvote proposals to amend the protocol.  Can only be submitted during a proposal period. More info https://tezos.gitlab.io/master/whitedoc/voting.html  :param proposals: List of proposal hashes or single proposal hash :param source: Public key hash (of the signatory), leave None for autocomplete :param period: Number of the current voting period, leave 0 for autocomplete :returns: dict or OperationGroup

register_global_constant = <function ContentMixin.register_global_constant> Operation to register Micheline expressions in a global table of constants  :param value: Micheline expression :param source: Address from which funds will be delegated, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

reveal = <function ContentMixin.reveal> Reveal the public key associated with a tz address.  :param public_key: Public key to reveal, Base58 encoded :param source: Public key hash of the key revealed, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete (More info https://tezos.stackexchange.com/questions/632/how-counter-grows) :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

seed_nonce_revelation = <function ContentMixin.seed_nonce_revelation> Reveal the nonce committed operation in the previous cycle.  More info https://tezos.stackexchange.com/questions/567/what-are-nonce-revelations  :param level: When nonce hash was committed :param nonce: Hex string :returns: dict or OperationGroup

sign_message = <function PyTezosClient.sign_message> Sign arbitrary message with guarantee that resulting operation won't be used onchain.  :param message: Message to sign :param block: Specify block, defaults to genesis :returns: Base58-encoded signature (non-generic)

sleep = <function PyTezosClient.sleep> Sleeps until a certain amount of blocks appended to the chain  :param num_blocks: number of blocks to wait for :param time_between_blocks: override the corresponding parameter from constants :param block_timeout: set block timeout (by default Pytezos will wait for a long time)

smart_rollup_add_messages = <function ContentMixin.smart_rollup_add_messages> Send external message to the global rollup inbox  :param message: Array of byte strings 2KB max each :param source: Address from which funds will be delegated, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

smart_rollup_execute_outbox_message = <function ContentMixin.smart_rollup_execute_outbox_message> Execute outbox message on L1  :param rollup: Rollup address, base58 encoded (sr1) :param cemented_commitment: Commitment hash, base58 encoded (src1) :param output_proof: Byte string :param source: Address from which funds will be delegated, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

transaction = <function ContentMixin.transaction> Transfer tez to a given address (implicit or originated).  If the receiver is a smart contract, then optional parameters may be passed.  :param source: Address from which funds will be sent, leave None to use signatory address :param destination: Address :param amount: Amount to send in microtez (int) or tez (Decimal) (optional) :param counter: Current account counter, leave None for autocomplete :param parameters: { "entrypoint": $string, "value": $Micheline expression } (optional) :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

transfer_ticket = <function ContentMixin.transfer_ticket> Transfer ticket to another implicit account or to a smart rollup  :param ticket_contents: Micheline expression (value) :param ticket_ty: Micheline expression (type) :param ticket_ticketer: Ticketer address :param ticket_amount: Amount :param destination: Implicit or originated address (smart rollups not supported) :param entrypoint: Smart contract entrypoint (leave "default" for implicit accounts) :param source: Address from which funds will be delegated, leave None to use signatory address :param counter: Current account counter, leave None for autocomplete :param fee: Leave None for autocomplete :param gas_limit: Leave None for autocomplete :param storage_limit: Leave None for autocomplete :returns: dict or OperationGroup

using = <function PyTezosClient.using> Change current RPC endpoint and account (private key).  :param shell: one of 'mainnet', '***net', or RPC node uri, or instance of :class:`pytezos.rpc.shell.ShellQuery` :param key: base58 encoded key, path to the faucet file, faucet file itself, alias from tezos-client, or `Key` :param mode: whether to use `readable` or `optimized` encoding for parameters/storage/other :returns: A copy of current object with changes applied

wait = <function PyTezosClient.wait> Wait for multiple injected operations get enough confirmations  :param min_confirmations: number of block injections to wait for before returning :param num_blocks_wait: number of blocks to wait for injection :param time_between_blocks: override the corresponding parameter from constants :param prev_hash: Current block hash (optional). If not set, current head is used. :param block_timeout: set block timeout (by default Pytezos will wait for a long time)

Contract interface

class pytezos.contract.interface.ContractInterface(context: ExecutionContext)

Proxy class for interacting with a contract.

big_map_get = <function ContractInterface.big_map_get> Get BigMap entry as Python object by plain key and block height.  :param path: JSON path to the key (or just key to access default BigMap location). Use `/` to separate nodes and `::` to separate tuple args. In any other case you'd need to escape those symbols. :returns: object   .. deprecated:: 3.0.0 This will be removed in 4.0.0. use `.storage[path][to][big_map][key]()` instead

property call: ContractEntrypoint

Deprecated since version 3.0.0.

This will be removed in 4.0.0. use default() instead

property code

Deprecated since version 3.0.0.

This will be removed in 4.0.0. use to_micheline() instead

property contract: ContractInterface

Deprecated since version 3.0.0.

This will be removed in 4.0.0. access ContractInterface directly

classmethod create_from(source)

Create contract interface from its code.

Parameters:

source – Michelson code, filename, or Micheline JSON

Return type:

ContractInterface

Deprecated since version 3.0.0: This will be removed in 4.0.0. use one of from_file, from_michelson, from_micheline, from_url

from_context = <staticmethod(<function ContractInterface.from_context>)> Create contract from the previously loaded context data.  :param context: execution context :return: ContractInterface

from_file = <staticmethod(<function ContractInterface.from_file>)> Create contract from michelson source code stored in a file.  :param path: Path to the `.tz` file :param context: optional execution context :rtype: ContractInterface

from_micheline = <staticmethod(<function ContractInterface.from_micheline>)> Create contract from micheline expression.  :param expression: [{'prim': 'parameter'}, {'prim': 'storage'}, {'prim': 'code'}] :param context: optional execution context :rtype: ContractInterface

from_michelson = <staticmethod(<function ContractInterface.from_michelson>)> Create contract from michelson source code.  :param source: Michelson source code :param context: optional execution context :rtype: ContractInterface

from_url = <staticmethod(<function ContractInterface.from_url>)> Create contract from michelson source code available via URL  :param url: link to the Michelson file :param context: optional execution context :rtype: ContractInterface

property metadata: ContractMetadata | None

Get TZIP-016 contract metadata, if exists

Return type:

ContractMetadata

operation_result = <function ContractInterface.operation_result> Get operation parameters, and resulting storage as Python objects. Can locate operation inside operation groups with multiple contents and/or internal operations.  :param operation_group: {'branch', 'protocol', 'contents', 'signature'} :rtype: ContractCallResult

originate = <function ContractInterface.originate> Create an origination operation  :param initial_storage: Python object, leave None to generate default :param mode: whether to use `readable` or `optimized` (or `legacy_optimized`) encoding for initial storage :param balance: initial balance :param delegate: initial delegator :rtype: OperationGroup

script = <function ContractInterface.script> Generate script for contract origination.  :param initial_storage: Python object, leave None to generate default (attach shell/key for smart fill) :param mode: whether to use `readable` or `optimized` (or `legacy_optimized`) encoding for initial storage :return: {"code": $Micheline, "storage": $Micheline}

storage_from_file = <function ContractInterface.storage_from_file> Load contract storage from file  :param path: path to .tz file

storage_from_micheline = <function ContractInterface.storage_from_micheline> Load contract storage from Micheline expression  :param expression: Micheline expression

storage_from_michelson = <function ContractInterface.storage_from_michelson> Load contract storage from Michelson code  :param source: Michelson code

property text: str

Deprecated since version 3.0.0.

This will be removed in 4.0.0. use to_michelson() instead

to_file = <function ContractInterface.to_file> Write contract source to a .tz file  :param path: path to the file

to_micheline = <function ContractInterface.to_micheline> Get contract script in Micheline JSON  :return:  [{'prim': 'parameter'}, {'prim': 'storage'}, {'prim': 'code'}]

to_michelson = <function ContractInterface.to_michelson> Get contract listing in formatted Michelson  :return: string

property token_metadata: ContractTokenMetadataProxy

Get TZIP-021 contract token metadata proxy

Return type:

ContractTokenMetadataProxy

using = <function ContractInterface.using> Change the block at which the current contract is inspected.  Also, if address is undefined you can specify RPC endpoint, and private key.  :param shell: one of 'mainnet', '***net', or RPC node uri, or instance of :class:`pytezos.rpc.shell.ShellQuery` :param key: base58 encoded key, path to the faucet file, alias from tezos-client, or instance of `Key` :param block_id: block height / hash / offset to use, default is `head` :param mode: whether to use `readable` or `optimized` encoding for parameters/storage/other :param ipfs_gateway: override IPFS gateway URI :rtype: ContractInterface

Contract entrypoint proxy

class pytezos.contract.entrypoint.ContractEntrypoint(context: ExecutionContext, entrypoint: str)

Proxy class for spawning ContractCall instances.

__call__(*args, **kwargs) → ContractCall

Spawn a contract call proxy initialized with the entrypoint name

Parameters:

• args – entrypoint args

• kwargs – entrypoint key-value args

Return type:

ContractCall

decode = <function ContractEntrypoint.decode> Convert from Michelson to Python type system  :param value: Micheline JSON expression or Michelson value :param entrypoint: overwrite current entrypoint (in case you want to parse tx parameters) :return: Python object {entrypoint: value}

encode = <function ContractEntrypoint.encode> Encode transaction parameters from the given Python object  :param py_obj: Python object :param mode: whether to use `readable` or `optimized` (or `legacy_optimized`) encoding :return: {entrypoint, value}

Contract call proxy

class pytezos.contract.call.ContractCall(context: ExecutionContext, parameters: dict, amount: int | Decimal = 0)

Proxy class encapsulating a contract call: contract type scheme, contract address, parameters, and amount

as_transaction = <function ContractCall.as_transaction> Get operation content.  :rtype: OperationGroup

callback_view = <function ContractCall.callback_view> Get return value of an on-chain callback method.  :param storage: initial storage as Python object, if None then the current one will be taken (if context attached), otherwise empty (dummy) :returns: Decoded parameters of a callback

cmdline = <function ContractCall.cmdline> Generate command line for tezos-client.

inject = <function ContractCall.inject> Send operation to blockchain.  .. deprecated:: 3.2.2 This will be removed in 4.0.0. use `send()` instead

interpret = <function ContractCall.interpret> Run code in the builtin REPL (WARNING! Not recommended for critical tasks).  :param storage: initial storage as Python object, leave None if you want to generate a dummy one :param source: patch SOURCE :param sender: patch SENDER :param amount: patch AMOUNT :param balance: patch BALANCE :param chain_id: patch CHAIN_ID :param level: patch LEVEL :param now: patch NOW :param self_address: patch SELF/SELF_ADDRESS :param view_results: patch VIEW calls (keys must be string "address%view", values => Python objects) :rtype: pytezos.contract.result.ContractCallResult

property operation_group: OperationGroup

Deprecated since version 3.0.0.

This will be removed in 4.0.0. use as_transaction() instead

result = <function ContractCall.result> Simulate operation and parse the result.  :param storage: Python object only. If storage is specified, `run_code` is called instead of `run_operation`. :param source: Can be specified for unit testing purposes :param sender: Can be specified for unit testing purposes,see https://tezos.gitlab.io/whitedoc/michelson.html#operations-on-contracts for the difference :param gas_limit: Specify gas limit (default is gas hard limit) :rtype: ContractCallResult   .. deprecated:: 3.0.0 This will be removed in 4.0.0. use either `run_code` or `run_operation`

run_code = <function ContractCall.run_code> Execute using RPC interpreter.  :param storage: initial storage as Python object, leave None if you want to generate a dummy one :param source: patch SOURCE :param sender: patch SENDER :param amount: patch AMOUNT :param balance: patch BALANCE :param chain_id: patch CHAIN_ID :param gas_limit: restrict max consumed gas :rtype: ContractCallResult

run_operation = <function ContractCall.run_operation> Simulate operation using real context.  :rtype: ContractCallResult

send = <function ContractCall.send> Fill, sign, and broadcast the transaction  :param gas_reserve: Add a safe reserve for dynamically calculated gas limit (default is 100). :param burn_reserve: Add a safe reserve for dynamically calculated storage limit (default is 100). :param min_confirmations: number of block injections to wait for before returning (default is 0, i.e. async mode) :param ttl: Number of blocks to wait in the mempool before removal (default is 5 for public network, 60 for sandbox) :return: OperationGroup with hash filled

send_async = <function ContractCall.send_async>  Send operation without simulation or pre-validation  :param ttl: Number of blocks to wait in the mempool before removal (default is 5 for public network, 60 for sandbox) :param counter: Set counter value :param gas_limit: Set gas_limit value :param storage_limit: Set storage_limit value :param minimal_nanotez_per_gas_unit: Override minimal_nanotez_per_gas_unit constant :rtype: OperationGroup

view = <function ContractCall.view>   .. deprecated:: 3.0.4 This will be removed in 4.0.0. Use callback_view instead

with_amount = <function ContractCall.with_amount> Set amount of funds to send with transaction to the contract.  :param amount: amount in microtez (int) or tez (Decimal) :rtype: ContractCall

Contract call result

class pytezos.contract.result.ContractCallResult(**props)

Encapsulates the result of a contract invocation.

classmethod from_run_code(response: Dict[str, Any], parameters, context: ExecutionContext) → ContractCallResult

Parse a result of pytezos.contract.call.ContractCall.run_code() execution.

Parameters:

• response – RPC response (JSON)

• parameters – {“entrypoint”: str, “value”: $Micheline}

• context – execution context

Return type:

ContractCallResult

classmethod from_run_operation(operation_group: Dict[str, Any], context: ExecutionContext) → List[ContractCallResult]

Get a list of results from an operation group content with metadata.

Parameters:

• operation_group – {…, “contents”: [{…, kind: “transaction”, …}]}

• context – execution context

Return type:

ContractCallResult

Contract storage proxy

class pytezos.contract.data.ContractData(context: ExecutionContext, data: MichelsonType, path='', title=None)

__call__(try_unpack=False)

Get Michelson value as a Python object

Parameters:

try_unpack – try to unpack utf8-encoded strings or PACKed Michelson expressions

decode = <function ContractData.decode> Convert from Michelson or Micheline to Python type system  :param value: Micheline JSON expression or Michelson value :return: Python object

default = <function ContractData.default>   .. deprecated:: 3.0.0 This will be removed in 4.0.0.

dummy = <function ContractData.dummy> Try to generate a dummy (empty) value  :return: Python object

encode = <function ContractData.encode> Convert from Python to Micheline type system  :param py_obj: Python object :param mode: whether to use `readable` or `optimized` (or `legacy_optimized`) encoding :return: Micheline JSON expression

to_micheline = <function ContractData.to_micheline> Get as Micheline JSON expression  :param optimized: use optimized data form for some domain types (timestamp, address, etc.)

to_michelson = <function ContractData.to_michelson> Get as Michelson value  :param optimized: use optimized data form for some domain types (timestamp, address, etc.)

Contract view proxy

class pytezos.contract.view.ContractView(context: ExecutionContext, name: str, parameter: Dict[str, Any] | None, return_type: Dict[str, Any], code: List[Any])

Proxy class for handling off-chain and on-chain views