Built-in Functions¶
General¶
CHARSET_LATIN1¶
Constant denoting the Latin-1 charset ISO-8859-1
Constant: CHARSET_LATIN1:integer = 1
at¶
idx integer list [<l>] → <a>
idx string object object:<{o}> → <a>
Index LIST at IDX, or get value with key IDX from OBJECT.
pact> (at 1 [1 2 3])
2
pact> (at "bar" { "foo": 1, "bar": 2 })
2
base64-decode¶
string string → string
Decode STRING from unpadded base64
pact> (base64-decode "aGVsbG8gd29ybGQh")
"hello world!"
base64-encode¶
string string → string
Encode STRING as unpadded base64
pact> (base64-encode "hello world!")
"aGVsbG8gd29ybGQh"
bind¶
src object:<{row}> binding binding:<{row}> → <a>
Special form evaluates SRC to an object which is bound to with BINDINGS over subsequent body statements.
pact> (bind { "a": 1, "b": 2 } { "a" := a-value } a-value)
1
chain-data¶
→ object:{public-chain-data}
Get transaction public metadata. Returns an object with ‘chain-id’, ‘block-height’, ‘block-time’, ‘prev-block-hash’, ‘sender’, ‘gas-limit’, ‘gas-price’, and ‘gas-fee’ fields.
pact> (chain-data)
{"block-height": 0,"block-time": "1970-01-01T00:00:00Z","chain-id": "","gas-limit": 0,"gas-price": 0.0,"prev-block-hash": "","sender": ""}
compose¶
x x:<a> -> <b> y x:<b> -> <c> value <a> → <c>
Compose X and Y, such that X operates on VALUE, and Y on the results of X.
pact> (filter (compose (length) (< 2)) ["my" "dog" "has" "fleas"])
["dog" "has" "fleas"]
concat¶
str-list [string] → string
Takes STR-LIST and concats each of the strings in the list, returning the resulting string
pact> (concat ["k" "d" "a"])
"kda"
pact> (concat (map (+ " ") (str-to-list "abcde")))
" a b c d e"
constantly¶
value <a> ignore1 <b> → <a>
value <a> ignore1 <b> ignore2 <c> → <a>
value <a> ignore1 <b> ignore2 <c> ignore3 <d>
→ <a>
Lazily ignore arguments IGNORE* and return VALUE.
pact> (filter (constantly true) [1 2 3])
[1 2 3]
contains¶
value <a> list [<a>] → bool
key <a> object object:<{o}> → bool
value string string string → bool
Test that LIST or STRING contains VALUE, or that OBJECT has KEY entry.
pact> (contains 2 [1 2 3])
true
pact> (contains 'name { 'name: "Ted", 'age: 72 })
true
pact> (contains "foo" "foobar")
true
continue¶
value * → *
Continue a previously started nested defpact.
(continue (coin.transfer-crosschain "bob" "alice" 10.0))
define-namespace¶
namespace string user-guard guard admin-guard guard
→ string
Create a namespace called NAMESPACE where ownership and use of the namespace is controlled by GUARD. If NAMESPACE is already defined, then the guard previously defined in NAMESPACE will be enforced, and GUARD will be rotated in its place.
(define-namespace 'my-namespace (read-keyset 'user-ks) (read-keyset 'admin-ks))
Top level only: this function will fail if used in module code.
describe-namespace¶
ns string → object:{described-namespace}
Describe the namespace NS, returning a row object containing the user and admin guards of the namespace, as well as its name.
(describe-namespace 'my-namespace)
Top level only: this function will fail if used in module code.
distinct¶
values [<a>] → [<a>]
Returns from a homogeneous list of VALUES a list with duplicates removed. The original order of the values is preserved.
pact> (distinct [3 3 1 1 2 2])
[3 1 2]
drop¶
count integer list <a[[<l>],string]>
→ <a[[<l>],string]>
keys [string] object object:<{o}> → object:<{o}>
Drop COUNT values from LIST (or string), or entries having keys in KEYS from OBJECT. If COUNT is negative, drop from end. If COUNT exceeds the interval (-263,263), it is truncated to that range.
pact> (drop 2 "vwxyz")
"xyz"
pact> (drop (- 2) [1 2 3 4 5])
[1 2 3]
pact> (drop ['name] { 'name: "Vlad", 'active: false})
{"active": false}
enforce¶
test bool msg string → bool
Fail transaction with MSG if pure expression TEST is false. Otherwise, returns true.
pact> (enforce (!= (+ 2 2) 4) "Chaos reigns")
<interactive>:0:0:Error: Chaos reigns
enforce-one¶
msg string tests [bool] → bool
Run TESTS in order (in pure context, plus keyset enforces). If all fail, fail transaction. Short-circuits on first success.
pact> (enforce-one "Should succeed on second test" [(enforce false "Skip me") (enforce (= (+ 2 2) 4) "Chaos reigns")])
true
enforce-pact-version¶
min-version string → bool
min-version string max-version string → bool
Enforce runtime pact version as greater than or equal MIN-VERSION, and less than or equal MAX-VERSION. Version values are matched numerically from the left, such that ‘2’, ‘2.2’, and ‘2.2.3’ would all allow ‘2.2.3’.
pact> (enforce-pact-version "2.3")
true
Top level only: this function will fail if used in module code.
enumerate¶
from integer to integer inc integer → [integer]
from integer to integer → [integer]
Returns a sequence of numbers from FROM to TO (both inclusive) as a list. INC is the increment between numbers in the sequence. If INC is not given, it is assumed to be 1. Additionally, if INC is not given and FROM is greater than TO assume a value for INC of -1. If FROM equals TO, return the singleton list containing FROM, irrespective of INC’s value. If INC is equal to zero, this function will return the singleton list containing FROM. If INC is such that FROM + INC > TO (when FROM < TO) or FROM + INC < TO (when FROM > TO) return the singleton list containing FROM. Lastly, if INC is such that FROM + INC < TO (when FROM < TO) or FROM + INC > TO (when FROM > TO), then this function fails.
pact> (enumerate 0 10 2)
[0 2 4 6 8 10]
pact> (enumerate 0 10)
[0 1 2 3 4 5 6 7 8 9 10]
pact> (enumerate 10 0)
[10 9 8 7 6 5 4 3 2 1 0]
filter¶
app x:<a> -> bool list [<a>] → [<a>]
Filter LIST by applying APP to each element. For each true result, the original value is kept.
pact> (filter (compose (length) (< 2)) ["my" "dog" "has" "fleas"])
["dog" "has" "fleas"]
fold¶
app x:<a> y:<b> -> <a> init <a> list [<b>] → <a>
Iteratively reduce LIST by applying APP to last result and element, starting with INIT.
pact> (fold (+) 0 [100 10 5])
115
format¶
template string vars [*] → string
Interpolate VARS into TEMPLATE using {}.
pact> (format "My {} has {}" ["dog" "fleas"])
"My dog has fleas"
hash¶
value <a> → string
Compute BLAKE2b 256-bit hash of VALUE represented in unpadded base64-url. Strings are converted directly while other values are converted using their JSON representation. Non-value-level arguments are not allowed.
pact> (hash "hello")
"Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"
pact> (hash { 'foo: 1 })
"h9BZgylRf_M4HxcBXr15IcSXXXSz74ZC2IAViGle_z4"
if¶
cond bool then <a> else <a> → <a>
Test COND. If true, evaluate THEN. Otherwise, evaluate ELSE.
pact> (if (= (+ 2 2) 4) "Sanity prevails" "Chaos reigns")
"Sanity prevails"
int-to-str¶
base integer val integer → string
Represent integer VAL as a string in BASE. BASE can be 2-16, or 64 for unpadded base64URL. Only positive values are allowed for base64URL conversion.
pact> (int-to-str 16 65535)
"ffff"
pact> (int-to-str 64 43981)
"q80"
is-charset¶
charset integer input string → bool
Check that a string INPUT conforms to the a supported character set CHARSET. Character sets currently supported are: ‘CHARSET_LATIN1’ (ISO-8859-1), and ‘CHARSET_ASCII’ (ASCII). Support for sets up through ISO 8859-5 supplement will be added in the future.
pact> (is-charset CHARSET_ASCII "hello world")
true
pact> (is-charset CHARSET_ASCII "I am nÖt ascii")
false
pact> (is-charset CHARSET_LATIN1 "I am nÖt ascii, but I am latin1!")
true
length¶
x <a[[<l>],string,object:<{o}>]> → integer
Compute length of X, which can be a list, a string, or an object.
pact> (length [1 2 3])
3
pact> (length "abcdefgh")
8
pact> (length { "a": 1, "b": 2 })
2
list¶
elems * → [*]
Create list from ELEMS. Deprecated in Pact 2.1.1 with literal list support.
pact> (list 1 2 3)
[1 2 3]
list-modules¶
→ [string]
List modules available for loading.
Top level only: this function will fail if used in module code.
make-list¶
length integer value <a> → [<a>]
Create list by repeating VALUE LENGTH times.
pact> (make-list 5 true)
[true true true true true]
map¶
app x:<b> -> <a> list [<b>] → [<a>]
Apply APP to each element in LIST, returning a new list of results.
pact> (map (+ 1) [1 2 3])
[2 3 4]
namespace¶
namespace string → string
Set the current namespace to NAMESPACE. All expressions that occur in a current transaction will be contained in NAMESPACE, and once committed, may be accessed via their fully qualified name, which will include the namespace. Subsequent namespace calls in the same tx will set a new namespace for all declarations until either the next namespace declaration, or the end of the tx.
(namespace 'my-namespace)
Top level only: this function will fail if used in module code.
pact-version¶
→ string
Obtain current pact build version.
pact> (pact-version)
"4.8"
Top level only: this function will fail if used in module code.
public-chain-data¶
Schema type for data returned from ‘chain-data’.
Fields: chain-id:string block-height:integer
block-time:time prev-block-hash:string sender:string
gas-limit:integer gas-price:decimal
read-decimal¶
key string → decimal
Parse KEY string or number value from top level of message data body as decimal.
(defun exec ()
(transfer (read-msg "from") (read-msg "to") (read-decimal "amount")))
read-integer¶
key string → integer
Parse KEY string or number value from top level of message data body as integer.
(read-integer "age")
read-msg¶
→ <a>
key string → <a>
Read KEY from top level of message data body, or data body itself if not provided. Coerces value to their corresponding pact type: String -> string, Number -> integer, Boolean -> bool, List -> list, Object -> object.
(defun exec ()
(transfer (read-msg "from") (read-msg "to") (read-decimal "amount")))
read-string¶
key string → string
Parse KEY string or number value from top level of message data body as string.
(read-string "sender")
remove¶
key string object object:<{o}> → object:<{o}>
Remove entry for KEY from OBJECT.
pact> (remove "bar" { "foo": 1, "bar": 2 })
{"foo": 1}
resume¶
binding binding:<{r}> → <a>
Special form binds to a yielded object value from the prior step execution in a pact. If yield step was executed on a foreign chain, enforce endorsement via SPV.
sort¶
values [<a>] → [<a>]
fields [string] values [object:<{o}>] → [object:<{o}>]
Sort a homogeneous list of primitive VALUES, or objects using supplied FIELDS list.
pact> (sort [3 1 2])
[1 2 3]
pact> (sort ['age] [{'name: "Lin",'age: 30} {'name: "Val",'age: 25}])
[{"name": "Val","age": 25} {"name": "Lin","age": 30}]
str-to-int¶
str-val string → integer
base integer str-val string → integer
Compute the integer value of STR-VAL in base 10, or in BASE if specified. STR-VAL can be up to 512 chars in length. BASE must be between 2 and 16, or 64 to perform unpadded base64url conversion. Each digit must be in the correct range for the base.
pact> (str-to-int 16 "abcdef123456")
188900967593046
pact> (str-to-int "123456")
123456
pact> (str-to-int 64 "q80")
43981
str-to-list¶
str string → [string]
Takes STR and returns a list of single character strings
pact> (str-to-list "hello")
["h" "e" "l" "l" "o"]
pact> (concat (map (+ " ") (str-to-list "abcde")))
" a b c d e"
take¶
count integer list <a[[<l>],string]>
→ <a[[<l>],string]>
keys [string] object object:<{o}> → object:<{o}>
Take COUNT values from LIST (or string), or entries having keys in KEYS from OBJECT. If COUNT is negative, take from end. If COUNT exceeds the interval (-263,263), it is truncated to that range.
pact> (take 2 "abcd")
"ab"
pact> (take (- 3) [1 2 3 4 5])
[3 4 5]
pact> (take ['name] { 'name: "Vlad", 'active: false})
{"name": "Vlad"}
try¶
default <a> action <a> → <a>
Attempt a pure ACTION, returning DEFAULT in the case of failure. Pure expressions are expressions which do not do i/o or work with non-deterministic state in contrast to impure expressions such as reading and writing to a table.
pact> (try 3 (enforce (= 1 2) "this will definitely fail"))
3
(expect "impure expression fails and returns default" "default" (try "default" (with-read accounts id {'ccy := ccy}) ccy))
tx-hash¶
→ string
Obtain hash of current transaction as a string.
pact> (tx-hash)
"DldRwCblQ7Loqy6wYJnaodHl30d3j3eH-qtFzfEv46g"
where¶
field string app x:<a> -> bool value object:<{row}>
→ bool
Utility for use in ‘filter’ and ‘select’ applying APP to FIELD in VALUE.
pact> (filter (where 'age (> 20)) [{'name: "Mary",'age: 30} {'name: "Juan",'age: 15}])
[{"name": "Juan","age": 15}]
yield¶
object object:<{y}> → object:<{y}>
object object:<{y}> target-chain string → object:<{y}>
Yield OBJECT for use with ‘resume’ in following pact step. With optional argument TARGET-CHAIN, target subsequent step to execute on targeted chain using automated SPV endorsement-based dispatch.
(yield { "amount": 100.0 })
(yield { "amount": 100.0 } "some-chain-id")
zip¶
f x:<a> y:<b> -> <c> list1 [<a>] list2 [<b>]
→ [<c>]
Combine two lists with some function f, into a new list, the length of which is the length of the shortest list.
pact> (zip (+) [1 2 3 4] [4 5 6 7])
[5 7 9 11]
pact> (zip (-) [1 2 3 4] [4 5 6])
[-3 -3 -3]
pact> (zip (+) [1 2 3] [4 5 6 7])
[5 7 9]
pact> (zip (lambda (x y) { 'x: x, 'y: y }) [1 2 3 4] [4 5 6 7])
[{"x": 1,"y": 4} {"x": 2,"y": 5} {"x": 3,"y": 6} {"x": 4,"y": 7}]
Database¶
create-table¶
table table:<{row}> → string
Create table TABLE.
(create-table accounts)
Top level only: this function will fail if used in module code.
describe-keyset¶
keyset string → object:*
Get metadata for KEYSET.
Top level only: this function will fail if used in module code.
describe-module¶
module string → object:*
Get metadata for MODULE. Returns an object with ‘name’, ‘hash’, ‘blessed’, ‘code’, and ‘keyset’ fields.
(describe-module 'my-module)
Top level only: this function will fail if used in module code.
describe-table¶
table table:<{row}> → object:*
Get metadata for TABLE. Returns an object with ‘name’, ‘hash’, ‘blessed’, ‘code’, and ‘keyset’ fields.
(describe-table accounts)
Top level only: this function will fail if used in module code.
fold-db¶
table table:<{row}> qry a:string b:object:<{row}> -> bool
consumer a:string b:object:<{row}> -> <b> → [<b>]
Select rows from TABLE using QRY as a predicate with both key and value, and then accumulate results of the query in CONSUMER. Output is sorted by the ordering of keys.
(let*
((qry (lambda (k obj) true)) ;; select all rows
(f (lambda (k obj) [(at 'firstName obj), (at 'b obj)]))
)
(fold-db people (qry) (f))
)
insert¶
table table:<{row}> key string object object:<{row}>
→ string
Write entry in TABLE for KEY of OBJECT column data, failing if data already exists for KEY.
(insert accounts id { "balance": 0.0, "note": "Created account." })
keylog¶
table table:<{row}> key string txid integer
→ [object:*]
Return updates to TABLE for a KEY in transactions at or after TXID, in a list of objects indexed by txid.
(keylog accounts "Alice" 123485945)
read¶
table table:<{row}> key string → object:<{row}>
table table:<{row}> key string columns [string]
→ object:<{row}>
Read row from TABLE for KEY, returning database record object, or just COLUMNS if specified.
(read accounts id ['balance 'ccy])
select¶
table table:<{row}> where row:object:<{row}> -> bool
→ [object:<{row}>]
table table:<{row}> columns [string]
where row:object:<{row}> -> bool → [object:<{row}>]
Select full rows or COLUMNS from table by applying WHERE to each row to get a boolean determining inclusion.
(select people ['firstName,'lastName] (where 'name (= "Fatima")))
(select people (where 'age (> 30)))?
txids¶
table table:<{row}> txid integer → [integer]
Return all txid values greater than or equal to TXID in TABLE.
(txids accounts 123849535)
txlog¶
table table:<{row}> txid integer → [object:*]
Return all updates to TABLE performed in transaction TXID.
(txlog accounts 123485945)
update¶
table table:<{row}> key string object object:~<{row}>
→ string
Write entry in TABLE for KEY of OBJECT column data, failing if data does not exist for KEY.
(update accounts id { "balance": (+ bal amount), "change": amount, "note": "credit" })
with-default-read¶
table table:<{row}> key string
defaults object:~<{row}> bindings binding:~<{row}>
→ <a>
Special form to read row from TABLE for KEY and bind columns per BINDINGS over subsequent body statements. If row not found, read columns from DEFAULTS, an object with matching key names.
(with-default-read accounts id { "balance": 0, "ccy": "USD" } { "balance":= bal, "ccy":= ccy }
(format "Balance for {} is {} {}" [id bal ccy]))
with-read¶
table table:<{row}> key string
bindings binding:<{row}> → <a>
Special form to read row from TABLE for KEY and bind columns per BINDINGS over subsequent body statements.
(with-read accounts id { "balance":= bal, "ccy":= ccy }
(format "Balance for {} is {} {}" [id bal ccy]))
write¶
table table:<{row}> key string object object:<{row}>
→ string
Write entry in TABLE for KEY of OBJECT column data.
(write accounts id { "balance": 100.0 })
Time¶
add-time¶
time time seconds decimal → time
time time seconds integer → time
Add SECONDS to TIME; SECONDS can be integer or decimal.
pact> (add-time (time "2016-07-22T12:00:00Z") 15)
"2016-07-22T12:00:15Z"
days¶
n decimal → decimal
n integer → decimal
N days, for use with ‘add-time’
pact> (add-time (time "2016-07-22T12:00:00Z") (days 1))
"2016-07-23T12:00:00Z"
diff-time¶
time1 time time2 time → decimal
Compute difference between TIME1 and TIME2 in seconds.
pact> (diff-time (parse-time "%T" "16:00:00") (parse-time "%T" "09:30:00"))
23400.0
format-time¶
format string time time → string
Format TIME using FORMAT. See “Time Formats” docs for supported formats.
pact> (format-time "%F" (time "2016-07-22T12:00:00Z"))
"2016-07-22"
hours¶
n decimal → decimal
n integer → decimal
N hours, for use with ‘add-time’
pact> (add-time (time "2016-07-22T12:00:00Z") (hours 1))
"2016-07-22T13:00:00Z"
minutes¶
n decimal → decimal
n integer → decimal
N minutes, for use with ‘add-time’.
pact> (add-time (time "2016-07-22T12:00:00Z") (minutes 1))
"2016-07-22T12:01:00Z"
parse-time¶
format string utcval string → time
Construct time from UTCVAL using FORMAT. See “Time Formats” docs for supported formats.
pact> (parse-time "%F" "2016-09-12")
"2016-09-12T00:00:00Z"
time¶
utcval string → time
Construct time from UTCVAL using ISO8601 format (%Y-%m-%dT%H:%M:%SZ).
pact> (time "2016-07-22T11:26:35Z")
"2016-07-22T11:26:35Z"
Operators¶
!=¶
x <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset,guard,module{}]>
y <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset,guard,module{}]>
→ bool
True if X does not equal Y.
pact> (!= "hello" "goodbye")
true
*¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
Multiply X by Y.
pact> (* 0.5 10.0)
5.0
pact> (* 3 5)
15
+¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
x <a[string,[<l>],object:<{o}>]>
y <a[string,[<l>],object:<{o}>]>
→ <a[string,[<l>],object:<{o}>]>
Add numbers, concatenate strings/lists, or merge objects.
pact> (+ 1 2)
3
pact> (+ 5.0 0.5)
5.5
pact> (+ "every" "body")
"everybody"
pact> (+ [1 2] [3 4])
[1 2 3 4]
pact> (+ { "foo": 100 } { "foo": 1, "bar": 2 })
{"bar": 2,"foo": 100}
-¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
x <a[integer,decimal]> → <a[integer,decimal]>
Negate X, or subtract Y from X.
pact> (- 1.0)
-1.0
pact> (- 3 2)
1
/¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
Divide X by Y.
pact> (/ 10.0 2.0)
5.0
pact> (/ 8 3)
2
<¶
x <a[integer,decimal,string,time]>
y <a[integer,decimal,string,time]> → bool
True if X < Y.
pact> (< 1 3)
true
pact> (< 5.24 2.52)
false
pact> (< "abc" "def")
true
<=¶
x <a[integer,decimal,string,time]>
y <a[integer,decimal,string,time]> → bool
True if X <= Y.
pact> (<= 1 3)
true
pact> (<= 5.24 2.52)
false
pact> (<= "abc" "def")
true
=¶
x <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset,guard,module{}]>
y <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset,guard,module{}]>
→ bool
Compare alike terms for equality, returning TRUE if X is equal to Y. Equality comparisons will fail immediately on type mismatch, or if types are not value types.
pact> (= [1 2 3] [1 2 3])
true
pact> (= 'foo "foo")
true
pact> (= { 'a: 2 } { 'a: 2})
true
>¶
x <a[integer,decimal,string,time]>
y <a[integer,decimal,string,time]> → bool
True if X > Y.
pact> (> 1 3)
false
pact> (> 5.24 2.52)
true
pact> (> "abc" "def")
false
>=¶
x <a[integer,decimal,string,time]>
y <a[integer,decimal,string,time]> → bool
True if X >= Y.
pact> (>= 1 3)
false
pact> (>= 5.24 2.52)
true
pact> (>= "abc" "def")
false
^¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
Raise X to Y power.
pact> (^ 2 3)
8
and? {#and?}¶
a x:<r> -> bool b x:<r> -> bool value <r> → bool
Apply logical ‘and’ to the results of applying VALUE to A and B, with short-circuit.
pact> (and? (> 20) (> 10) 15)
false
ceiling¶
x decimal prec integer → decimal
x decimal → integer
Rounds up value of decimal X as integer, or to PREC precision as decimal.
pact> (ceiling 3.5)
4
pact> (ceiling 100.15234 2)
100.16
dec¶
x integer → decimal
Cast an integer to a decimal value of integer X as decimal.
pact> (dec 3)
3.0
floor¶
x decimal prec integer → decimal
x decimal → integer
Rounds down value of decimal X as integer, or to PREC precision as decimal.
pact> (floor 3.5)
3
pact> (floor 100.15234 2)
100.15
ln¶
x <a[integer,decimal]> → <a[integer,decimal]>
Natural log of X.
pact> (round (ln 60) 6)
4.094345
log¶
x <a[integer,decimal]> y <a[integer,decimal]>
→ <a[integer,decimal]>
x <a[integer,decimal]> y <b[integer,decimal]>
→ decimal
Log of Y base X.
pact> (log 2 256)
8
not? {#not?}¶
app x:<r> -> bool value <r> → bool
Apply logical ‘not’ to the results of applying VALUE to APP.
pact> (not? (> 20) 15)
false
or? {#or?}¶
a x:<r> -> bool b x:<r> -> bool value <r> → bool
Apply logical ‘or’ to the results of applying VALUE to A and B, with short-circuit.
pact> (or? (> 20) (> 10) 15)
true
round¶
x decimal prec integer → decimal
x decimal → integer
Performs Banker’s rounding value of decimal X as integer, or to PREC precision as decimal.
pact> (round 3.5)
4
pact> (round 100.15234 2)
100.15
shift¶
x integer y integer → integer
Shift X Y bits left if Y is positive, or right by -Y bits otherwise. Right shifts perform sign extension on signed number types; i.e. they fill the top bits with 1 if the x is negative and with 0 otherwise.
pact> (shift 255 8)
65280
pact> (shift 255 -1)
127
pact> (shift -255 8)
-65280
pact> (shift -255 -1)
-128
xor¶
x integer y integer → integer
Compute bitwise X xor Y.
pact> (xor 127 64)
63
pact> (xor 5 -7)
-4
Keysets¶
define-keyset¶
name string keyset string → string
name string → string
Define keyset as NAME with KEYSET, or if unspecified, read NAME from message payload as keyset, similarly to ‘read-keyset’. If keyset NAME already exists, keyset will be enforced before updating to new value.
(define-keyset 'admin-keyset (read-keyset "keyset"))
Top level only: this function will fail if used in module code.
enforce-keyset¶
guard guard → bool
keysetname string → bool
Execute GUARD, or defined keyset KEYSETNAME, to enforce desired predicate logic.
(enforce-keyset 'admin-keyset)
(enforce-keyset row-guard)
keys-2¶
count integer matched integer → bool
Keyset predicate function to match at least 2 keys in keyset.
pact> (keys-2 3 1)
false
keys-all¶
count integer matched integer → bool
Keyset predicate function to match all keys in keyset.
pact> (keys-all 3 3)
true
keys-any¶
count integer matched integer → bool
Keyset predicate function to match any (at least 1) key in keyset.
pact> (keys-any 10 1)
true
read-keyset¶
key string → keyset
Read KEY from message data body as keyset ({ “keys”: KEYLIST, “pred”: PREDFUN }). PREDFUN should resolve to a keys predicate.
(read-keyset "admin-keyset")
Capabilities¶
compose-capability¶
capability -> bool → bool
Specifies and requests grant of CAPABILITY which is an application of a ‘defcap’ production, only valid within a (distinct) ‘defcap’ body, as a way to compose CAPABILITY with the outer capability such that the scope of the containing ‘with-capability’ call will “import” this capability. Thus, a call to ‘(with-capability (OUTER-CAP) OUTER-BODY)’, where the OUTER-CAP defcap calls ‘(compose-capability (INNER-CAP))’, will result in INNER-CAP being granted in the scope of OUTER-BODY.
(compose-capability (TRANSFER src dest))
emit-event¶
capability -> bool → bool
Emit CAPABILITY as event without evaluating body of capability. Fails if CAPABILITY is not @managed or @event.
(emit-event (TRANSFER "Bob" "Alice" 12.0))
enforce-guard¶
guard guard → bool
keysetname string → bool
Execute GUARD, or defined keyset KEYSETNAME, to enforce desired predicate logic.
(enforce-guard 'admin-keyset)
(enforce-guard row-guard)
install-capability¶
capability -> bool → string
Specifies, and provisions install of, a managed CAPABILITY, defined in a ‘defcap’ in which a ‘@managed’ tag designates a single parameter to be managed by a specified function. After install, CAPABILITY must still be brought into scope using ‘with-capability’, at which time the ‘manager function’ is invoked to validate the request. The manager function is of type ’managed:
requested:
->
‘, where’
’ indicates the type of the managed parameter, such that for ‘(defcap FOO (bar:string baz:integer) @managed baz FOO-mgr …)’, the manager function would be ‘(defun FOO-mgr:integer (managed:integer requested:integer) …)’. Any capability matching the ‘static’ (non-managed) parameters will cause this function to be invoked with the current managed value and that of the requested capability. The function should perform whatever logic, presumably linear, to validate the request, and return the new managed value representing the ‘balance’ of the request. NOTE that signatures scoped to a managed capability cause the capability to be automatically provisioned for install similarly to one installed with this function.
(install-capability (PAY "alice" "bob" 10.0))
require-capability¶
capability -> bool → bool
Specifies and tests for existing grant of CAPABILITY, failing if not found in environment.
(require-capability (TRANSFER src dest))
with-capability¶
capability -> bool body [*] → <a>
Specifies and requests grant of acquired CAPABILITY which is an application of a ‘defcap’ production. Given the unique token specified by this application, ensure that the token is granted in the environment during execution of BODY. ‘with-capability’ can only be called in the same module that declares the corresponding ‘defcap’, otherwise module-admin rights are required. If token is not present, the CAPABILITY is evaluated, with successful completion resulting in the installation/granting of the token, which will then be revoked upon completion of BODY. Nested ‘with-capability’ calls for the same token will detect the presence of the token, and will not re-apply CAPABILITY, but simply execute BODY. ‘with-capability’ cannot be called from within an evaluating defcap. Acquire of a managed capability results in emission of the equivalent event.
(with-capability (UPDATE-USERS id) (update users id { salary: new-salary }))
SPV¶
verify-spv¶
type string payload object:<in> → object:<out>
Performs a platform-specific spv proof of type TYPE on PAYLOAD. The format of the PAYLOAD object depends on TYPE, as does the format of the return object. Platforms such as Chainweb will document the specific payload types and return values.
(verify-spv "TXOUT" (read-msg "proof"))
Commitments¶
decrypt-cc20p1305¶
ciphertext string nonce string aad string
mac string public-key string secret-key string
→ string
Perform decryption of CIPHERTEXT using the CHACHA20-POLY1305 Authenticated Encryption with Associated Data (AEAD) construction described in IETF RFC 7539. CIPHERTEXT is an unpadded base64url string. NONCE is a 12-byte base64 string. AAD is base64 additional authentication data of any length. MAC is the “detached” base64 tag value for validating POLY1305 authentication. PUBLIC-KEY and SECRET-KEY are base-16 Curve25519 values to form the DH symmetric key.Result is unpadded base64URL.
(decrypt-cc20p1305 ciphertext nonce aad mac pubkey privkey)
validate-keypair¶
public string secret string → bool
Enforce that the Curve25519 keypair of (PUBLIC,SECRET) match. Key values are base-16 strings of length 32.
(validate-keypair pubkey privkey)
Guards¶
create-capability-guard¶
capability -> bool → guard
Creates a guard that will enforce that CAPABILITY is acquired.
(create-capability-guard (BANK_DEBIT 10.0))
create-capability-pact-guard¶
capability -> bool → guard
Creates a guard that will enforce that CAPABILITY is acquired and that the currently-executing defpact is operational.
(create-capability-pact-guard (ESCROW owner))
create-module-guard¶
name string → guard
Defines a guard by NAME that enforces the current module admin predicate.
create-pact-guard¶
name string → guard
Defines a guard predicate by NAME that captures the results of ‘pact-id’. At enforcement time, the success condition is that at that time ‘pact-id’ must return the same value. In effect this ensures that the guard will only succeed within the multi-transaction identified by the pact id.
create-principal¶
guard guard → string
Create a principal which unambiguously identifies GUARD.
(create-principal (read-keyset 'keyset))
(create-principal (keyset-ref-guard 'keyset))
(create-principal (create-module-guard 'module-guard))
(create-principal (create-user-guard 'user-guard))
(create-principal (create-pact-guard 'pact-guard))
create-user-guard¶
closure -> bool → guard
Defines a custom guard CLOSURE whose arguments are strictly evaluated at definition time, to be supplied to indicated function at enforcement time.
is-principal¶
principal string → bool
Tell whether PRINCIPAL string conforms to the principal format without proving validity.
(enforce (is-principal 'k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69) "Invalid account structure: non-principal account")
keyset-ref-guard¶
keyset-ref string → guard
Creates a guard for the keyset registered as KEYSET-REF with ‘define-keyset’. Concrete keysets are themselves guard types; this function is specifically to store references alongside other guards in the database, etc.
typeof-principal¶
principal string → string
Return the protocol type of a given PRINCIPAL value. If input value is not a principal type, then the empty string is returned.
(typeof-principal 'k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69)
validate-principal¶
guard guard principal string → bool
Validate that PRINCIPAL unambiguously identifies GUARD.
(enforce (validate-principal (read-keyset 'keyset) account) "Invalid account ID")
Zk¶
pairing-check¶
points-g1 [<a>] points-g2 [<b>] → bool
Perform pairing and final exponentiation points in G1 and G2 in BN254, check if the result is 1
point-add¶
type string point1 <a> point2 <a> → <a>
Add two points together that lie on the curve BN254. Point addition either in Fq or in Fq2
pact> (point-add 'g1 {'x: 1, 'y: 2} {'x: 1, 'y: 2})
{"x": 1368015179489954701390400359078579693043519447331113978918064868415326638035,"y": 9918110051302171585080402603319702774565515993150576347155970296011118125764}
scalar-mult¶
type string point1 <a> scalar integer → <a>
Multiply a point that lies on the curve BN254 by an integer value
pact> (scalar-mult 'g1 {'x: 1, 'y: 2} 2)
{"x": 1368015179489954701390400359078579693043519447331113978918064868415326638035,"y": 9918110051302171585080402603319702774565515993150576347155970296011118125764}
REPL-only functions¶
The following functions are loaded automatically into the interactive
REPL, or within script files with a .repl extension. They are not
available for blockchain-based execution.
begin-tx¶
→ string
name string → string
Begin transaction with optional NAME.
pact> (begin-tx "load module")
"Begin Tx 0: load module"
continue-pact¶
step integer → string
step integer rollback bool → string
step integer rollback bool pact-id string
→ string
step integer rollback bool pact-id string
yielded object:<{y}> → string
Continue previously-initiated pact identified STEP, optionally specifying ROLLBACK (default is false), PACT-ID of the pact to be continued (defaults to the pact initiated in the current transaction, if one is present), and YIELDED value to be read with ‘resume’ (if not specified, uses yield in most recent pact exec, if any).
(continue-pact 1)
(continue-pact 1 true)
(continue-pact 1 false "[pact-id-hash]"))
(continue-pact 2 1 false "[pact-id-hash]" { "rate": 0.9 })
env-chain-data¶
new-data object:~{public-chain-data} → string
Update existing entries of ‘chain-data’ with NEW-DATA, replacing those items only.
pact> (env-chain-data { "chain-id": "TestNet00/2", "block-height": 20 })
"Updated public metadata"
env-data¶
json <a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset]>
→ string
Set transaction JSON data, either as encoded string, or as pact types coerced to JSON.
pact> (env-data { "keyset": { "keys": ["my-key" "admin-key"], "pred": "keys-any" } })
"Setting transaction data"
env-dynref¶
iface module impl module{} → string
→ string
Substitute module IMPL in any dynamic usages of IFACE in typechecking and analysis. With no arguments, remove all substitutions.
(env-dynref fungible-v2 coin)
env-enable-repl-natives¶
enable bool → string
Control whether REPL native functions are allowed in module code. When enabled, fixture functions like ‘env-sigs’ are allowed in module code.
pact> (env-enable-repl-natives true)
"Repl natives enabled"
env-entity¶
→ string
entity string → string
Set environment confidential ENTITY id, or unset with no argument.
(env-entity "my-org")
(env-entity)
env-events¶
clear bool → [object:*]
Retreive any accumulated events and optionally clear event state. Object returned has fields ‘name’ (fully-qualified event name), ‘params’ (event parameters), ‘module-hash’ (hash of emitting module).
(env-events true)
env-exec-config¶
flags [string] → [string]
→ [string]
Queries, or with arguments, sets execution config flags. Valid flags: [“AllowReadInLocal”,“DisableHistoryInTransactionalMode”,“DisableInlineMemCheck”,“DisableModuleInstall”,“DisableNewTrans”,“DisablePact40”,“DisablePact420”,“DisablePact43”,“DisablePact431”,“DisablePact44”,“DisablePact45”,“DisablePact46”,“DisablePact47”,“DisablePact48”,“DisablePactEvents”,“DisableRuntimeReturnTypeChecking”,“EnforceKeyFormats”,“OldReadOnlyBehavior”,“PreserveModuleIfacesBug”,“PreserveModuleNameBug”,“PreserveNsModuleInstallBug”,“PreserveShowDefs”]
pact> (env-exec-config ['DisableHistoryInTransactionalMode]) (env-exec-config)
["DisableHistoryInTransactionalMode"]
env-gas¶
→ integer
gas integer → string
Query gas state, or set it to GAS. Note that certain plaforms may charge additional gas that is not captured by the interpreter gas model, such as an overall transaction-size cost.
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gas 0) (map (+ 1) [1 2 3]) (env-gas)
7
env-gaslog¶
→ string
Enable and obtain gas logging. Bracket around the code whose gas logs you want to inspect.
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gaslog) (map (+ 1) [1 2 3]) (env-gaslog)
["TOTAL: 7" "map:GUnreduced:currTotalGas=4: 4" "+:GUnreduced:currTotalGas=5: 1" ":GIntegerOpCost:(1, ):(1, ):Pact48IntThreshold:currTotalGas=5: 0" "+:GUnreduced:currTotalGas=6: 1" ":GIntegerOpCost:(1, ):(2, ):Pact48IntThreshold:currTotalGas=6: 0" "+:GUnreduced:currTotalGas=7: 1" ":GIntegerOpCost:(1, ):(3, ):Pact48IntThreshold:currTotalGas=7: 0"]
env-gasmodel¶
model string → string
→ string
model string rate integer → string
Update or query current gas model. With just MODEL, “table” is supported; with MODEL and RATE, ‘fixed’ is supported. With no args, output current model.
pact> (env-gasmodel)
"Current gas model is 'fixed 0': constant rate gas model with fixed rate 0"
pact> (env-gasmodel 'table)
"Set gas model to table-based cost model"
pact> (env-gasmodel 'fixed 1)
"Set gas model to constant rate gas model with fixed rate 1"
env-hash¶
hash string → string
Set current transaction hash. HASH must be an unpadded base64-url encoded BLAKE2b 256-bit hash.
pact> (env-hash (hash "hello"))
"Set tx hash to Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"
env-keys¶
keys [string] → string
DEPRECATED in favor of ‘env-sigs’. Set transaction signer KEYS. See ‘env-sigs’ for setting keys with associated capabilities.
pact> (env-keys ["my-key" "admin-key"])
"Setting transaction keys"
env-namespace-policy¶
allow-root bool
ns-policy-fun ns:string ns-admin:guard -> bool → string
Install a managed namespace policy specifying ALLOW-ROOT and NS-POLICY-FUN.
(env-namespace-policy (my-ns-policy-fun))
env-sigs¶
sigs [object:*] → string
Set transaction signature keys and capabilities. SIGS is a list of objects with “key” specifying the signer key, and “caps” specifying a list of associated capabilities.
(env-sigs [{'key: "my-key", 'caps: [(accounts.USER_GUARD "my-account")]}, {'key: "admin-key", 'caps: []}
env-simulate-onchain¶
on-chain bool → string
Set a flag to simulate on-chain behavior that differs from the repl, in particular for observing things like errors and stack traces.
(env-simulate-onchain true)
expect¶
doc string expected <a> actual <a> → string
Evaluate ACTUAL and verify that it equals EXPECTED.
pact> (expect "Sanity prevails." 4 (+ 2 2))
"Expect: success: Sanity prevails."
expect-failure¶
doc string exp <a> → string
doc string err string exp <a> → string
Evaluate EXP and succeed only if it throws an error.
pact> (expect-failure "Enforce fails on false" (enforce false "Expected error"))
"Expect failure: success: Enforce fails on false"
pact> (expect-failure "Enforce fails with message" "Expected error" (enforce false "Expected error"))
"Expect failure: success: Enforce fails with message"
expect-that¶
doc string pred value:<a> -> bool exp <a>
→ string
Evaluate EXP and succeed if value passes predicate PRED.
pact> (expect-that "addition" (< 2) (+ 1 2))
"Expect-that: success: addition"
pact> (expect-that "addition" (> 2) (+ 1 2))
"FAILURE: addition: did not satisfy (> 2) : 3:integer"
format-address¶
scheme string public-key string → string
Transform PUBLIC-KEY into an address (i.e. a Pact Runtime Public Key) depending on its SCHEME.
load¶
file string → string
file string reset bool → string
Load and evaluate FILE, resetting repl state beforehand if optional RESET is true.
(load "accounts.repl")
mock-spv¶
type string payload object:* output object:*
→ string
Mock a successful call to ‘spv-verify’ with TYPE and PAYLOAD to return OUTPUT.
(mock-spv "TXOUT" { 'proof: "a54f54de54c54d89e7f" } { 'amount: 10.0, 'account: "Dave", 'chainId: "1" })
pact-state¶
→ object:*
clear bool → object:*
Inspect state from most recent pact execution. Returns object with fields ‘pactId’: pact ID; ‘yield’: yield result or ‘false’ if none; ‘step’: executed step; ‘executed’: indicates if step was skipped because entity did not match. With CLEAR argument, erases pact from repl state.
(pact-state)
(pact-state true)
rollback-tx¶
→ string
Rollback transaction.
pact> (begin-tx "Third Act") (rollback-tx)
"Rollback Tx 0: Third Act"
sig-keyset¶
→ keyset
Convenience function to build a keyset from keys present in message signatures, using ‘keys-all’ as the predicate.
test-capability¶
capability -> bool → string
Acquire (if unmanaged) or install (if managed) CAPABILITY. CAPABILITY and any composed capabilities are in scope for the rest of the transaction.
(test-capability (MY-CAP))
typecheck¶
module string → string
module string debug bool → string
Typecheck MODULE, optionally enabling DEBUG output.
verify¶
module string debug bool → string
Verify MODULE, checking that all properties hold. Optionally, if DEBUG is set to true, write debug output to “pact-verify-MODULE” directory.
(verify "module")
(verify "module" true)
with-applied-env¶
exec <a> → <a>
Evaluate EXEC with any pending environment changes applied. Normally, environment changes must execute at top-level for the change to take effect. This allows scoped application of non-toplevel environment changes.
pact> (let ((a 1)) (env-data { 'b: 1 }) (with-applied-env (+ a (read-integer 'b))))
2
