Guards

Use create-capability-guard to create a guard that will enforce that a specified CAPABILITY is acquired.

To create a guard that enforces the acquisition of a CAPABILITY, use the following syntax:

(create-capability-guard CAPABILITY)

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 the create-capability-guard function:

In this example, (create-capability-guard (BANK_DEBIT 10.0)) is used to create a guard that enforces the acquisition of the BANK_DEBIT 10.0 capability. This guard can then be used to enforce the presence of this capability in Pact code.

Use create-capability-pact-guard to create a guard that enforces that a specified CAPABILITY is acquired and that the currently-executing defpact is operational.

To create a guard that enforces the acquisition of a CAPABILITY and checks for an operational defpact, use the following syntax:

(create-capability-pact-guard CAPABILITY)

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 enforces the acquisition of the specified CAPABILITY and checks for an operational defpact.

The following example demonstrates the create-capability-pact-guard function:

In this example, (create-capability-pact-guard (ESCROW owner)) is used to create a guard that enforces the acquisition of the ESCROW owner capability and checks for an operational defpact. This guard ensures that the ESCROW owner capability is acquired and that the current defpact is operational before proceeding with Pact code execution.

Use create-module-guard to define a guard by NAME that enforces the current module admin predicate.

To define a guard by NAME that enforces the current module admin predicate, use the following syntax:

(create-module-guard NAME)

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

The create-module-guard function returns a guard that enforces the current module admin predicate, identified by the specified NAME.

The following example demonstrates the create-module-guard function:

In this example, (create-module-guard "module-admin-guard") is used to define a guard named "module-admin-guard" that enforces the current module admin predicate. This guard can then be used to enforce module admin privileges in Pact code.

Use create-pact-guard to define a guard predicate by NAME that captures the results of 'pact-id'. At enforcement time, the success condition is that at that time 'pact-id' must return the same value. This ensures that the guard will only succeed within the multi-transaction identified by the pact id.

To define a guard predicate by NAME that captures the results of 'pact-id', use the following syntax:

create-pact-guard NAME

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

The create-pact-guard function returns a guard predicate identified by the specified NAME, which captures the 'pact-id' results.

The following example demonstrates the create-pact-guard function:

In this example, (create-pact-guard "pact-id-guard") is used to define a guard named "pact-id-guard" that captures the results of 'pact-id'. This guard ensures that it will only succeed within the multi-transaction identified by the pact id.

Use create-principal to create a principal that unambiguously identifies a specified GUARD.

To create a principal that identifies a GUARD, use the following syntax:

create-principal GUARD

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.

The following example demonstrates the create-principal function:

In this example, (create-principal (read-keyset 'keyset)) is used 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:

(create-user-guard CLOSURE)

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

The create-user-guard function returns a guard that utilizes the specified custom CLOSURE.

The following example demonstrates the create-user-guard function:

In this example, (read-keyset 'my-keyset) is used to obtain a keyset, and this keyset is then used as a custom guard closure in create-user-guard. The closure captures the keyset at definition time, and it will be supplied to the indicated function at enforcement time. This allows for custom user-defined guards based on specific keysets or conditions.

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:

(is-principal principal)

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 input principal string conforms to the principal format.

The following example demonstrates the use of is-principal within an enforce statement:

In this example, the is-principal function checks whether the provided principal string conforms to the principal format. If the string conforms to the format, the enforce statement proceeds without triggering an error; otherwise, it throws an error with the message "Invalid account structure: non-principal account".

Use keyset-ref-guard to create a guard for the keyset registered as KEYSET-REF with the define-keyset function. Concrete keysets are themselves guard types; this function is specifically to store references alongside other guards in the database, etc.

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

(keyset-ref-guard KEYSET-REF)

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 the use of keyset-ref-guard:

In this example, keyset-ref-guard creates a guard for the keyset registered as "my-keyset" using define-keyset.

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

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

`(typeof-principal principal)

Use the following argument to specify the PRINCIPAL value for which to determine the protocol type using the typeof-principal Pact function.

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

The following example demonstrates the usage of the typeof-principal function within a Pact script. It determines the protocol type of a given principal value:

This example illustrates how to use the typeof-principal function to determine the protocol type of a principal value in Pact.

The validate-principal function validates 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 for validation 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 the usage of the validate-principal function within a Pact script. It enforces that the principal obtained from reading a keyset matches the specified account, ensuring it is valid:

This example illustrates how to use the validate-principal function to validate that a principal unambiguously identifies a specified guard in Pact, ensuring the security and integrity of the identification process.