Capabilities

Use compose-capability to compose and grant capabilities in a nested structure to control the scope of how the capabilities are applied. By convention, capabilities are defined using all uppercase letters.

With this function, you can define the specified CAPABILITY within the context of an outer defcap declaration. The function is only valid within the distinct defcap body of its outer capability, such that the CAPABILITY you specify for the compose-capability function is included when you call the with-capability function for its outer capability.

For example, if you call (with-capability (OUTER-CAP) OUTER-BODY) and the OUTER-CAP declaration includes the (compose-capability (INNER-CAP)) function, the INNER-CAP capability is granted in the scope of the OUTER-BODY logic.

To compose and grant a specified CAPABILITY within an outer capability body, use the following syntax:

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

The compose-capability function returns a boolean value to indicate success or failure in requesting the grant of the specified CAPABILITY.

The following example demonstrates how to use the compose-capability function within the body of the TRANSFER capability and include the DEBIT and CREDIT capabilities when the with-capability function is called:

Use emit-event to emit a specified CAPABILITY as an event without evaluating the body of the capability. This function fails if the specified CAPABILITY doesn't include the @managed or @event keyword in its declaration.

By convention, capabilities are defined using all uppercase letters.

To emit a CAPABILITY as an event without evaluating its body, use the following syntax:

Use the following argument to specify the CAPABILITY for the emit-event Pact function.

The emit-event function returns a boolean value indicating success or failure of emitting the event.

The following example demonstrates how to use the emit-event function to emit an event for the TRANSFER capability with the parameters "Bob", "Alice", and 12.0:

The function returns a boolean value indicating the success or failure of emitting the event.

Use install-capability to specify and provision a managed capability. Managed capabilities are defined in defcap declarations that include the @managed keyword. The @managed keyword designates a single parameter to be managed by a specified management function. After a capability is installed, it must still be brought into scope using the with-capability function. When the capability is brought into scope, its management function is invoked to validate the request.

The management function takes the type of the managed parameter, executes the logic required to validate the requested capability or perform the managed operation, and returns the new managed value that results from the request.

The type signature for the management function is managed:<p> requested:<p> -> <p>, where <p> indicates the type of the managed parameter. For example, assume you define a managed capability as:

The management function for this capability would be:

Any capability that has static unmanaged parameters will invoke the management function with the current managed value and that of the requested capability. The function should perform whatever logic, presumably linear, to validate the request, and return the new managed value representing the balance of the request.

Note that signatures scoped to a managed capability cause the capability to be automatically provisioned in a manner similar to how capabilities are installed with this function.

By convention, capabilities are defined using all uppercase letters.

To specify and provision a managed capability, use the following syntax:

Use the following argument to specify the capability you want to install using the install-capability Pact function.

The install-capability function returns a boolean value indicating the success or failure of the installation, along with a string message providing additional information.

The following example demonstrates how to use the install-capability to install a capability named coin.TRANSFER with specified parameters:

The following example illustrates the definition for a capability with a management function and a managed parameter.

The following example demonstrates the use of install-capability in the Pact REPL to install a capability named PAY with specified parameters:

If the PAY capability is installed successfully, the function returns a boolean value indicating success. If the capability isn't installed, the function returns an error message indicating the reason for failure.

Use require-capability to require a specific CAPABILITY to be granted before allowing the current body of code to be executed. If the required capability isn't found in the environment, the code fails to execute.

By convention, capabilities are defined using all uppercase letters.

To test whether a specific CAPABILITY has been granted before executing a portion of code in a contract, use the following syntax:

Use the following argument to specify the CAPABILITY to be tested for using the require-capability Pact function.

The require-capability function returns a boolean value indicating whether the specified CAPABILITY exists in the environment.

The following example demonstrates how to use the require-capability function to check whether the capability to transfer funds from one source to another has been granted:

If the capability isn't found, the function fails.

The following example uses the require-capability function to create a guard that ensure both the GAS and ALLOW_GAS capabilities have been granted:

Use with-capability to apply the access to a specific capability to execute a body of code. This function ensures that an elevated privilege—defined as a capability using a defcap code block—is present during the execution of the provided body of code.

You can only call the with-capability function in the same module that contains the corresponding defcap declaration. If the token that grants permission to use the specified capability isn't found, the with-capability evaluates the capability definition to install or grant the permission token. The permission token is automatically revoked after executing the code body. Nested with-capability calls for the same permission token detect the presence of the token and execute the body without reapplying the capability.

By convention, capabilities are defined using all uppercase letters.

To request the grant of an acquired CAPABILITY, use the following syntax:

Use the following arguments to specify the name of the capability and the body of expressions to be executed using the with-capability Pact function.

The with-capability function returns the result of executing the provided body of code using the granted capability.

The following example demonstrates how to use the with-capability function to request access to the UPDATE-USERS capability to execute the code that updates user information:

In this example, the with-capability function ensures that a sensitive operation can only be executed with an elevated permission granted using the UPDATE-USERS capability.