Skip to main content
Last updated

REPL-only functions

begin-tx

Use begin-tx to begin a new transaction with an optional name.

Basic syntax

To begin a transaction without a name, use the following syntax:

lisp
(begin-tx)
lisp
(begin-tx)

To begin a transaction with a specific name, use the following syntax:

lisp
(begin-tx name)
lisp
(begin-tx name)

Arguments

Use the following argument to specify an optional name for the transaction when using the begin-tx Pact function.

ArgumentTypeDescription
namestring(Optional) Specifies the name of the transaction.

Return value

The begin-tx function returns a string indicating the transaction identifier and the optional name (if provided).

Examples

The following examples demonstrate the usage of the begin-tx function within a Pact REPL:

  1. Beginning a transaction without a name:
pact
pact> (begin-tx)"Begin Tx 0"
pact
pact> (begin-tx)"Begin Tx 0"
  1. Beginning a transaction with a name:
pact
pact> (begin-tx "load module")"Begin Tx 0: load module"
pact
pact> (begin-tx "load module")"Begin Tx 0: load module"

By using begin-tx, you can initiate a new transaction in Pact and optionally assign a name to it for better organization and tracking purposes.

commit-tx

Use commit-tx to commit the current transaction.

Basic syntax

(commit-tx)

Arguments

The commit-tx function does not take any arguments.

Return value

The commit-tx function returns a string indicating the transaction identifier that has been committed.

Example

The following example demonstrates the usage of the commit-tx function within a Pact REPL:

pact
pact> (begin-tx) (commit-tx)"Commit Tx 0"
pact
pact> (begin-tx) (commit-tx)"Commit Tx 0"

In this example, a new transaction is started using (begin-tx), and then (commit-tx) is called to commit the transaction. The function returns a string indicating that "Tx 0" has been committed.

Note that commit-tx should be used after performing the necessary operations within a transaction. Once commit-tx is called, the transaction is finalized, and any changes made during the transaction are persisted.

It's important to ensure that commit-tx is called after begin-tx and any other transaction-related operations to properly commit the transaction. If commit-tx is not called, the transaction will remain open and may lead to unexpected behavior or inconsistencies in the system.

continue-pact

Use continue-pact to continue a previously-initiated pact identified by a specific step, with optional parameters for rollback, pact ID, and yielded value.

Basic syntax

To continue a pact with the specified step, use the following syntax:

lisp
(continue-pact step)
lisp
(continue-pact step)

To continue a pact with the specified step and rollback option, use the following syntax:

lisp
(continue-pact step rollback)
lisp
(continue-pact step rollback)

To continue a pact with the specified step, rollback option, and pact ID, use the following syntax:

lisp
(continue-pact step rollback pact-id)
lisp
(continue-pact step rollback pact-id)

To continue a pact with the specified step, rollback option, pact ID, and yielded value, use the following syntax:

lisp
(continue-pact step rollback pact-id yielded)
lisp
(continue-pact step rollback pact-id yielded)

Arguments

Use the following arguments to customize the behavior of the continue-pact Pact function.

ArgumentTypeDescription
stepintegerSpecifies the step of the pact to continue.
rollbackbool(Optional) Specifies whether to perform a rollback. Default is false.
pact-idstring(Optional) Specifies the ID of the pact to continue. Defaults to the pact initiated in the current transaction, if one is present.
yieldedobject(Optional) Specifies the yielded value to be read with 'resume'. If not specified, uses the yield from the most recent pact execution, if any. The schema of the yielded object is object:<{y}>.

Return value

The continue-pact function returns a string indicating the result of continuing the pact.

Examples

The following examples demonstrate the usage of the continue-pact function:

  1. Continue a pact with step 1:
pact
(continue-pact 1)
pact
(continue-pact 1)
  1. Continue a pact with step 1 and perform a rollback:
pact
(continue-pact 1 true)
pact
(continue-pact 1 true)
  1. Continue a pact with step 1, without rollback, and specify the pact ID:
pact
(continue-pact 1 false "[pact-id-hash]")
pact
(continue-pact 1 false "[pact-id-hash]")
  1. Continue a pact with step 2, without rollback, specify the pact ID, and provide a yielded value:
pact
(continue-pact 2 false "[pact-id-hash]" { "rate": 0.9 })
pact
(continue-pact 2 false "[pact-id-hash]" { "rate": 0.9 })

describe-module

Use describe-module to get metadata for a specified MODULE. This function returns an object with fields including name, hash, blessed, code, and keyset.

Basic syntax

To get metadata for a MODULE, use the following syntax:

(describe-module MODULE)

Arguments

Use the following argument to specify the MODULE for the describe-module Pact function.

ArgumentTypeDescription
modulestringSpecifies the name of the module to describe.

Return values

The describe-module function returns an object with metadata for the specified MODULE.

Examples

The following example demonstrates the describe-module function:

pact
pact>(module m G (defcap G () true))pact>(describe-module 'm){"hash":"0RpFOMAZ2787-fNFO6DokGf_V5WiSLMK10v4xnOymX0", "interfaces":[  ], "name":"m"}
pact
pact>(module m G (defcap G () true))pact>(describe-module 'm){"hash":"0RpFOMAZ2787-fNFO6DokGf_V5WiSLMK10v4xnOymX0", "interfaces":[  ], "name":"m"}

In this example, (describe-module 'm) is used to get metadata for the module named 'm'. The function returns an object providing detailed information about the module.

env-data

Use env-data to set transaction JSON data, either as an encoded string or as Pact types coerced to JSON.

Basic syntax

(env-data json)

Arguments

Use the following argument to specify the JSON data when using the env-data Pact function.

ArgumentTypeDescription
json<a[integer,string,time,decimal,bool,[<l>],object:<{o}>,keyset]>Specifies the JSON data to be set for the transaction. The data can be provided as an encoded string or as Pact types that will be coerced to JSON.

Return value

The env-data function returns a string indicating that the transaction data is being set.

Example

The following example demonstrates the usage of the env-data function within a Pact REPL:

pact
pact> (env-data { "keyset": { "keys": ["my-key" "admin-key"], "pred": "keys-any" } })"Setting transaction data"
pact
pact> (env-data { "keyset": { "keys": ["my-key" "admin-key"], "pred": "keys-any" } })"Setting transaction data"

env-enable-repl-natives

Use env-enable-repl-natives to control whether REPL native functions are allowed in module code.

Basic syntax

(env-enable-repl-natives enable)

Arguments

Use the following argument to specify whether to enable or disable REPL native functions in module code.

ArgumentTypeDescription
enableboolSpecifies whether to enable or disable REPL native functions in module code. Set to true to enable, or false to disable.

Return value

The env-enable-repl-natives function returns a string indicating the status of REPL natives.

  • If enable is set to true, it returns "Repl natives enabled".
  • If enable is set to false, it returns "Repl natives disabled".

Behavior

When REPL native functions are enabled (enable is set to true), fixture functions like env-sigs are allowed in module code. This means that you can use these functions within your module definitions.

On the other hand, when REPL native functions are disabled (enable is set to false), fixture functions are not allowed in module code, and attempting to use them will result in an error.

Example

The following example demonstrates enabling REPL native functions within a Pact REPL:

pact
pact> (env-enable-repl-natives true)"Repl natives enabled"
pact
pact> (env-enable-repl-natives true)"Repl natives enabled"

After enabling REPL natives, you can use fixture functions like env-sigs within your module code.

It's important to note that enabling REPL native functions in module code should be done with caution, as it allows access to functions that are typically intended for use in the REPL environment only. Enable this feature only when necessary and ensure that the usage of REPL native functions in module code is properly controlled and validated.

env-events

Use env-events to retrieve any accumulated events and optionally clear the event state.

Basic syntax

(env-events clear)

Arguments

Use the following argument to specify whether to clear the event state after retrieving the events.

ArgumentTypeDescription
clearboolSpecifies whether to clear the event state after retrieving the events. Set to true to clear the event state, or false to keep the event state.

Return value

The env-events function returns an array of objects representing the accumulated events. Each object in the array has the following fields:

  • name: The fully-qualified name of the event.
  • params: The parameters associated with the event.
  • module-hash: The hash of the module that emitted the event.

env-gas

Use env-gas to query the current gas state or set it to a specific value.

Basic syntax

To query the current gas state, use the following syntax:

(env-gas)

To set the gas state to a specific value, use the following syntax:

(env-gas gas)

Arguments

Use the following argument to set the gas state when using the env-gas Pact function.

ArgumentTypeDescription
gasinteger(Optional) Specifies the value to set the gas state to.

Return value

When called without arguments, env-gas returns an integer representing the current gas state.

When called with the gas argument, env-gas returns a string indicating that the gas state has been set to the specified value.

Example

The following example demonstrates querying and setting the gas state within a Pact REPL:

pact
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gas 0) (map (+ 1) [1 2 3]) (env-gas)7
pact
pact> (env-gasmodel "table") (env-gaslimit 10) (env-gas 0) (map (+ 1) [1 2 3]) (env-gas)7

env-gaslimit

Use env-gaslimit to set the environment gas limit to a specific value.

Basic syntax

(env-gaslimit limit)

Arguments

Use the following argument to set the gas limit when using the env-gaslimit Pact function.

ArgumentTypeDescription
limitintegerSpecifies the gas limit to set for the environment.

Return value

The env-gaslimit function returns a string indicating that the gas limit has been set to the specified value.

Examples

pact
pact>(env-gaslimit 10)"Set gas limit to 10"
pact
pact>(env-gaslimit 10)"Set gas limit to 10"

env-gasmodel

Use env-gasmodel to update or query the current gas model.

Basic syntax

To update the gas model to a table-based cost model, use the following syntax:

pact
(env-gasmodel model)
pact
(env-gasmodel model)

To update the gas model to a fixed-rate model with a specific rate, use the following syntax:

pact
(env-gasmodel model rate)
pact
(env-gasmodel model rate)

To query the current gas model, use the following syntax:

pact
(env-gasmodel)
pact
(env-gasmodel)

Arguments

Use the following arguments when using the env-gasmodel Pact function.

ArgumentTypeDescription
modelstringSpecifies the gas model to set. Supported values are "table" and "fixed".

Return value

When called with the model argument, env-gasmodel returns a string indicating the updated gas model.

When called without arguments, env-gasmodel returns a string describing the current gas model.

Examples

The following examples demonstrate updating and querying the gas model within a Pact REPL:

  1. Querying the current gas model:
bash
pact> (env-gasmodel)"Current gas model is 'unitGasModel': GasModel with constant cost MilliGas 0"
bash
pact> (env-gasmodel)"Current gas model is 'unitGasModel': GasModel with constant cost MilliGas 0"
  1. Updating the gas model to a table-based cost model:
bash
pact> (env-gasmodel 'table)"Set gas model to table-based cost model"
bash
pact> (env-gasmodel 'table)"Set gas model to table-based cost model"

env-hash

Use env-hash to set the current transaction hash.

Basic syntax

pact
(env-hash hash)
pact
(env-hash hash)

Arguments

Use the following argument when using the env-hash Pact function.

ArgumentTypeDescription
hashstringSpecifies the hash value to set as the current transaction hash. The hash must be an unpadded base64-url encoded BLAKE2b 256-bit hash.

Return value

The env-hash function returns a string indicating that the transaction hash has been set to the specified value.

Example

The following example demonstrates setting the transaction hash within a Pact REPL:

pact
pact> (env-hash (hash "hello"))"Set tx hash to Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"
pact
pact> (env-hash (hash "hello"))"Set tx hash to Mk3PAn3UowqTLEQfNlol6GsXPe-kuOWJSCU0cbgbcs8"

env-keys (DEPRECATED)

Note: The env-keys function is deprecated in favor of env-sigs. It is recommended to use env-sigs for setting transaction signer keys with associated capabilities.

Use env-keys to set the transaction signer keys.

Basic syntax

pact
(env-keys keys)
pact
(env-keys keys)

Arguments

Use the following argument when using the env-keys Pact function.

ArgumentTypeDescription
keys[string]Specifies the list of keys to set as transaction signer keys.

Return value

The env-keys function returns a string indicating that the transaction keys have been set.

Example

The following example demonstrates setting the transaction signer keys within a Pact REPL using env-keys:

pactbash
pact> (env-keys ["my-key" "admin-key"])"Setting transaction keys"
pactbash
pact> (env-keys ["my-key" "admin-key"])"Setting transaction keys"

In this example, env-keys is called with a list of two keys: "my-key" and "admin-key". The function sets these keys as the current transaction signer keys.

The function returns a string indicating that the transaction keys have been set.

env-namespace-policy

Use env-namespace-policy to install a managed namespace policy.

Basic syntax

pact
(env-namespace-policy allow-root ns-policy-fun)
pact
(env-namespace-policy allow-root ns-policy-fun)

Arguments

Use the following arguments when using the env-namespace-policy Pact function.

ArgumentTypeDescription
allow-rootboolSpecifies whether to allow root-level namespace creation. If set to true, root-level namespaces can be created. If set to false, root-level namespace creation is restricted.
ns-policy-funns:string ns-admin:guard -> boolSpecifies the namespace policy function. This function takes two arguments: ns (the namespace string) and ns-admin (the namespace admin guard), and returns a boolean value indicating whether the namespace is allowed based on the policy. The function should return true if the namespace is allowed, and false otherwise.

Return value

The env-namespace-policy function returns a string indicating that the namespace policy has been installed.

Example

The following example demonstrates installing a namespace policy within a Pact REPL:

pact
(env-namespace-policy (my-ns-policy-fun))
pact
(env-namespace-policy (my-ns-policy-fun))

env-sigs

Use env-sigs to set transaction signature keys and their associated capabilities.

Basic syntax

pact
(env-sigs sigs)
pact
(env-sigs sigs)

Arguments

Use the following argument when using the env-sigs Pact function.

ArgumentTypeDescription
sigs[object]Specifies the list of signature objects. Each object represents a signer key and its associated caps capabilities.

Return value

The env-sigs function returns a string indicating that the transaction signature keys and capabilities have been set.

Example

The following example demonstrates setting transaction signature keys and capabilities within a Pact REPL:

pact
(env-sigs [{'key: "my-key", 'caps: [(accounts.USER_GUARD "my-account")]}, {'key: "admin-key", 'caps: []}])
pact
(env-sigs [{'key: "my-key", 'caps: [(accounts.USER_GUARD "my-account")]}, {'key: "admin-key", 'caps: []}])

expect-failure

Use expect-failure to evaluate an expression and succeed only if it throws an error.

Basic syntax

To expect a failure without specifying the error message, use the following syntax:

pact
(expect-failure doc exp)
pact
(expect-failure doc exp)

To expect a failure with a specific error message, use the following syntax:

pact
(expect-failure doc err exp)
pact
(expect-failure doc err exp)

Arguments

Use the following arguments when using the expect-failure Pact function.

ArgumentTypeDescription
docstringSpecifies the documentation string describing the expected failure.
errstring(Optional) Specifies the expected error message.
exp<a>Specifies the expression to evaluate. The expression can be of any Pact type.

Return value

The expect-failure function returns a string indicating the success or failure of the expected failure.

  • If the expression exp throws an error, the function returns a string indicating the success of the expected failure, e.g., "Expect failure: success: Enforce fails on false".
  • If the expression exp does not throw an error, the function itself throws an error, indicating that the expected failure did not occur.

Examples

The following examples demonstrate the usage of expect-failure within a Pact REPL:

  1. Expecting a failure without specifying the error message:
pact
pact> (expect-failure "Enforce fails on false" (enforce false "Expected error"))"Expect failure: success: Enforce fails on false"
pact
pact> (expect-failure "Enforce fails on false" (enforce false "Expected error"))"Expect failure: success: Enforce fails on false"
  1. Expecting a failure with a specific error message:
pact
pact> (expect-failure "Enforce fails with message" "Expected error" (enforce false "Expected error"))"Expect failure: success: Enforce fails with message"
pact
pact> (expect-failure "Enforce fails with message" "Expected error" (enforce false "Expected error"))"Expect failure: success: Enforce fails with message"

expect-that

Use expect-that to evaluate an expression and succeed if the resulting value passes a predicate function.

Basic syntax

pact
(expect-that doc pred exp)
pact
(expect-that doc pred exp)

Arguments

Use the following arguments when using the expect-that Pact function.

ArgumentTypeDescription
docstringSpecifies the documentation string describing the expectation.
predvalue:<a> -> boolSpecifies the predicate function that takes the result of exp and returns a boolean.
exp<a>Specifies the expression to evaluate. The expression can be of any Pact type.

Return value

The expect-that function returns a string indicating the success or failure of the expectation.

Examples

The following examples demonstrate the usage of expect-that within a Pact REPL:

  1. Expectation passes:
pact
pact> (expect-that "addition" (< 2) (+ 1 2))"Expect-that: success: addition"
pact
pact> (expect-that "addition" (< 2) (+ 1 2))"Expect-that: success: addition"
  1. Expectation fails:
pact
pact> (expect-that "addition" (> 2) (+ 1 2))"FAILURE: addition: did not satisfy (> 2) : 3:integer"
pact
pact> (expect-that "addition" (> 2) (+ 1 2))"FAILURE: addition: did not satisfy (> 2) : 3:integer"

expect

Use expect to evaluate an expression and verify that the result equals an expected value.

Basic syntax

pact
(expect doc expected actual)
pact
(expect doc expected actual)

Arguments

Use the following arguments when using the expect Pact function.

ArgumentTypeDescription
docstringSpecifies the documentation string describing the expectation.
expected<a>Specifies the expected value to compare against the result of actual.
actual<a>Specifies the expression to evaluate. The expression can be of any Pact type.

Return value

The expect function returns a string indicating the success or failure of the expectation.

Example

The following example demonstrates the usage of expect within a Pact REPL:

pact
pact> (expect "Sanity prevails." 4 (+ 2 2))"Expect: success: Sanity prevails."
pact
pact> (expect "Sanity prevails." 4 (+ 2 2))"Expect: success: Sanity prevails."