A First Encounter with SmartPy

SmartPy.io
Jun 27 · 9 min read

SmartPy, a smart contract Python library for Tezos, has been under heavy development for the past few months. Its online editor is now available in the form of a first public alpha-version at https://SmartPy.io/demo.

It’s not finished yet but we think it is already useful and interesting for members of the community to have a first look.

One primary idea behind SmartPy is that its design should aim for simplicity and efficiency whenever possible. Its syntax is quite natural and knowing Python should be enough to understand how a smart contract will behave. Let’s start with a few examples.

A first regular Python script in SmartPy.io

SmartPy is a Python library and SmartPy.io lets its users execute Python scripts in a browser. Let’s start with a simple computation.

def f(x):
return 2 * x - 3
alert(sum(f(x) for x in range(0, 12)))

This has nothing to do with a smart contract or Tezos. It’s simply a script that performs some random computation and shows its result to the user by calling the function.

To test this code, you can copy-paste it into https://SmartPy.io/demo or click here.

Once in SmartPy.io, this code can be executed by clicking on the icon or by using the shortcut or while focus is in the editor.

This possibility of computing a random Python script is important as it enables meta-programming: developers can interleave regular Python computations and smart contract programming, seamlessly yielding a very powerful programming experience.

SmartPy.io is capable of executing reasonable Python3 scripts thanks to the great Brython interpreter. Reasonable means that not all Python is covered but a huge portion of it is.

A first example: building a TicTacToe game

To build a smart contract, we define a regular Python class that inherits from a class of the module.

import smartpy as spclass TicTacToe(sp.Contract):
def __init__(self):
self.init(nbMoves = 0,
winner = 0,
draw = False,
deck = [[0, 0, 0], [0, 0, 0], [0, 0, 0]])
@sp.entryPoint
def play(self, params):
# contract code is coming here
pass

This contract calls an initialization method , contained in , that is able to determine an initial storage for the contract, iterate on its entry points, and actually build the smart contract. Here, we’re building a TicTacToe game so we need to keep track of the deck, a potential winner or draw, and the number of moves (to possibly declare a draw).

You can copy-paste the code into SmartPy.io or click here to execute it.

Nothing observable happens until now: we only defined a class.

Using a test

We need to define an object, i.e., the smart contract instance, and interact with it. This can be done directly in SmartPy.io, but it is usually done by adding a test: a clean way to split the definition of a class and some interactions to study a given instance.

import smartpy as sp
class TicTacToe(sp.Contract):
def __init__(self):
self.init(nbMoves = 0,
winner = 0,
draw = False,
deck = [[0, 0, 0], [0, 0, 0], [0, 0, 0]])
@sp.entryPoint
def play(self, params):
# contract code is coming here
pass
if "templates" not in __name__:
@addTest(name = "Test TicTacToe")
def test():
html = ""
# define a contract
c1 = TicTacToe()
# show its representation
html += c1.fullHtml()
setOutput(html)

You can copy-paste the code into SmartPy.io or click here to execute it.

Executing this script, done by clicking on or with the shortcuts or , adds a new test . Clicking on this new link, in turn, shows some real SmartPy computation.

A shortcut or does both steps: execution of the script and then execution of tests.

On the output panel of SmartPy.io, we now can see a few tabs:

  • Stripped: shows the state of the smart contract and its entry points, here which happens to do nothing.
  • SmartPy: like “Stripped” but with a bit more information.
  • Data Only: data only, no entry points.
  • Types: type information about storage and entry points.
  • All: gathers information from other tabs.
  • Michelson: a Michelson script derived from the SmartPy smart contract.
  • X: simply to hide the tabs.

A few remarks:

  • The html output is generic, nothing was done for this exact example and it is nonetheless quite readable.
  • Types have been inferred from both script and storage. In Michelson, integers have two different types: and . Here, SmartPy doesn’t know how the user wants to use them so infers . Depending on some constructions, it infers , or . Similar inference is done for lists, maps, big maps, records, sum types, i.e., or-patterns, etc.
  • The Michelson compiler uses for both and in SmartPy as this is the most general type and one can always require by explicitly using in SmartPy.

Going further with play

It is time to have this contract do something meaningful and come back to the TicTacToe class.

Let’s edit the entry point:

    @sp.entryPoint
def play(self, params):
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1

and the test to obtain:

import smartpy as spclass TicTacToe(sp.Contract):
def __init__(self):
self.init(nbMoves = 0,
winner = 0,
draw = False,
deck = [[0, 0, 0], [0, 0, 0], [0, 0, 0]])
@sp.entryPoint
def play(self, params):
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1
# Tests
if "templates" not in __name__:
@addTest(name = "Test TicTacToe")
def test():
html = ""
# define a contract
c1 = TicTacToe()
# show its representation
html += c1.fullHtml()
html += h2("Message execution")
html += h3("A first move in the center")
html += c1.play(i = 1, j = 1, move = 1).html()
setOutput(html)

You can copy-paste the code into SmartPy.io or click here to execute it.

A few remarks:

  • Types are inferred for as well.
  • Some Michelson code is also generated.
  • The contract pretty-printing looks really similar to the Python script.
  • A new box appears as the result of . It describes the environment used to evaluate , its arguments and outputs.

Checks

What would happen if we were to add another move to the test ? It would be accepted since we didn’t encode checks.

To test this, you can add the following line to the script or click here.

        html   += c1.play(i = 1, j = 1, move = 2).html()

This is not correct: both players played on the same cell, this is forbidden by the official rules of the game that we all know.

This is corrected by adding a check:

        sp.verify(self.data.deck[params.i][params.j] == 0)

in

    @sp.entryPoint
def play(self, params):
sp.verify(self.data.deck[params.i][params.j] == 0)
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1

verifies and raises an exception if false.

To test the script with this , you can add the new line to the script or click here.

The output box for the second and bad move is now in red showing the error

Many other checks need to be performed: that players play inside the deck, that no winner has been found yet, no draw, etc.

    @sp.entryPoint
def play(self, params):
sp.verify((self.data.winner == 0) & ~self.data.draw)
sp.verify((params.i >= 0) & (params.i < 3))
sp.verify((params.j >= 0) & (params.j < 3))
sp.verify((params.move == 1) | (params.move == 2))
sp.verify(self.data.deck[params.i][params.j] == 0)
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1

You can add the lines to the script or click here.

Computing Winner or Draw

We can expand the simulation so that we reach a winning state.

if "templates" not in __name__:
@addTest(name = "Test TicTacToe")
def test():
html = ""
# define a contract
c1 = TicTacToe()
# show its representation
html += h2("A sequence of interactions with a winner")
html += c1.fullHtml()
html += h2("Message execution")
html += h3("A first move in the center")
html += c1.play(i = 1, j = 1, move = 1).html()
html += h3("A forbidden move")
html += c1.play(i = 1, j = 1, move = 2).html()
html += h3("A second move")
html += c1.play(i = 1, j = 2, move = 2).html()
html += h3("Other moves")
html += c1.play(i = 2, j = 1, move = 1).html()
html += c1.play(i = 2, j = 2, move = 2).html()
# assert int(c1.data.winner) == 0
html += c1.play(i = 0, j = 1, move = 1).html()
# assert int(c1.data.winner) == 1
setOutput(html)

You can add the lines to the script or click here.

Two commented-out asserts are shown in the test: the first one is OK and can be uncommented; the second one is not: we need to add code for this in our TicTacToe class.

If you uncomment the second assert, and run the test, an exception is shown and no output is shown in the output panel. This last point can be fixed by also calling before calling the failing assert.

We add new lines to determine winner and draw.

    @sp.entryPoint
def play(self, params):
sp.verify((self.data.winner == 0) & ~self.data.draw)
sp.verify((params.i >= 0) & (params.i < 3))
sp.verify((params.j >= 0) & (params.j < 3))
sp.verify((params.move == 1) | (params.move == 2))
sp.verify(self.data.deck[params.i][params.j] == 0)
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1
r = range(0, 3)
self.checkLine([self.data.deck[params.i][j] for j in r])
self.checkLine([self.data.deck[i][params.j] for i in r])
self.checkLine([self.data.deck[i][i ] for i in r])
self.checkLine([self.data.deck[i][2 - i ] for i in r])
sp.if (self.data.nbMoves == 9) & (self.data.winner == 0):
self.data.draw = True
def checkLine(self, lin):
sp.if ((lin[0]!=0) & (lin[0]==lin[1]) & (lin[0]==lin[2])):
self.data.winner = lin[0]

You can add the lines to the script or click here.

A few words about these .

  • is a helper method of the contract that serves to check if three aligned cells contain identical and non-zero values.
  • It is called on both line and column of the move currently being played and on both diagonals.
  • Meta-programming is nicely at play here, is called at creation time of the smart contract, generating the corresponding code. The SmartPy code output in the “Stripped” or “SmartPy” tabs is no longer quasi identical to what was inputted; it is expanded.

Wrapping everything up

We’ve seen how to define a smart contract class, how to interact with it, and how storage, types, entry points, and generic outputs are built.

import smartpy as spclass TicTacToe(sp.Contract):
def __init__(self):
self.init(nbMoves = 0,
winner = 0,
draw = False,
deck = [[0, 0, 0], [0, 0, 0], [0, 0, 0]])
@sp.entryPoint
def play(self, params):
sp.verify((self.data.winner == 0) & ~self.data.draw)
sp.verify((params.i >= 0) & (params.i < 3))
sp.verify((params.j >= 0) & (params.j < 3))
sp.verify((params.move == 1) | (params.move == 2))
sp.verify(self.data.deck[params.i][params.j] == 0)
self.data.deck[params.i][params.j] = params.move
self.data.nbMoves += 1
r = range(0, 3)
self.checkLine([self.data.deck[params.i][j] for j in r])
self.checkLine([self.data.deck[i][params.j] for i in r])
self.checkLine([self.data.deck[i][i ] for i in r])
self.checkLine([self.data.deck[i][2 - i ] for i in r])
sp.if (self.data.nbMoves == 9) & (self.data.winner == 0):
self.data.draw = True
def checkLine(self, lin):
sp.if ((lin[0]!=0) & (lin[0]==lin[1]) & (lin[0]==lin[2])):
self.data.winner = lin[0]
# Tests
if "templates" not in __name__:
@addTest(name = "Test TicTacToe")
def test():
html = ""
# define a contract
c1 = TicTacToe()
# show its representation
html += h2("A sequence of interactions with a winner")
html += c1.fullHtml()
html += h2("Message execution")
html += h3("A first move in the center")
html += c1.play(i = 1, j = 1, move = 1).html()
html += h3("A forbidden move")
html += c1.play(i = 1, j = 1, move = 2).html()
html += h3("A second move")
html += c1.play(i = 1, j = 2, move = 2).html()
html += h3("Other moves")
html += c1.play(i = 2, j = 1, move = 1).html()
html += c1.play(i = 2, j = 2, move = 2).html()
assert int(c1.data.winner) == 0
html += c1.play(i = 0, j = 1, move = 1).html()
assert int(c1.data.winner) == 1
html += p("Player %i has won" % int(c1.data.winner))
setOutput(html)

To go further

To go further, and conquer proper SmartPy bragging rights, one can think to improve this design in several directions.

  • Add a new element to the storage called declaring a next player and checking, in , that this next player plays.
  • Further expanding the design to verify that the sender of the transaction is the correct one by something similar to . This will be explained in a following tutorial.
  • Players could put some XTZ bound before playing and the winner gets everything. This will be explained and expanded with State Channels in a following post.
  • We could also play another game. Chess and Nim have templates in SmartPy.io. They are not finished in two directions: SmartPy scripts that need to be completed and Michelson compilation that still lacks some constructions. Completing the SmartPy scripts is a wonderful exercice for developers wishing to understand better how it works and get ready for more challenging SmartPy programming. For a more complete Michelson compilation, this is being addressed and will be available soon. Even when incomplete, SmartPy’s Michelson compiler tries its best to show some skeleton of a compiled script and this is already useful.

Thanks to Charlie Wiser.

SmartPy.io

Written by

An intuitive and effective smart contracts language and development platform for Tezos. In Python.