diff --git a/docs/builtins/Capabilities/compose-capability.md b/docs/builtins/Capabilities/compose-capability.md index 9624ad84..e54fc953 100644 --- a/docs/builtins/Capabilities/compose-capability.md +++ b/docs/builtins/Capabilities/compose-capability.md @@ -1,4 +1,3 @@ -## compose-capability 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. @@ -8,7 +7,7 @@ The function is only valid within the distinct `defcap` body of its outer capabi 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. -### Basic syntax +## Basic syntax To compose and grant a specified `CAPABILITY` within an outer capability body, use the following syntax: @@ -16,7 +15,7 @@ To compose and grant a specified `CAPABILITY` within an outer capability body, u (compose-capability CAPABILITY) ``` -### Arguments +## Arguments Use the following argument to specify the `CAPABILITY` for the `compose-capability` Pact function. @@ -24,11 +23,11 @@ Use the following argument to specify the `CAPABILITY` for the `compose-capabili | --- | --- | --- | | `CAPABILITY` | capability | Specifies the capability to include in the scope of an outer capability. | -### Return values +## Return values The `compose-capability` function returns a boolean value to indicate success or failure in requesting the grant of the specified `CAPABILITY`. -### Examples +## Examples 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: diff --git a/docs/builtins/Capabilities/emit-event.md b/docs/builtins/Capabilities/emit-event.md index 2adf54fa..92915502 100644 --- a/docs/builtins/Capabilities/emit-event.md +++ b/docs/builtins/Capabilities/emit-event.md @@ -1,11 +1,10 @@ -## emit-event 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. -### Basic syntax +## Basic syntax To emit a `CAPABILITY` as an event without evaluating its body, use the following syntax: @@ -13,7 +12,7 @@ To emit a `CAPABILITY` as an event without evaluating its body, use the followin (emit-event CAPABILITY) ``` -### Arguments +## Arguments Use the following argument to specify the `CAPABILITY` for the `emit-event` Pact function. @@ -21,11 +20,11 @@ Use the following argument to specify the `CAPABILITY` for the `emit-event` Pact |------------|------|---------------------------------------------------| | `CAPABILITY` | capability | Specifies the capability to emit as an event. | -### Return values +## Return values The `emit-event` function returns a boolean value indicating success or failure of emitting the event. -### Examples +## Examples 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`: diff --git a/docs/builtins/Capabilities/install-capability.md b/docs/builtins/Capabilities/install-capability.md index b8ef2b82..e3df7836 100644 --- a/docs/builtins/Capabilities/install-capability.md +++ b/docs/builtins/Capabilities/install-capability.md @@ -1,4 +1,3 @@ -## install-capability 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. @@ -20,7 +19,6 @@ The management function for this capability would be: (defun FOO-mgr:integer (managed:integer requested:integer) ...) ``` - 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. @@ -28,7 +26,7 @@ Note that signatures scoped to a managed capability cause the capability to be a By convention, capabilities are defined using all uppercase letters. -### Basic syntax +## Basic syntax To specify and provision a managed capability, use the following syntax: @@ -36,7 +34,7 @@ To specify and provision a managed capability, use the following syntax: (install-capability CAPABILITY) ``` -### Arguments +## Arguments Use the following argument to specify the capability you want to install using the `install-capability` Pact function. @@ -44,11 +42,11 @@ Use the following argument to specify the capability you want to install using t | --- | --- | --- | | `CAPABILITY` | any | Specifies the capability to be installed. | -### Return value +## Return value The `install-capability` function returns a boolean value indicating the success or failure of the installation, along with a string message providing additional information. -### Examples +## Examples The following example demonstrates how to use the `install-capability` to install a capability named `coin.TRANSFER` with specified parameters: diff --git a/docs/builtins/Capabilities/require-capability.md b/docs/builtins/Capabilities/require-capability.md index 8cff2aa4..58e97f55 100644 --- a/docs/builtins/Capabilities/require-capability.md +++ b/docs/builtins/Capabilities/require-capability.md @@ -1,11 +1,10 @@ -## require-capability 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. -### Basic syntax +## Basic syntax To test whether a specific `CAPABILITY` has been granted before executing a portion of code in a contract, use the following syntax: @@ -13,7 +12,7 @@ To test whether a specific `CAPABILITY` has been granted before executing a port (require-capability CAPABILITY) ``` -### Arguments +## Arguments Use the following argument to specify the `CAPABILITY` to be tested for using the `require-capability` Pact function. @@ -21,11 +20,11 @@ Use the following argument to specify the `CAPABILITY` to be tested for using th | --- | --- | --- | | `CAPABILITY` | | Specifies the capability that must be granted before executing a certain portion of code. | -### Return value +## Return value The `require-capability` function returns a boolean value indicating whether the specified `CAPABILITY` exists in the environment. -### Examples +## Examples 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: diff --git a/docs/builtins/Capabilities/with-capability.md b/docs/builtins/Capabilities/with-capability.md index 568d650f..9f4c54e3 100644 --- a/docs/builtins/Capabilities/with-capability.md +++ b/docs/builtins/Capabilities/with-capability.md @@ -1,4 +1,3 @@ -## with-capability 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. @@ -10,7 +9,7 @@ Nested `with-capability` calls for the same permission token detect the presence By convention, capabilities are defined using all uppercase letters. -### Basic syntax +## Basic syntax To request the grant of an acquired `CAPABILITY`, use the following syntax: @@ -18,7 +17,7 @@ To request the grant of an acquired `CAPABILITY`, use the following syntax: (with-capability CAPABILITY body) ``` -### Arguments +## Arguments 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. @@ -27,11 +26,11 @@ Use the following arguments to specify the name of the capability and the body o | `CAPABILITY` | capability | Specifies the name of the capability to grant access to. | | `body` | any | Specifies the body of expressions to be executed using the granted capability. | -### Return value +## Return value The `with-capability` function returns the result of executing the provided body of code using the granted capability. -### Examples +## Examples 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: