Standard libraries ​

These modules contain helper functions. To use a stdlib module in SmartPy code simply import it:

import smartpy.utils as utils

Then to use that module in an entrypoint or other part of a SmartPy module, use the module via the alias you gave, as in this example:

x = sp.timestamp(1095379199)
assert utils.seconds_of_timestamp(x) == 1095379199

To use a stdlib module in a test scenario, add it to the scenario and keep a hold of the returned handle:

scenario = sp.test_scenario("my_test", main)
u = scenario.add_module("smartpy/utils.spy")
scenario.verify(u.mutez_to_nat(sp.mutez(1)) == sp.nat(1))

Module contract_utils ​

is_kt1(address: sp.address) → sp.bool

Check is a given address is a 'kt1' address.

check_key_address(ka: sp.tuple[sp.key_hash, sp.address]) → sp.bool

Check whether a public_key of a user matches his/her tezos address.

Module fixed_point ​

mk(fp: sp.pair[sp.int, sp.int]) → sp.record[value sp.int, exponent sp.int]

Create a decimal fixed-point number.

add(values: sp.pair[fp, fp]) → sp.record[value sp.int, exponent sp.int]

Add two fixed point numbers.

Examples:

smartpy

import smartpy.fixed_point as fp
v1 = fp.mk((123, 2))
v2 = fp.mk((245, 2))
assert fp.add((v1, v2)) == sp.record(value=sp.int(368), exponent=2)

sub(values: sp.pair[fp, fp]) → sp.record[value sp.int, exponent sp.int]

Subtract two fixed point numbers.

Examples:

smartpy

import smartpy.fixed_point as fp
v1 = fp.mk((245, 2))
v2 = fp.mk((123, 2))
fp.sub((v1, v2)) == sp.record(value=sp.int(122), exponent=2)

mul(values: sp.pair[fp, fp]) → sp.record[value sp.int, exponent sp.int]

Multiply two fixed point numbers.

Examples:

smartpy

import smartpy.fixed_point as fp
v1 = fp.mk((123, 3))
v2 = fp.mk((25, 1))
fp.mul((v1, v2)) == sp.record(value=sp.int(3075), exponent=4)

eq(values: sp.pair[fp, fp]) → sp.bool

Check if two fixed point numbers are equal.

lt(values: sp.pair[fp, fp]) → sp.bool

Check if a fixed point value (v1) is less than another fixed point value (v2).

gt(values: sp.pair[fp, fp]) → sp.bool

Check if a fixed point value (v1) is greater than another fixed point value (v2).

leq(values: sp.pair[fp, fp]) → sp.bool

Check if a fixed point value (v1) is less than (or equal to) another fixed point value (v2).

geq(values: sp.pair[fp, fp]) → sp.bool

Check if a fixed point value (v1) is greater than (or equal to) another fixed point value (v2).

Module list_utils ​

replicate(vn: sp.pair[sp.int, sp.nat]) → sp.list[int]

Generate a list with 'n' occurrences of a given value 'v'

Examples:

smartpy

import smartpy.list_utils as list_utils
sp.pack(list_utils.replicate((0, 5))) == sp.pack([0, 0, 0, 0, 0])

element_at(ab: sp.pair[sp.list[sp.int], sp.nat]) → sp.int

Return the element of a list at a particular index.

Examples:

smartpy

import smartpy.list_utils as list_utils
list_utils.element_at(([1, 2, 3], 0)) == 1
list_utils.element_at(([1, 2, 3], 1)) == 2
list_utils.element_at(([1, 2, 3], 2)) == 3

update_list(abc: sp.tuple[sp.list[sp.int], sp.int, sp.int]) → sp.list[int]

Update one specific element of a list.

Examples:

smartpy

import smartpy.list_utils as list_utils
sp.pack(list_utils.update_list(([1, 2, 3, 4, 5], 0, 100))) == sp.pack([100, 2, 3, 4, 5])
sp.pack(list_utils.update_list(([1, 2, 3, 4, 5], 1, 100))) == sp.pack([1, 100, 3, 4, 5])
sp.pack(list_utils.update_list(([1, 2, 3, 4, 5], 2, 100))) == sp.pack([1, 2, 100, 4, 5])

sub_list(abc (sp.tuple[sp.list[sp.int], sp.int, sp.int]: None) → sp.list[int]

Compute the portion of a list that contains elements starting at from_index and extends up to element at to_index-1.

Examples:

smartpy

import smartpy.list_utils as list_utils
sp.pack(list_utils.sub_list(([1, 2, 3, 4, 5], 1, 2))) == sp.pack([2, 3])
sp.pack(list_utils.sub_list(([1, 2, 3, 4, 5], 1, 3))) == sp.pack([2, 3, 4])

insertion_sort(elements (sp.list[sp.int]]: None) → sp.list[int]

Sort a list of elements using the insertion sort algorithm (useful when the number of elements is small).

Examples:

smartpy

import smartpy.list_utils as list_utils
list_utils.element_at((list_utils.insertion_sort([1, 3, 5, 7, 2, 4, 6, 8]), 0))== 1

merge_sort(elements (sp.list[sp.int]]: None) → sp.list[int]

Sort a list of elements using the merge sort algorithm.

Examples:

smartpy

import smartpy.list_utils as list_utils
list_utils.element_at((list_utils.insertion_sort([1, 3, 5, 7, 2, 4, 6, 8]), 0))== 1

sort(elements (sp.list[sp.int]]: None) → sp.list[int]

Sort a list of elements.

Examples:

smartpy

import smartpy.list_utils as list_utils
list_utils.element_at((list_utils.sort([1, 3, 5, 7, 2, 4, 6, 8]), 0))== 1

quick_select(ak (sp.tuple[sp.list[sp.int], sp.int]: None) → sp.int

Selects the kth smallest element of an array, using a non-recursive implementation of the QuickSelect algorithm.

Examples:

smartpy

import smartpy.list_utils as list_utils
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 0)) == 4
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 1)) == 5
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 2)) == 6
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 3)) == 8
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 4)) == 10
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 5)) == 11
list_utils.quick_select(([10, 4, 5, 8, 6, 11, 26], 6)) == 26

Module math ​

pow(be: sp.pair[sp.int, sp.nat]) → sp.int

Compute the result of a 'base' to the power of an 'exponent'.

Examples:

smartpy

import smartpy.math as math
math.pow((2, 0)) == sp.int(1)
math.pow((2, 1)) == sp.int(2)
math.pow((2, 3)) == sp.int(8)
math.pow((10, 3)) == sp.int(1000)

gcd(ab: sp.pair[sp.int, sp.int]) → sp.int

Compute the greatest common divisor (gcd) between two int values '(a, b)'.

Examples:

smartpy

import smartpy.math as math
math.gcd((15, 10)) == sp.int(5)
math.gcd((18, 42)) == sp.int(6)
math.gcd((15, 36)) == sp.int(3)
math.gcd((4, 24)) == sp.int(4)
math.gcd((-4, 24)) == sp.int(4)

lcm(ab: sp.pair[sp.int, sp.int]) → sp.int

Compute the least common multiple (lcm) between two int values '(a, b)'.

Examples:

smartpy

import smartpy.math as math
math.lcm((3, 5)) == sp.int(15)
math.lcm((54, 24)) == sp.int(216)

Module rational ​

mk(ab: sp.pair[sp.int, sp.int]) → sp.record[numerator sp.int, denominator sp.nat]

Create a rational number.

ceil(r: sp.record[numerator sp.int, denominator sp.nat]) → sp.int

Compute the ceiling value of r (the smallest integer greater than or equal to r).

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((4, 3))
r2 = rational.mk((4, 2))
r3 = rational.mk((4, 1))
rational.ceil(r1) == sp.int(2)
rational.ceil(r2) == sp.int(2)
rational.ceil(r3) == sp.int(4)

floor(r: sp.record[numerator sp.int, denominator sp.nat]) → sp.int

Compute the floor value of r (the largest integer not greater than r).

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((3, 1))
r2 = rational.mk((2, 3))
r3 = rational.mk((7, 2))
rational.floor(r1) == sp.int(3)
rational.floor(r2) == sp.int(0)
rational.floor(r3) == sp.int(3)

add(values: sp.pair[rational, rational]) → sp.record[numerator sp.int, denominator sp.nat]

Add two rational numbers.

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((3, 5))
r2 = rational.mk((4, 3))
res = rational.add((r1, r2))
res.numerator == sp.int(29)
res.denominator == sp.nat(15)

sub(values: sp.pair[rational, rational]) → sp.record[numerator sp.int, denominator sp.nat]

Subtract two rational numbers.

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((1, 5))
r2 = rational.mk((5, 3))
r3 = rational.mk((2, 8))
r4 = rational.mk((1, 4))
res1 = rational.sub((r1, r2))
res1.numerator == sp.int(-22)
res1.denominator == sp.nat(15)
res2 = rational.sub((r3, r4))
assert res.numerator == sp.int(0)

mul(values: sp.pair[rational, rational]) → sp.record[numerator sp.int, denominator sp.nat]

Multiply two rational numbers.

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((2, 5))
r2 = rational.mk((3, 4))
r3 = rational.mk((-4, 6))
r4 = rational.mk((1, 4))
res1 = rational.mul((r1, r2))
res2 = rational.mul((r1, r2))
res1.numerator == sp.int(3)
res1.denominator == sp.nat(10)
res2.numerator == sp.int(-1)
res2.denominator == sp.nat(6)

div(values: sp.pair[rational, rational]) → sp.record[numerator sp.int, denominator sp.nat]

Divide two rational numbers.

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((2, 5))
r2 = rational.mk((3, 4))
r3 = rational.mk((7, 4))
r4 = rational.mk((2, 7))
res1 = rational.div((r1, r2))
res2 = rational.div((r1, r2))
res1.numerator == sp.int(8)
res1.denominator == sp.nat(15)
res2.numerator == sp.int(49)
res2.denominator == sp.nat(8)

round(r: sp.record[numerator sp.int, denominator sp.nat]) → sp.int

Round a rational number to its closest integer.

Examples:

smartpy

import smartpy.rational as rational
r1 = rational.mk((1, 3))
r2 = rational.mk((2, 3))
r3 = rational.mk((3, 3))
r4 = rational.mk((4, 3))
r5 = rational.mk((5, 3))
r6 = rational.mk((6, 3))
r7 = rational.mk((7, 3))
r8 = rational.mk((8, 3))
r9 = rational.mk((9, 3))
r10 = rational.mk((10, 3))
r11 = rational.mk((11, 3))
r12 = rational.mk((12, 3))
rational.round(r1) == sp.int(0)
rational.round(r2) == sp.int(1)
rational.round(r3) == sp.int(1)
rational.round(r4) == sp.int(1)
rational.round(r5) == sp.int(2)
rational.round(r6) == sp.int(2)
rational.round(r7) == sp.int(2)
rational.round(r8) == sp.int(3)
rational.round(r9) == sp.int(3)
rational.round(r10) == sp.int(3)
rational.round(r11) == sp.int(4)
rational.round(r12) == sp.int(4)

Module statistics ​

median(elements: sp.list[sp.int]) → sp.int

Calculate the median (middle value) of a list of ints.

Examples:

smartpy

import smartpy.statistics as statistics
statistics.median([1, 3, 5, 7, 9, 11, 13]) == 7

Module string_utils ​

starts_with(ab: sp.pair[sp.string, sp.string]) → sp.bool

Check if a string starts with a given pattern.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.starts_with(("abc", "abc")) == True
string_utils.starts_with(("abc", "abcd")) == True
string_utils.starts_with(("abc", "abcdefg")) == True

drop_first(ab: sp.pair[sp.nat, sp.string]) → sp.Option[sp.string]

Drop the first n characters of a string.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.drop_first((0, "abcdef")) == sp.Some("abcdef")
string_utils.drop_first((1, "abcdef")) == sp.Some("bcdef")
string_utils.drop_first((2, "abcdef")) == sp.Some("cdef")
string_utils.drop_first((3, "abcdef")) == sp.Some("def")
string_utils.drop_first((4, "abcdef")) == sp.Some("ef")
string_utils.drop_first((5, "abcdef")) == sp.Some("f")
string_utils.drop_first((6, "abcdef")) == sp.Some("")
string_utils.drop_first((7, "abcdef")) == None

find_first(ab: sp.pair[sp.string, sp.string]) → sp.Option[sp.nat]

Return the index of the first occurrence of a string within another string.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.find_first((".", "abc")) == None
string_utils.find_first((".", ".abc")) == sp.Some(0)
string_utils.find_first((".", "a.bc")) == sp.Some(1)
string_utils.find_first((".", "ab.c")) == sp.Some(2)
string_utils.find_first((".", "abc.")) == sp.Some(3)
string_utils.find_first(("/", "4/6")) == sp.Some(1)

split(ab: sp.pair[sp.string, sp.string]) → sp.List[sp.string]

Split a string using another string as delimiter.

Examples:

smartpy

import smartpy.string_utils as string_utils
sp.pack(string_utils.split(("abc def ghi", " "))) == sp.pack(["abc", "def", "ghi"])

digit(a: sp.string) → sp.option[sp.int]

Convert a single-character string representing a digit to its integer value.

is_digit(c: sp.string) → sp.bool

Check if a string is a single digit character.

to_digit(s: sp.string) → sp.int

Convert a single-character string to its corresponding integer value.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.to_digit("1") == 1
string_utils.to_digit("2") == 2
string_utils.to_digit("3") == 3
string_utils.to_digit("4") == 4
string_utils.to_digit("5") == 5

to_int(a: sp.string) → sp.int

Convert a string to its corresponding integer value.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.to_int("1") == 1
string_utils.to_int("12") == 12
string_utils.to_int("123") == 123
string_utils.to_int("1234") == 1234

to_rational(a: sp.string) → sp.record[numerator sp.int, denominator sp.nat]

Convert a string to a rational number.

Examples:

smartpy

import smartpy.string_utils as string_utils
to_rational("4/6") == rational.mk((2, 3))
to_rational("4/60") == rational.mk((2, 30))
to_rational("04/60") == rational.mk((2, 30))
to_rational("0/3") == rational.mk((0, 3))

from_digit(d: sp.int) → sp.string

Convert a digit to its string representation.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.from_digit(0) == "0"
string_utils.from_digit(1) == "1"
string_utils.from_digit(2) == "2"
string_utils.from_digit(3) == "3"
string_utils.from_digit(4) == "4"
string_utils.from_digit(5) == "5"

from_int(n: sp.int) → sp.string

Convert an integer value to its string representation.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.from_int(1) == "1"
string_utils.from_int(2) == "2"
string_utils.from_int(3) == "3"
string_utils.from_int(123) == "123"
string_utils.from_int(-123) == "-123"

from_rational(r: record[numerator sp.int, denominator sp.nat]) → sp.string

Convert a rational number to its string representation.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.from_rational(rational.mk((4, 3))) == "4/3"
string_utils.from_rational(rational.mk((-4, 3))) == "-4/3"
string_utils.from_rational(rational.mk((2, 6))) == "1/3"

from_fixed_point(fixed: record[value sp.int, exponent sp.int]) → sp.string

Convert a fixed point number to its string representation.

Examples:

smartpy

import smartpy.string_utils as string_utils
string_utils.from_fixed_point(fp.mk((123, 2))) == "1.23"

Module utils ​

seconds_of_timestamp(timestamp: sp.nat) → sp.int

Compute the number of seconds since the epoch for a given timestamp.

Examples:

smartpy

x = sp.timestamp(1095379199)
assert utils.seconds_of_timestamp(x) == 1095379199

mutez_to_nat(x: sp.mutez) → sp.nat

Convert a value of type sp.mutez to sp.nat.

Examples:

smartpy

x = sp.mutez(3)
assert utils.mutez_to_nat(x) == sp.nat(3)

nat_to_mutez(x: sp.nat) → sp.mutez

Convert a value of type sp.nat to sp.mutez.

Examples:

smartpy

x = 3
assert utils.nat_to_mutez(x) == sp.mutez(3)

nat_to_tez(x: sp.nat) → sp.tez

Convert a value of type sp.nat representing tez to sp.tez

Examples:

smartpy

import smartpy.utils as utils
utils.nat_to_tez(5) == sp.mutez(5*1000000) == sp.tez(5)

same_underlying_address(attr1: sp.address, attr2: sp.address) → sp.bool

Verify that the two arguments have the same address section when packed

Examples:

smartpy

a = sp.address("KT1WD5PV1i1HQTFhNUxVGNjRda63trNyshwU")
b = sp.address("KT1WD5PV1i1HQTFhNUxVGNjRda63trNyshwU%a")
assert utils.same_underlying_address(a, b)