REPL-only functions

Use begin-tx to begin a new transaction with an optional name. This function is used to create tests that you want to execute using the Pact REPL. In most cases, you include this function in .repl files that test specific application features and failure scenarios.

Within the context of a transaction, you can set environment data, load modules, and execute functions. To complete the transaction, use the commit-tx function. The commit-tx function signals the end of a transaction block and can be followed by additional begin-tx and commit-tx blocks.

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 example demonstrates how to use the begin-tx function to begin a new transaction without a name:

The following example demonstrates how to use the begin-tx function to begin a new transaction with a specific name:

You can write an empty transaction as a placeholder for the logic to test specific function or failure scenarios. For example, to create a placeholder for the logic that defines a namespace:

Use commit-tx to commit the current transaction. In most cases, you include this function in .repl files that test specific application features and failure scenarios.

Within the context of a transaction started using the begin-tx function, you can set environment data, load modules, and execute functions. You use the commit-tx function to signal the end of a transaction block and can be followed by additional begin-tx and commit-tx blocks.

To commit a transaction, use the following syntax:

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 how to use the commit-tx function within a Pact REPL:

In this example, a new transaction—Tx0—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 you should only call the commit-tx function after performing the necessary operations within a transaction. The commit-tx function finalizes the transaction, and any changes made during the transaction are persisted.

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

Use continue-pact to continue a previously-initiated multi-step transaction defined using a defpact declaration. You must specify the step at which to continue. You can also specify 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 example demonstrates how to use the continue-pact function to continue a pact with step 1:

The following example demonstrates how to use the continue-pact function to continue a pact with step 1 and perform a rollback:

The following example demonstrates how to use the continue-pact function to continue a pact with step 1, without rollback, and specify the pact ID:

The following example demonstrates how to use the continue-pact function to continue a pact with step 2, without rollback, specify the pact ID, and provide a yielded value:

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:

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 how to use describe-module function to describe a loaded module:

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-chain-data to define chain information for transactions in your testing environment. You can this function to create an object with one or more of the following fields:

To set one or more chain data fields, use the following syntax:

Use the following argument to specify the chain data you want to set using the env-chain-data Pact function.

The env-chain-data function returns an object with the chain data you specify.

The following example demonstrates how to use the env-chain-data function to set a chain identifier and block time for a transaction:

Use env-data to set transaction data for your testing environment either as an encoded string or as Pact types coerced to JSON format.

To set transaction data, use the following syntax:

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:

In the following example, the env-data function is used to set up a mock token identifier and account information for testing Marmalade functions:

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

If you set this function to true to enable REPL native functions in module code, other environment configuration functions like env-sigs are allowed in module code, and you can use these functions in your module definitions.

If you set this function to false to disable REPL native functions in module code, other environment configuration functions are not allowed in module code, and attempting to use them will result in an error.

To allow REPL native functions to be used in module code, use the following syntax:

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.

The following example demonstrates how to enable REPL native functions:

After enabling REPL natives, you can use environment configuration functions like env-sigs in your module code.

It's important to note that you should only enable REPL native functions in module code—that is, executable .pact files—if absolutely necessary. Most REPL native functions are intended to be used exclusively in the REPL environment. If you enable access to the REPL native functions in module code, ensure that access to the functions is properly controlled and validated.

The following example demonstrates how to disable access to REPL native functions:

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

To retrieve events and clear the event state, use the following syntax:

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:

The following example demonstrates how to retrieve events, then clear the event state:

In this example, there were no events to retrieve, so an empty list is returned.

The following example retrieves three events—TOKEN, MINT, and ACCOUNT-GUARD—without clearing the event state:

To set one or more configuration flags, use the following syntax:

Use the following argument to specify the configuration data you want to set using the env-exec-config Pact function.

The env-exec-config function returns the list of configuration flags that have been set for the execution environment.

The following example demonstrates how to use the env-exec-config function to enforce key formats and disable Pact events:

The following example demonstrates how to unset previously-set configuration flags using the env-exec-config function:

The following example demonstrates how to check the current configuration settings:

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:

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

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

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

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

The following example demonstrates how to use the env-gas function to query the current gas state:

In the following example, the env-gas function resets the current gas state to zero:

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

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

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.

The following example demonstrates how to use the env-gaslimit function to set a gas limit for the environment:

Use env-gaslog to enable gas logging for a block of code. You can use this function to check the gas required to execute a specific block of code.

To enable gas logging for a specific block of code, use the following syntax:

The env-gaslog function does not take any arguments.

The env-gaslog function returns the log messages in strings that describe the gas consumed by each operation in the code block.

The following example demonstrates how to use the env-gaslog function to report the gas consumed for the specified map function:

In this example, the ["TOTAL: 0"] message signals the beginning of gas logging for the map function. The messages after "TOTAL: 7" provide details about how the gas was calculated.

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

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

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:

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 example demonstrates how to use the env-gasmodel function to query the current gas model:

The following example demonstrates how to use the env-gasmodel function to update the current gas model to use a table-based cost model:

In the following example, the env-gasmodel function updates the gas model to use a fixed rate of two:

Use env-hash to set the current transaction hash.

To set the current transaction hash, use the following syntax:

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 how to use the env-hash function to set the transaction hash using the base64-url encoded string for the hello string:

The following example illustrates using the env-hash function to create a transaction hash for the test transaction that creates a token:

Use env-keys to set the transaction signer keys in older version of the Pact REPL. The env-keys function is deprecated in favor of env-sigs. You should use env-sigs for setting transaction signer keys with associated capabilities.

To set transaction signer keys in older version of the Pact REPL, use the following syntax:

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 how to use the env-keys function to set "my-key" and "admin-key" as the current transaction signing keys in a Pact REPL:

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

To install a managed namespace policy, use the following syntax:

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 how to use the env-namespace-policy function to install a namespace policy in a Pact REPL:

Use env-sigs to set signature keys for signing transactions and granting capabilities.

To set the signature keys to use for signing transactionL and granting capabilities, use the following syntax:

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 how to use the env-sigs function to set two transaction signature keys—"my-key" and "admin-key"—and capabilities:

The following example illustrates using the env-sigs function to grant "any" key the MINT capability:

(env-sigs [ { 'key: 'any ,'caps: [(MINT (read-msg "token-id") (read-string 'account) 1.0)]} ])

Use expect-failure to evaluate an expression and succeed only if the expressions results in an error. This function enables you to verify that use cases that should failbehave as expected.

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 example demonstrates how to use the expect-failure function without specifying the expected error message:

The following example illustrates using the expect-failure function with a specific expected error message:

In this example, the doc argument describes the test being performed. The err argument specifies the error message that is returned when the expression is evaluated.

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

You can use any data type for the exp argument as long as the pred function can take that same data type and return the resulting boolean value . By convention, the data type <a> is used to represent type-bound parameters that serve as input for functions and expressions or for generic arguments.

To evaluate an expression that returns a predicate function, use the following syntax:

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 example demonstrates how to use the expect-that function to evaluate an expression that returns the expected result:

The following example demonstrates how to use the expect-that function to evaluate an expression that returns fails to return the expected result:

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

To evaluate an expression that returns an expected result, use the following syntax:

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 how to use the function expect to evaluate an expression that returns an expected result in a Pact REPL:

The following example illustrates using the expect function to verify that the information expected to be inserted into a table is the same as the result of the get-token-info function:

(expect "Token info is inserted into table" { "id": "t:YV6-cQBhE_EoIXAuNV08aGXLfcucBEGy0Gb1Pj6w_Oo" ,"supply": 0.0 ,"precision": 0 ,"uri": "test-uri" ,"policies": [] } (get-token-info "t:YV6-cQBhE_EoIXAuNV08aGXLfcucBEGy0Gb1Pj6w_Oo") )