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