High-level interfaces

PyTezos client

class pytezos.client.PyTezosClient(shell=None, key=None)[source]

Entry point for a developer, start your script with: from pytezos import pytezos

account(account_id=None) → dict[source]

Shortcut for RPC contract request.

Parameters

account_id – tz/KT address, leave None to show info about current key

activate_account(activation_code='', pkh='')

Activate recommended allocations for contributions to the TF fundraiser. More info https://activate.tezos.com/

Parameters
  • activation_code – Secret code from pdf, leave empty for autocomplete

  • pkh – Public key hash, leave empty for autocomplete

Returns

dict or OperationGroup

ballot(proposal, ballot, source='', period=0)

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

Parameters
  • proposal – Hash of the proposal

  • ballot – ‘Yay’, ‘Nay’ or ‘Pass’

  • source – Public key hash (of the signatory), leave None for autocomplete

  • period – Number of the current voting period, leave None for autocomplete

Returns

dict or OperationGroup

contract(contract_id)pytezos.michelson.interface.ContractInterface[source]

Get a high-level interface for a given smart contract id.

Parameters

contract_id – KT address of a smart contract

Return type

ContractInterface

delegation(delegate='', source='', counter=0, fee=0, gas_limit=0, storage_limit=0)

Delegate funds or register yourself as a delegate.

Parameters
  • delegate – tz address of delegate, leave None to register yourself as a delegate

  • source – Address from which funds will be delegated, leave None to use signatory address

  • counter – Current account counter, leave None for autocomplete

  • fee – Leave None for autocomplete

  • gas_limit – Leave None for autocomplete

  • storage_limit – Leave None for autocomplete

Returns

dict or OperationGroup

double_baking_evidence(bh1, bh2)

Provide evidence of double baking (two different blocks at the same height).

Parameters
  • bh1 – First block hash

  • bh2 – Second block hash

Returns

dict or OperationGroup

double_endorsement_evidence(op1: dict, op2: dict)

Provide evidence of double endorsement (endorsing two different blocks at the same block height).

Parameters
  • op1

    Inline endorsement {

    ”branch”: $block_hash, “operations”: {

    ”kind”: “endorsement”, “level”: integer ∈ [-2^31-2, 2^31+2]

    }, “signature”?: $Signature

    }

  • op2 – Inline endorsement

Returns

dict or OperationGroup

endorsement(level: int)

Endorse a block.

Parameters

level – Endorsed level

Returns

dict or OperationGroup

nft_app(contract_id)pytezos.michelson.interface.ContractInterface[source]

Get a high-level NFT interface for a given smart contract id.

Read more at https://nft.stove-labs.com/ :param contract_id: KT address of a smart contract :rtype: ContractInterface

now() → int[source]

Timestamp of the current head (UTC).

operation(content: dict)pytezos.operation.group.OperationGroup[source]

Create an operation group with single content.

Parameters

content – Operation body (depending on kind)

Return type

OperationGroup

operation_group(protocol=None, branch=None, contents=None, signature=None)pytezos.operation.group.OperationGroup[source]

Create new operation group (multiple contents). You can leave all fields empty in order to create an empty operation group.

Parameters
  • protocol – Leave None for autocomplete, otherwise you know what to do

  • branch – Leave None for autocomplete

  • contents – List of operation contents (optional)

  • signature – Can be set later

Return type

OperationGroup

origination(script, balance=0, delegate=None, source='', counter=0, fee=0, gas_limit=0, storage_limit=0)

Deploy smart contract (scriptless KT accounts are not used for delegation since Babylon)

Parameters
  • script – {“code”: $Micheline, “storage”: $Micheline}

  • 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

  • delegate – Set contract delegate, default None

  • source – Address from which funds will be sent, leave None to use signatory address

  • counter – Current account counter, leave None for autocomplete

  • fee – Leave None for autocomplete

  • gas_limit – Leave None for autocomplete

  • storage_limit – Leave None for autocomplete

Returns

dict or OperationGroup

proposals(proposals, source='', period=0)

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

Parameters
  • proposals – List of proposal hashes or single proposal hash

  • source – Public key hash (of the signatory), leave None for autocomplete

  • period – Number of the current voting period, leave 0 for autocomplete

Returns

dict or OperationGroup

reveal(public_key='', source='', counter=0, fee=0, gas_limit=0, storage_limit=0)

Reveal the public key associated with a tz address.

Parameters
  • public_key – Public key to reveal, Base58 encoded

  • source – Public key hash of the key revealed, leave None to use signatory address

  • counter – Current account counter, leave None for autocomplete (More info https://tezos.stackexchange.com/questions/632/how-counter-grows)

  • fee – Leave None for autocomplete

  • gas_limit – Leave None for autocomplete

  • storage_limit – Leave None for autocomplete

Returns

dict or OperationGroup

seed_nonce_revelation(level: int, nonce)

Reveal the nonce committed operation in the previous cycle. More info https://tezos.stackexchange.com/questions/567/what-are-nonce-revelations

Parameters
  • level – When nonce hash was committed

  • nonce – Hex string

Returns

dict or OperationGroup

transaction(destination, amount=0, parameters=None, source='', counter=0, fee=0, gas_limit=0, storage_limit=0)

Transfer tez to a given address (implicit or originated). If the receiver is a smart contract, then optional parameters may be passed.

Parameters
  • source – Address from which funds will be sent, leave None to use signatory address

  • destination – Address

  • amount – Amount to send in microtez (int) or tez (Decimal) (optional)

  • counter – Current account counter, leave None for autocomplete

  • parameters – { “entrypoint”: $string, “value”: $Micheline expression } (optional)

  • fee – Leave None for autocomplete

  • gas_limit – Leave None for autocomplete

  • storage_limit – Leave None for autocomplete

Returns

dict or OperationGroup

using(shell: pytezos.rpc.shell.ShellQuery = None, key: pytezos.crypto.Key = None)

Change current rpc endpoint and account (private key).

Parameters
  • shell – one of ‘carthagenet’, ‘mainnet’, ‘delphinet’, ‘dalphanet’ or RPC node uri, or instance of ShellQuery

  • key – base58 encoded key, path to the faucet file, alias from tezos-client, or instance of Key

Returns

A copy of current object with changes applied

Contract interface

class pytezos.michelson.interface.ContractInterface(address=None, contract: pytezos.michelson.contract.Contract = None, factory=<class 'pytezos.michelson.contract.Contract'>, shell=None, key=None)[source]

Proxy class for interacting with a contract.

big_map_get(path, block_id='head')[source]

Get BigMap entry as Python object by plain key and block height.

Parameters
  • 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.

  • block_id – Block height / hash / offset to use, default is head

Returns

object

classmethod create_from(source, shell=None, factory=<class 'pytezos.michelson.contract.Contract'>)[source]

Initialize from contract code.

Parameters
  • source – Michelson code

  • shell – A Shell instance (optional)

  • factory – An optional contract factory if you need to force interface (forced annotations)

Return type

ContractInterface

manager()[source]

Get contract manager address (tz).

operation_result(operation_group: dict) → List[pytezos.michelson.interface.ContractCallResult][source]

Get operation parameters, storage and big_map_diff as Python objects. Can locate operation inside operation groups with multiple contents and/or internal operations.

Parameters

operation_group – {‘branch’, ‘protocol’, ‘contents’, ‘signature’}

Return type

ContractCallResult

storage(block_id='head')[source]

Get storage as Pythons object at specified block height.

Parameters

block_id – Block height / hash / offset to use, default is head

Returns

object

using(shell: pytezos.rpc.shell.ShellQuery = None, key: pytezos.crypto.Key = None)

Change current rpc endpoint and account (private key).

Parameters
  • shell – one of ‘carthagenet’, ‘mainnet’, ‘delphinet’, ‘dalphanet’ or RPC node uri, or instance of ShellQuery

  • key – base58 encoded key, path to the faucet file, alias from tezos-client, or instance of Key

Returns

A copy of current object with changes applied

Contract entrypoint proxy

class pytezos.michelson.interface.ContractEntrypoint(name, address=None, contract: pytezos.michelson.contract.Contract = None, factory=<class 'pytezos.michelson.contract.Contract'>, shell=None, key=None)[source]

Proxy class for spawning ContractCall instances.

__call__(*args, **kwargs)[source]

Spawn a contract call proxy initialized with the entrypoint name

Parameters
  • args – entrypoint args

  • kwargs – entrypoint key-value args

Return type

ContractCall

using(shell: pytezos.rpc.shell.ShellQuery = None, key: pytezos.crypto.Key = None)

Change current rpc endpoint and account (private key).

Parameters
  • shell – one of ‘carthagenet’, ‘mainnet’, ‘delphinet’, ‘dalphanet’ or RPC node uri, or instance of ShellQuery

  • key – base58 encoded key, path to the faucet file, alias from tezos-client, or instance of Key

Returns

A copy of current object with changes applied

Contract call proxy

class pytezos.michelson.interface.ContractCall(parameters, address=None, contract: pytezos.michelson.contract.Contract = None, factory=<class 'pytezos.michelson.contract.Contract'>, amount=0, shell=None, key=None)[source]

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

cmdline()[source]

Generate command line for tezos client.

inject(_async=True, preapply=True, check_result=True, num_blocks_wait=2)[source]

Autofill, sign and inject resulting operation group.

Parameters
  • _async – do not wait for operation inclusion (default is True)

  • preapply – do a preapply before injection

  • check_result – raise RpcError in case operation is refused

  • num_blocks_wait – number of blocks to wait for injection

interpret(storage, source=None, sender=None, amount=None, balance=None, chain_id=None, now=None)[source]

Run code in the builtin REPL (WARNING! Not recommended for critical tasks).

Parameters
  • storage – Python object

  • source – patch SOURCE

  • sender – patch SENDER

  • amount – patch AMOUNT

  • balance – patch BALANCE

  • chain_id – patch CHAIN_ID

  • now – patch NOW

Return type

ContractCallResult

property operation_group

Show generated operation group.

Return type

OperationGroup

result(storage=None, source=None, sender=None, gas_limit=None)[source]

Simulate operation and parse the result.

Parameters
  • storage – Python object only. If storage is specified, run_code is called instead of run_operation.

  • source – Can be specified for unit testing purposes

  • sender – Can be specified for unit testing purposes, see https://tezos.gitlab.io/whitedoc/michelson.html#operations-on-contracts for the difference

  • gas_limit – Specify gas limit (default is gas hard limit)

Return type

ContractCallResult

using(shell: pytezos.rpc.shell.ShellQuery = None, key: pytezos.crypto.Key = None)

Change current rpc endpoint and account (private key).

Parameters
  • shell – one of ‘carthagenet’, ‘mainnet’, ‘delphinet’, ‘dalphanet’ or RPC node uri, or instance of ShellQuery

  • key – base58 encoded key, path to the faucet file, alias from tezos-client, or instance of Key

Returns

A copy of current object with changes applied

view()[source]

Get return value of a view method.

Returns

object

with_amount(amount)[source]

Send funds to the contract too.

Parameters

amount – amount in microtez (int) or tez (Decimal)

Return type

ContractCall

Contract call result

class pytezos.michelson.interface.ContractCallResult(**props)[source]

Encapsulates the result of a contract invocation.

classmethod from_code_run(code_run: dict, parameters, contract: pytezos.michelson.contract.Contract)[source]

Parse a result of run_code execution.

Parameters
  • code_run – RPC response (json)

  • parameters – Micheline expression

  • contract – invoked contract

Return type

ContractCallResult

classmethod from_contract_call(operation_group: dict, address, contract: pytezos.michelson.contract.Contract) → list[source]

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

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

  • address – address of the invoked contract

  • contract – invoked contract

Return type

List[ContractCallResult]

classmethod from_repl_result(res: dict, parameters, contract: pytezos.michelson.contract.Contract)[source]

Parse an output of the builtin interpreter.

Parameters
  • res – Interpreter output

  • parameters – Micheline expression

  • contract – invoked contract

Returns

ContractCallResult