Version: Next

Hangzhou

Important: This is only available for protocol Hangzhou (i.e. --protocol hangzhou command line option).

Note: this is a temporary documentation page and will be moved to another location.

API#

New types#

type chest
A type for chests
type chest_key
A type for chest keys
type chest_opening_result = ["Ok_opening", bytes] | ["Fail_decrypt"] | ["Fail_timelock"];
A type for the result of chest opening, see `Tezos.open_chest`

New primitives#

Tezos#

let open_chest : chest_key => chest => nat => chest_opening_result
let call_view : string => 'arg => address => option <'ret>

Test#

new signature for originate_from_file:

let originate_from_file = (filepath: string, entrypoint: string , views : list <'string> , init: michelson_program, balance: tez) => [address, michelson_program, int]

Originate a contract with a path to the contract file, an entrypoint, a list of views, an initial storage and an initial balance.

let create_chest : bytes => nat => [chest , chest_key]

Generate a locked value, the RSA parameters and encrypt the payload. Also returns the chest key
Exposes tezos timelock library function create_chest_and_chest_key

let create_chest_key : chest => nat => chest_key

Unlock the value and create the time-lock proof.
Exposes tezos timelock library function create_chest_key.

Examples#

Timelock#

Extensive documentation about timelock can be found here. Here is an example of a contract trying to open a chest and the corresponding tests to trigger all error kinds:

let open_or_fail = ([ck , c , time_] : [chest_key, chest, nat]) : bytes => {
return (match ( Tezos.open_chest(ck,c,time_), {
Ok_opening: (b:bytes) => b,
Fail_decrypt: () => failwith("decrypt") as bytes,
Fail_timelock: () => failwith("timelock") as bytes,
}))
};

On-chain views#

Tezos documentation on views can be found here

On-chain views are named routines attached to your contract allowing another contract to call them to get a "view" of your contract current storage. It cannot modify your storage nor emit operations.
These routines can either simply return your contract storage or apply some kind of processing to it: they take your current storage, a parameter and returns the data of your choice. Note that parameter and return types can be anything except big_map ; sapling_state ; operation and ticket.
Views are named after their declaration name and can be compiled in two ways:

  1. by passing their names to the command line option --views (e.g. ligo compile contract --views v1,v2,v3)
  2. by annotating their declarations in your code with view

Important: the first way (--views) will override any annotated declarations

Given a very simple contract having a storage of type string, here are a few legit views:

type storage = string
let main = ([_ , s]: [unit , storage]) : [ list<operation> , storage] => [list([]) as list<operation> , s];
/* view 'view1', simply returns the storage */
// @view
let view1 = ([_ , s]: [unit , storage]) : storage => s;
/* view 'v2', returns true if the storage has a given length */
// @view
let v2 = ([expected_length,s] : [nat , storage]) : bool => (String.length (s) == expected_length);
/* view 'view3' returns a constant int */
// @view
let view3 = ([_ , _s]: [unit , storage]) : int => 42;

A few primitives have a slightly different meaning when executed as part of a view:

  • Tezos.balance represents the current amount of mutez held by the contract attached to the view
  • Tezos.sender represents the caller of the view
  • Tezos.amount is always 0 mutez
  • Tezos.self_address represents the contract attached to the view

On the caller side, the primitive Tezos.call_view will allow you to call another contract view and get its result by providing the view name; the contract address and the parameter of the view. If the address is nonexistent; the name does not match of of the contract view or the parameter type do not match, Tezos.call_view will return None.

let view_call = ([name,parameter,addr]: [string , int , address]) : option<int> => (Tezos.call_view ("sto_plus_n", 1, addr) as option<int>)