High-level interfaces¶

PyTezos client¶

class pytezos.client.PyTezosClient(context: Optional[pytezos.context.impl.ExecutionContext] = 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

balance() → decimal.Decimal[source]¶

Get account balance

Returns: amount in tez

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

bulk(*operations: Union[pytezos.operation.group.OperationGroup, pytezos.contract.call.ContractCall]) → pytezos.operation.group.OperationGroup [source]¶

Batch multiple operations and contract calls in a single operation group

Parameters: operations – a tuple of operations or contract calls
Return type: OperationGroup

contract(address) → pytezos.contract.interface.ContractInterface [source]¶

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

Parameters: address – 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

now() → int[source]¶: Timestamp of the latest block + block time (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, unless you know what you are doing
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: Optional[Union[pytezos.rpc.shell.ShellQuery, str]] = None, key: Optional[Union[pytezos.crypto.key.Key, str]] = None, mode: Optional[str] = None)[source]¶

Change current rpc endpoint and account (private key).

Parameters

shell – one of ‘mainnet’, ‘***net’, 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
mode – whether to use readable or optimized encoding for parameters/storage/other

Returns

A copy of current object with changes applied

Contract interface¶

class pytezos.contract.interface.ContractInterface(context: pytezos.context.impl.ExecutionContext)[source]¶

Proxy class for interacting with a contract.

big_map_get(path)[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.
Returns: object

Deprecated since version 3.0.0: This will be removed in 3.1.0. use .storage[path][to][big_map][key]() instead

property call¶: Deprecated since version 3.0.0.

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

property code¶: Deprecated since version 3.0.0.

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

property contract¶: Deprecated since version 3.0.0.

This will be removed in 3.1.0. access ContractInterface directly

classmethod create_from(source)[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 3.1.0. use one of from_file, from_michelson, from_micheline, from_url

static from_context(context: pytezos.context.impl.ExecutionContext) → pytezos.contract.interface.ContractInterface [source]¶

Create contract from the previously loaded context data.

Parameters: context – execution context
Returns: ContractInterface

static from_file(path: str, context: Optional[pytezos.context.impl.ExecutionContext] = None) → pytezos.contract.interface.ContractInterface [source]¶

Create contract from michelson source code stored in a file.

Parameters

path – Path to the .tz file
context – optional execution context

Return type

ContractInterface

static from_micheline(expression, context: Optional[pytezos.context.impl.ExecutionContext] = None) → pytezos.contract.interface.ContractInterface [source]¶

Create contract from micheline expression.

Parameters

expression – [{‘prim’: ‘parameter’}, {‘prim’: ‘storage’}, {‘prim’: ‘code’}]
context – optional execution context

Return type

ContractInterface

static from_michelson(source: str, context: Optional[pytezos.context.impl.ExecutionContext] = None) → pytezos.contract.interface.ContractInterface [source]¶

Create contract from michelson source code.

Parameters

source – Michelson source code
context – optional execution context

Return type

ContractInterface

static from_url(url: str, context: Optional[pytezos.context.impl.ExecutionContext] = None) → pytezos.contract.interface.ContractInterface [source]¶

Create contract from michelson source code available via URL

Parameters

url – link to the Michelson file
context – optional execution context

Return type

ContractInterface

operation_result(operation_group: dict) → List[pytezos.contract.result.ContractCallResult][source]¶

Get operation parameters, and resulting storage 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

originate(initial_storage=None, mode: Optional[str] = None, balance: Union[int, decimal.Decimal] = 0, delegate: Optional[str] = None) → pytezos.operation.group.OperationGroup [source]¶

Create an origination operation

Parameters

initial_storage – Python object, leave None to generate default
mode – whether to use readable or optimized (or legacy_optimized) encoding for initial storage
balance – initial balance
delegate – initial delegator

Return type

OperationGroup

script(initial_storage=None, mode: Optional[str] = None) → dict[source]¶

Generate script for contract origination.

Parameters

initial_storage – Python object, leave None to generate default (attach shell/key for smart fill)
mode – whether to use readable or optimized (or legacy_optimized) encoding for initial storage

Returns

{“code”: $Micheline, “storage”: $Micheline}

property text¶: Deprecated since version 3.0.0.

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

to_file(path)[source]¶

Write contract source to a .tz file

Parameters: path – path to the file

to_micheline()[source]¶

Get contract script in Micheline JSON

Returns: [{‘prim’: ‘parameter’}, {‘prim’: ‘storage’}, {‘prim’: ‘code’}]

to_michelson()[source]¶

Get contract listing in formatted Michelson

Returns: string

using(shell: Optional[Union[pytezos.rpc.shell.ShellQuery, str]] = None, key: Optional[Union[pytezos.crypto.key.Key, str]] = None, block_id: Optional[Union[str, int]] = None, mode: Optional[str] = None) → pytezos.contract.interface.ContractInterface [source]¶

Change the block at which the current contract is inspected. Also, if address is undefined you can specify RPC endpoint, and private key.

Parameters

shell – one of ‘mainnet’, ‘***net’, 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
block_id – block height / hash / offset to use, default is head
mode – whether to use readable or optimized encoding for parameters/storage/other

Return type

ContractInterface

Contract entrypoint proxy¶

class pytezos.contract.entrypoint.ContractEntrypoint(context: pytezos.context.impl.ExecutionContext, entrypoint: str)[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

decode(value, entrypoint: Optional[str] = None) → dict[source]¶

Convert from Michelson to Python type system

Parameters

value – Micheline JSON expression or Michelson value
entrypoint – overwrite current entrypoint (in case you want to parse tx parameters)

Returns

Python object {entrypoint: value}

encode(py_obj, mode: Optional[str] = None) → dict[source]¶

Encode transaction parameters from the given Python object

Parameters

py_obj – Python object
mode – whether to use readable or optimized (or legacy_optimized) encoding

Returns

{entrypoint, value}

Contract call proxy¶

class pytezos.contract.call.ContractCall(context: pytezos.context.impl.ExecutionContext, parameters: dict, amount: Union[int, decimal.Decimal] = 0)[source]¶

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

as_transaction() → pytezos.operation.group.OperationGroup [source]¶

Get operation content

Return type: OperationGroup

cmdline()[source]¶: Generate command line for tezos client.

interpret(storage=None, source=None, sender=None, amount=None, balance=None, chain_id=None, level=None, now=None, self_address=None) → pytezos.contract.result.ContractCallResult [source]¶

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

Parameters

storage – initial storage as Python object, leave None if you want to generate a dummy one
source – patch SOURCE
sender – patch SENDER
amount – patch AMOUNT
balance – patch BALANCE
chain_id – patch CHAIN_ID
level – patch LEVEL
now – patch NOW
self_address – patch SELF/SELF_ADDRESS

Return type

pytezos.contract.result.ContractCallResult

property operation_group¶: Deprecated since version 3.0.0.

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

result(storage=None, source=None, sender=None, gas_limit=None) → pytezos.contract.result.ContractCallResult [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

Deprecated since version 3.0.0: This will be removed in 3.1.0. use either run_code or run_operation

run_code(storage=None, source=None, sender=None, amount=None, balance=None, chain_id=None, gas_limit=None) → pytezos.contract.result.ContractCallResult [source]¶

Execute using RPC interpreter

Parameters

storage – initial storage as Python object, leave None if you want to generate a dummy one
source – patch SOURCE
sender – patch SENDER
amount – patch AMOUNT
balance – patch BALANCE
chain_id – patch CHAIN_ID
gas_limit – restrict max comsumed gas

Return type

ContractCallResult

run_operation() → pytezos.contract.result.ContractCallResult [source]¶

Simulate operation using real context

Return type: ContractCallResult

view()[source]¶

Get return value of a view method.

Returns: Decoded parameters of a callback

with_amount(amount: Union[int, decimal.Decimal])[source]¶

Send funds to the contract too.

Parameters: amount – amount in microtez (int) or tez (Decimal)
Return type: ContractCall

Contract call result¶

class pytezos.contract.result.ContractCallResult(**props)[source]¶

Encapsulates the result of a contract invocation.

classmethod from_run_code(response: dict, parameters, context: pytezos.context.impl.ExecutionContext)[source]¶

Parse a result of 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, context: pytezos.context.impl.ExecutionContext) → List[pytezos.contract.result.ContractCallResult][source]¶

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: pytezos.context.impl.ExecutionContext, data: pytezos.michelson.types.base.MichelsonType, path='', title=None)[source]¶

__call__(try_unpack=False)[source]¶

Get Michelson value as a Python object

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

decode(value)[source]¶

Convert from Michelson to Python type system

Parameters: value – Micheline JSON expression or Michelson value
Returns: Python object

default()[source]¶: Deprecated since version 3.0.0: This will be removed in 3.1.0.

dummy()[source]¶

Try to generate a dummy (empty) value

Returns: Python object

encode(py_obj, mode: Optional[str] = None)[source]¶

Convert from Python to Michelson type system

Parameters

py_obj – Python object
mode – whether to use readable or optimized (or legacy_optimized) encoding

Returns

Micheline JSON expression

to_micheline(optimized=False)[source]¶

Get as Micheline JSON expression

Parameters: optimized – use optimized data form for some domain types (timestamp, address, etc.)

to_michelson(optimized=False)[source]¶

Get as Michelson value

Parameters: optimized – use optimized data form for some domain types (timestamp, address, etc.)