REPL-only functions

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

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

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

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

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

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

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.

Use commit-tx to commit the current transaction.

(commit-tx)

The commit-tx function does not take any arguments.

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

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

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.

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

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

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

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

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

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

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

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

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

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

(describe-module MODULE)

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

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

The following example demonstrates the describe-module function:

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.

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

(env-data json)

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

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

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

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

(env-enable-repl-natives enable)

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

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

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.

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

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.

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

(env-events clear)

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

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

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

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)

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

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.

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

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

(env-gaslimit limit)

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

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

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

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

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

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

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

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.

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

Use env-hash to set the current transaction hash.

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

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

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

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.

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

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

The following example demonstrates setting the transaction signer keys within a Pact REPL using env-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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Use the following arguments when using the expect Pact function.

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

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