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.
Argument | Type | Description |
---|---|---|
CAPABILITY | capability | Specifies 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:
(create-capability-guard (BANK_DEBIT 10.0))
(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.
Argument | Type | Description |
---|---|---|
CAPABILITY | capability | Specifies 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:
(create-capability-pact-guard (ESCROW owner))
(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.
Argument | Type | Description |
---|---|---|
NAME | string | Specifies 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:
(create-module-guard "module-admin-guard")
(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.
Argument | Type | Description |
---|---|---|
NAME | string | Specifies 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:
(create-pact-guard "pact-id-guard")
(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.
Argument | Type | Description |
---|---|---|
GUARD | guard | Specifies 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:
(create-principal (read-keyset 'keyset))
(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.
Argument | Type | Description |
---|---|---|
CLOSURE | closure | Specifies 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:
(create-user-guard (read-keyset 'my-keyset))
(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.
Argument | Type | Description |
---|---|---|
principal | string | Specifies 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>(enforce (is-principal "k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69") "Invalid account structure: non-principal account")true
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.
Argument | Type | Description |
---|---|---|
KEYSET-REF | string | Specifies 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
:
(keyset-ref-guard "my-keyset")
(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.
Argument | Type | Description |
---|---|---|
principal | string | Specifies 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:
(typeof-principal 'k:462e97a099987f55f6a2b52e7bfd52a36b4b5b470fed0816a3d9b26f9450ba69)
(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.
Argument | Type | Description |
---|---|---|
GUARD | guard | Specifies the guard to validate against. |
PRINCIPAL | string | Specifies 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:
(enforce (validate-principal (read-keyset 'keyset) account) "Invalid account ID")
(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.