Guards

Use create-capability-guard to create a predicate function that ensures that specific conditions are true and can be enforced to grant the specified CAPABILITY.

By convention, capabilities are defined using all uppercase letters.

To create a predicate function that guards the specified CAPABILITY, use the following syntax:

Use the following argument to specify the CAPABILITY for the create-capability-guard Pact function.

The create-capability-guard function returns a guard that enforces the acquisition of the specified CAPABILITY.

The following example demonstrates how to use the create-capability-guard function to create a guard for the GOVERNANCE capability:

The conditions specified for the GOVERNANCE capability must evaluate to true for the capability to be acquired and related code where the capability is required to be executed.

The following example illustrates how to create a guard for an ESCROW_MANAGEMENT account:

Use create-capability-pact-guard to create a predicate function that ensures that specific conditions are true and can be enforced to grant the specified CAPABILITY for steps defined in a defpact multi-step transaction.

By convention, capabilities are defined using all uppercase letters.

To create a predicate function that guards the specified CAPABILITY in a defpact multi-step transaction, use the following syntax:

Use the following argument to specify the CAPABILITY for the create-capability-pact-guard Pact function.

The create-capability-pact-guard function returns a guard that enables the code associated with the specified CAPABILITY to be executed in the context of a defpact multi-step transaction.

The following example demonstrates how to use the create-capability-pact-guard function to create a guard for the ESCROW owner capability in adefpact step:

The following example creates a guard for the SALE_PRIVATE capability associated with the pact-id for the sales contract being executed:

Use create-module-guard to create a predicate function with the specified name that ensures that specific conditions are true for the current module.

Module guards are typically used to enable a module to perform administrative operations independently outside of the module itself, for example, to own coins in an external ledger, or to perform administrative operations internally on its database, for example, to own and manage certain assets.

To define a predicate function name that guards administrative activity for the current module, use the following syntax:

Use the following argument to specify the name for the create-module-guard Pact function.

The create-module-guard function returns a guard with the specified namethat enables the current module to perform administrative operations.

The following example demonstrates how to use the create-module-guard function to define a guard named "module-admin-guard" for the current module:

If the evaluation of the module-admin-guard returns true, the current module is granted administrative privileges.

Use create-pact-guard to define a predicate function with the specified name that captures the results of the pact-id function for a defpact transaction.

When enforced, the guard will only return true if the pact-id at enforcement is the same as the pact-id captured by the create-pact-guard function. This check ensures that the guard will only succeed within the multi-step transaction identified by the pact-id.

To define a predicate function by name that captures the results of the pact-id function, use the following syntax:

Use the following argument to specify the name for the create-pact-guard Pact function.

The create-pact-guard function returns a guard with the specified name that captures the pact-id' for a defpact multi-step transaction.

The following example demonstrates how to use the create-pact-guard function to define a guard named "pact-id-guard" that captures the pact-id' for a defpact multi-step transaction:

This guard ensures that it will only succeed within the multi-transaction identified by the pact id.

Use create-principal to create a principal account that unambiguously identifies a specified guard predicate function.

For an introduction to principal accounts, see Accounts, keys, and principals.

To create a principal that identifies a guard predicate function, use the following syntax:

Use the following argument to specify the guard for the create-principal Pact function.

The create-principal function returns a string representing a principal that unambiguously identifies the specified guard predicate function.

The following example demonstrates how to use the create-principal function to create a principal that unambiguously identifies the keyset guard:

This principal can then be used for various purposes such as access control in Pact code.

Use create-user-guard to define a custom guard closure whose arguments are strictly evaluated at definition time and supplied to the indicated function at enforcement time.

To define a custom guard closure for use in Pact, use the following syntax:

Use the following argument to specify the closure for the create-user-guard Pact function.

The create-user-guard function returns a guard that uses the specified custom closure function that returns a boolean value.

The following example demonstrates how to use the create-user-guard function to obtain a keyset, then use the keyset as a custom guard closure function:

In this example, (read-keyset 'my-keyset) is used as the closure function to capture a keyset to use when the user guard is enforced. This code allows you to define custom user guards based on specific keysets or conditions.

The following example defines a user guard for the enforce-fungible-transfer function that must evaluate to true to allow a fungible transfer:

Use is-principal to determine whether a principal string conforms to the principal format without proving its validity.

To check whether a principal string conforms to the principal format, use the following syntax:

Use the following argument to specify the principal string you want to check using the is-principal Pact function.

The is-principal function returns a boolean value indicating whether the specified principal string conforms to the principal format.

The following example demonstrates how to use the is-principal function in the Pact REPL to check whether the specified string conforms to the principal format:

The following example demonstrates how to use the is-principal function in an enforce statement:

In this example, the is-principal function ensures that the sender account conforms to the format for principal accounts. If the format is valid, the enforce statement returns true and the LOCK_DEPOSIT capability is granted. If the sender isn't a valid principal format, the enforce statement returns the "Sender must be a principal account" error message.

The following example checks the format of a principal account associated with a capability guard in an enforce statement:

In this example, the length of the specified string doesn't conform to the format for a principal account, so the enforce statement returns the error message.

Use keyset-ref-guard to create a guard for the keyset registered as keyset-ref using the define-keyset function. Concrete keysets are themselves guard types. This function is specifically to store references alongside other guards in the database.

To create a guard for a keyset registered with the define-keyset function, use the following syntax:

Use the following argument to specify the keyset reference for which you want to create a guard using the keyset-ref-guard Pact function.

The keyset-ref-guard function returns a guard type corresponding to the specified keyset reference.

The following example demonstrates how to use the keyset-ref-guard function to create a guard for the keyset registered as "my-keyset" using the define-keyset function:

Use typeof-principal to return the protocol type of the specified principal value. If the specified value is not a principal type, then an empty string is returned.

To determine the protocol type of a specified principal value, use the following syntax:

Use the following argument to specify the principal value that you want to determine the protocol type for using the typeof-principal Pact function.

The typeof-principal function returns the protocol type of the specified principal value as a string. If the input value is not a principal type, an empty string is returned.

The following example demonstrates how to use the typeof-principal function to determine the protocol type of a principal value:

The following example uses the typeof-principal function to create a namespace using the guard associated with the principal account name:

Use validate-principal to validate that a principal unambiguously identifies a specified guard.

To validate a principal against guard, use the following syntax:

(validate-principal guard principal)

Use the following arguments to specify the guard and the principal that you want to validate using the validate-principal Pact function.

The validate-principal function returns a boolean value indicating whether the provided principal unambiguously identifies the specified guard.

The following example demonstrates how to use the validate-principal function to ensure that the principal obtained from reading a keyset matches the specified principal account:

The following example uses validate-principal in a function to ensure the merchant and buyer accounts are guarded principal account: