Skip to main content

Views

Several related but somewhat incompatible notions have been called views on Tezos.
From an historical perspective, we got:

  • CPS Views: (legacy pattern) entry points that happen to compute something from their storage without changing the state and callbacks one of its two parameters;
  • Off-chain Views: functions that look like on-chain views but are evaluated by an external process;
  • On-chain Views: special entry points that cannot change their state by construction and are much cheaper to call.

SmartPy supports all these notions.

CPS Views​

See helpers/utils.

We don't expect this to be used anymore except in standards that contain them for legacy reasons such as FA1.2.

Off-chain Views​

Exactly like a on-chain view except that:

  • the code is not generated inside the contract (but typically in metadata);
  • the generated code doesn't contain parameters when their parameter type would have been sp.TUnit.

Defining an off-chain view​

@sp.offchain_view(pure=False, doc=None, name=None)
Decorator to build an off-chain view. This is typically used inside a contract class.

ArgumentDescription
pureDeclare the view as pure, default is False.
docAdd a custom documentation. Python docstrings are also handled.
nameOverride the Python name.
    @sp.offchain_view()
def get_cst(self):
"""42"""
sp.result(42)

@sp.offchain_view(doc = "My bad")
def big_fail(self):
sp.failwith("my_bad")

@sp.offchain_view()
def some_computation(self, params):
sp.result(12 * params + self.data.x)

See reference Metadata template.

On-Chain Views​

The feature specification can be found here.

They are synchronous calls, meaning that the result is immediately available on the stack of the caller contract, which will make the contract development more effortless.

Views are a mechanism for contract calls that:

  • Are read-only: they may depend on the storage of the contract declaring the view but cannot modify it nor emit operations;
  • Can call other views;
  • Take arguments as input in addition to the contract storage;
  • Return a result as output;
  • Are synchronous: the result is immediately available on the stack of the caller contract.

In other words, the execution of a view is included in the operation of caller’s contract, but accesses the storage of the declarer’s contract, in read-only mode. Thus, in terms of execution, views are more like lambda functions rather than contract entrypoints.

On chain view

See reference On-Chain Views template.

They can be freely used as off-chain views as well.

Defining an on-chain view​

@sp.onchain_view(pure=None, doc=None, name=None)
Decorator to build an off-chain view. This is typically used inside a contract class.

ArgumentDescription
pureDeclare the view as pure, default is False.
docAdd a custom documentation. Python docstrings are also handled.
nameOverride the Python name.

By default, the view name is equal to the method name, where <name> is an optional argument and can be used to set a view name explicitly.

Examples​

# The view name will be "view1"
@sp.onchain_view()
def view1(self):
# sp.result is used to return the view result (the contract storage in this case)
sp.result(self.data)

# The view name will be "getState", it is being set explicitly
@sp.onchain_view(name = "getState")
def view2(self, param):
state = self.data.state[param];
sp.verify(state == 2, "The state is not equal to 2.")
sp.result(state)

Calling an on-chain view in a contract​

On-chain views are called with sp.view(<view_name>, <contract_address>, <argument>, t = <return_type>), and their output is of type sp.TOption(<return_type>).

Arguments:

ArgumentRequiredDescriptionExamples
view_nameYesThe name of the view being called."view1", "getState", "computeSomething"
contract_addressYesThe contract address where the view is defined.sp.address("KT1TezoooozzSmartPyzzSTATiCzzzwwBFA1")
argumentYesThe view argument.sp.unit, 10, "Some Text", sp.bytes("0x0123")
return_typeNo (It is optional)The view return type. Not required when the view is known by the compiler. (e.g. Defined in the same contract.)sp.TNat, "sp.TString"

Examples​

import smartpy as sp

# A contract that serves as storage and provides information to other contracts through an on-chain view
class Provider(sp.Contract):
def __init__(self, tokens):
self.init(tokens = tokens)

@sp.onchain_view()
def getTokenById(self, tokenID):
sp.verify(self.data.tokens.contains(tokenID), "Token doesn't exist")
sp.result(self.data.tokens[tokenID])

# Contract that will call the view defined in the consumer above
class Consumer(sp.Contract):
@sp.entry_point
def checkToken(self, params):
token = sp.view("getTokenById", params.providerAddress, params.tokenID, t = sp.TRecord(balance = sp.TNat)).open_some("Invalid view");
sp.verify(token.balance >= 10, "Token balance is lower than 10")

Testing an on-chain view​

Views can be called from test scenarios the same way as entry points my_contract.my_view(some_parameters). This has the additional benefit over sp.view(..) to make a full use of type inference which prevents type errors.

The Michelson semantics for sp.view(..) says that any type error yields to a sp.none. This is rather difficult to debug so SmartPy provides two semantics:

  • the regular one with flag "no-view-check-exception";
  • an enhanced one with proper exceptions with flag flag "view-check-exception".

Examples​

See reference On-Chain Views and On-Chain Views Exceptions templates.

import smartpy as sp

class MyContract(sp.Contract):
def __init__(self, param):
self.init(param)

@sp.onchain_view()
def state(self, param):
sp.verify(param < 5, "This is false: param >= 5")
sp.result(self.data * param)

@sp.add_test(name = "Test")
def test():
scenario = sp.test_scenario()
c1 = MyContract(1)
scenario += c1

""" Test views """

# Display the view result
scenario.show(c1.state(1))

# Assert the view result
scenario.verify(c1.state(2) == 2)
# Assert call failures
scenario.verify(sp.is_failing(c1.state(6))); # Expected to fail
scenario.verify(~ sp.is_failing(c1.state(1))); # Not expected to fail

# Assert exception result
# catch_exception returns an option:
# sp.none if the call succeeds
# sp.some(<exception>) if the call fails
e = sp.catch_exception(c1.state(7), t = sp.TString)
scenario.verify(e == sp.some("This is false: param >= 5"))


class Test(sp.Contract):
def __init__(self):
self.init(value = 0)

@sp.offchain_view()
def other(self, x):
sp.result(1 + x)

if "templates" not in __name__:
@sp.add_test(name="Test_exceptions")
def test():
scenario = sp.test_scenario()
provider = sp.address("KT1")
scenario.verify(sp.catch_exception(sp.view("a_view", provider, 0, t = sp.TNat)) == sp.some("Missing contract for view"))
c1 = Test()
scenario += c1
scenario.verify(c1.other(42) == 43)
scenario.verify(sp.view("other", c1.address, 1, t = sp.TIntOrNat) == sp.some(2))
scenario.verify(sp.catch_exception(sp.view("other", c1.address, 1, t = sp.TInt) == sp.some(2)) == sp.some("Type error in view"))
scenario.verify(sp.catch_exception(sp.view("missing_view", c1.address, 1)) == sp.some("Missing view missing_view in contract KT1TezoooozzSmartPyzzSTATiCzzzwwBFA1"))

@sp.add_test(name="Test_view_no_exception")
def test2():
scenario = sp.test_scenario()
scenario.add_flag("no-view-check-exception")
provider = sp.address("KT1")
scenario.verify(sp.view("a_view", provider, 0, t = sp.TNat) == sp.none)
c1 = Test()
scenario += c1
scenario.verify(c1.other(42) == 43)
scenario.verify(sp.view("other", c1.address, 1, t = sp.TIntOrNat) == sp.some(2))
scenario.verify(sp.view("other", c1.address, 1) == sp.some(2))
scenario.verify(sp.view("missing_view", c1.address, 1) == sp.none)
scenario.verify(sp.view("other", c1.address, 1, t = sp.TInt) == sp.none)