Skip to main content
Last updated

Guards

create-capability-guard

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

Basic syntax

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

(create-capability-guard CAPABILITY)

Arguments

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

ArgumentTypeDescription
CAPABILITYcapabilitySpecifies the capability that the guard will enforce acquisition for.

Return values

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

Examples

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

pact
(create-capability-guard (BANK_DEBIT 10.0))
pact
(create-capability-guard (BANK_DEBIT 10.0))

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.

create-capability-pact-guard

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.

Basic syntax

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)

Arguments

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

ArgumentTypeDescription
CAPABILITYcapabilitySpecifies the capability that the guard will enforce acquisition for.

Return values

The create-capability-pact-guard function returns a guard that enforces the acquisition of the specified CAPABILITY and checks for an operational defpact.

Examples

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

pact
(create-capability-pact-guard (ESCROW owner))
pact
(create-capability-pact-guard (ESCROW owner))

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.

create-module-guard

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

Basic syntax

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

(create-module-guard NAME)

Arguments

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

ArgumentTypeDescription
NAMEstringSpecifies the name of the guard to create, enforcing the current module admin predicate.

Return values

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

Example

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

pact
(create-module-guard "module-admin-guard")
pact
(create-module-guard "module-admin-guard")

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.

create-pact-guard

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.

Basic syntax

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

create-pact-guard NAME

Arguments

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

ArgumentTypeDescription
NAMEstringSpecifies the name of the guard to create, capturing the 'pact-id' results.

Return values

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

Example

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

pact
(create-pact-guard "pact-id-guard")
pact
(create-pact-guard "pact-id-guard")

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.

create-principal

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

Basic syntax

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

create-principal GUARD

Arguments

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

ArgumentTypeDescription
GUARDguardSpecifies the guard for which to create a principal.

Return values

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

Example

The following example demonstrates the create-principal function:

pact
(create-principal (read-keyset 'keyset))
pact
(create-principal (read-keyset 'keyset))

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.

create-user-guard

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.

Basic syntax

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

(create-user-guard CLOSURE)

Arguments

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

ArgumentTypeDescription
CLOSUREclosureSpecifies the custom guard closure to define. The closure is a function that takes no arguments and returns a boolean value.

Return values

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

Example

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

pact
(create-user-guard (read-keyset 'my-keyset))
pact
(create-user-guard (read-keyset 'my-keyset))

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.

is-principal

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

Basic syntax

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

(is-principal principal)

Arguments

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

ArgumentTypeDescription
principalstringSpecifies the principal string to be checked.

Return value

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

Examples

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

pact
pact>(enforce (is-principal "k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69") "Invalid account structure: non-principal account")true
pact
pact>(enforce (is-principal "k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69") "Invalid account structure: non-principal account")true

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".

keyset-ref-guard

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.

Basic syntax

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

(keyset-ref-guard KEYSET-REF)

Arguments

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

ArgumentTypeDescription
KEYSET-REFstringSpecifies the reference to the keyset registered with define-keyset.

Return value

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

Examples

The following example demonstrates the use of keyset-ref-guard:

pact
(keyset-ref-guard "my-keyset")
pact
(keyset-ref-guard "my-keyset")

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

typeof-principal

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.

Basic syntax

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

`(typeof-principal principal)

Argument

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

ArgumentTypeDescription
principalstringSpecifies the principal value for which to determine the protocol type.

Return value

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.

Examples

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:

pact
(typeof-principal 'k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69)
pact
(typeof-principal 'k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69)

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

validate-principal

The validate-principal function validates that a principal unambiguously identifies a specified guard.

Basic syntax

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

(validate-principal GUARD PRINCIPAL)

Arguments

Use the following arguments to specify the guard and the principal for validation using the validate-principal Pact function.

ArgumentTypeDescription
GUARDguardSpecifies the guard to validate against.
PRINCIPALstringSpecifies the principal to be validated.

Return value

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

Examples

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:

pact
(enforce (validate-principal (read-keyset 'keyset) account) "Invalid account ID")
pact
(enforce (validate-principal (read-keyset 'keyset) account) "Invalid account ID")

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.