General purpose functions

Pact provides the following general purpose built-in functions.

Use the CHARSET_ASCII constant to indicate the standard ASCII character set.

Constant:   CHARSET_ASCII:integer = 0

Use the CHARSET_LATIN1 constant to indicate the standard Latin-1 (ISO-8859-1) character set.

Constant:   CHARSET_LATIN1:integer = 1

Use at to retrieve the value at the location specified by an index number or by a key string in a collection. If you specify an index number, the collection must be a list of values. If you specify a key string, the collection must be an object.

To get a value using the specified index location from a list of values, use the following syntax:

To get a value using the specified string from an object, use the following syntax:

Use one of the following argument to define the value you want to retrieve using the at Pact function.

The at function returns the value found at the specified index or using the specified key. The return value can be any data type.

The following example returns the value found at the index location—starting with 0—from a list of values:

You can use the at function to return any type of data from a list. For example:

The following example returns the value found at the specified key from an object:

You can use the at function to return any type of data using the specified key from an object. For example:

For property checking, you can use the at list operator when specifying an invariant or a property to test your code against.

string string → string

Decode STRING from unpadded base64.

string string → string

Encode STRING as unpadded base64.

src object:<{row}> binding binding:<{row}> → <a>

Special form evaluates SRC to an object which is bound to with BINDINGS over subsequent body statements.

→ 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.

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.

str-list [string] → string

Takes STR-LIST and concats each of the strings in the list, returning the resulting string

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.

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.

value * → *

Continue a previously started nested defpact.

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.

Top level only: this function will fail if used in module code.

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.

Top level only: this function will fail if used in module code.

values [<a>] → [<a>]

Returns from a homogeneous list of VALUES a list with duplicates removed. The original order of the values is preserved.

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 (-2^63,2^63), it is truncated to that range.

test bool msg string → bool

Fail transaction with MSG if pure expression TEST is false. Otherwise, returns true.

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.

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'.

Top level only: this function will fail if used in module code.

Use enumerate to return a sequence of numbers from the specified first number to the specified last number, inclusively, as a list.

By default, the sequence increments by one from the first number to the last number. Optionally, you can specify an increment other than one to use between numbers in the sequence.

If you specify a first number that’s greater than the last number, the sequence decrements by one from the first number to the last number.

To increment or decrement the sequence by one, use the following syntax:

To specify a value to increment or decrement the sequence by, use the following syntax:

Use the following arguments to define the beginning and end of the sequence you want to list using the enumerate Pact function.

Use the following optional argument to define the increment to use between the beginning and end of the sequence in the enumerate Pact function.

The enumerate function returns the resulting sequence of numbers as a list.

The following example enumerates a sequence of numbers using the default increment of one in the Pact REPL:

The following example enumerates a sequence of numbers using an increment of two between numbers in the sequence:

The following example illustrates decrementing a sequence of numbers using an inc value of -2 between numbers in the sequence:

Use filter to filter a list of element by applying the specified criteria to each element in the list. FEach element that matches the specified criteria—returning a result of true—is included in the resulting list with its original value.

To filter a list of elements, use the following syntax:

Use the following argument to define the criteria you want to use to filter the list of elements.

The filter function returns the list of elements matching the specified criteria.

The following example composes a list of elements by evaluating the length of strings with less than two characters:

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.

template string vars [*] → string

Interpolate VARS into TEMPLATE using {}.

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.

value <a> → <a>

Return provided value.

cond bool then <a> else <a> → <a>

Test COND. If true, evaluate THEN. Otherwise, evaluate ELSE.

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.

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.

x <a[[<l>],string,object:<{o}>]> → integer

Compute length of X, which can be a list, a string, or an object.

elems * → [*]

Create list from ELEMS. Deprecated in Pact 2.1.1 with literal list support.

→ [string]

List modules available for loading.

Top level only: this function will fail if used in module code.

length integer value <a> → [<a>]

Create list by repeating VALUE LENGTH times.

app x:<b> -> <a> list [<b>] → [<a>]

Apply APP to each element in LIST, returning a new list of results.

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.

Top level only: this function will fail if used in module code.

→ string

Return ID if called during current pact execution, failing if not.

→ string

Obtain current pact build version.

Top level only: this function will fail if used in module code.

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

key string → decimal

Parse KEY string or number value from top level of message data body as decimal.

key string → integer

Parse KEY string or number value from top level of message data body as integer.

→ <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.

key string → string

Parse KEY string or number value from top level of message data body as string.

key string object object:<{o}> → object:<{o}>

Remove entry for KEY from OBJECT.

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.

list [<a>] → [<a>]

Reverse LIST.

values [<a>] → [<a>]

fields [string] values [object:<{o}>] → [object:<{o}>]

Sort a homogeneous list of primitive VALUES, or objects using supplied FIELDS list.

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.

str string → [string]

Takes STR and returns a list of single character strings

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 (-2^63,2^63), it is truncated to that range.

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.

→ string

Obtain hash of current transaction as a string.

x <a> → string

Returns type of X as string.

field string app x:<a> -> bool value object:<{row}> → bool

Utility for use in 'filter' and 'select' applying APP to FIELD in VALUE.

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.

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.