aptos-move/framework/aptos-stdlib/doc/capability.md
<a id="0x1_capability"></a>
0x1::capabilityA module which defines the basic concept of capabilities for managing access control.
EXPERIMENTAL
<a id="@Overview_0"></a>
A capability is a unforgeable token which testifies that a signer has authorized a certain operation. The token is valid during the transaction where it is obtained. Since the type <code><a href="capability.md#0x1_capability_Cap">capability::Cap</a></code> has no ability to be stored in global memory, capabilities cannot leak out of a transaction. For every function called within a transaction which has a capability as a parameter, it is guaranteed that the capability has been obtained via a proper signer-based authorization step previously in the transaction's execution.
<a id="@Usage_1"></a>
Initializing and acquiring capabilities is usually encapsulated in a module with a type tag which can only be constructed by this module.
module Pkg::Feature {
use std::capability::Cap;
/// A type tag used in Cap<Feature>. Only this module can create an instance,
/// and there is no public function other than Self::acquire which returns a value of this type.
/// This way, this module has full control how Cap<Feature> is given out.
struct Feature has drop {}
/// Initializes this module.
public fun initialize(s: &signer) {
// Create capability. This happens once at module initialization time.
// One needs to provide a witness for being the owner of Feature
// in the 2nd parameter.
<<additional conditions allowing to initialize this capability>>
capability::create<Feature>(s, &Feature{});
}
/// Acquires the capability to work with this feature.
public fun acquire(s: &signer): Cap<Feature> {
<<additional conditions allowing to acquire this capability>>
capability::acquire<Feature>(s, &Feature{});
}
/// Does something related to the feature. The caller must pass a Cap<Feature>.
public fun do_something(_cap: Cap<Feature>) { ... }
}
<a id="@Delegation_2"></a>
Capabilities come with the optional feature of delegation. Via <code><a href="capability.md#0x1_capability_delegate">Self::delegate</a></code>, an owner of a capability can designate another signer to be also capable of acquiring the capability. Like the original creator, the delegate needs to present his signer to obtain the capability in his transactions. Delegation can be revoked via <code><a href="capability.md#0x1_capability_revoke">Self::revoke</a></code>, removing this access right from the delegate.
While the basic authorization mechanism for delegates is the same as with core capabilities, the target of delegation might be subject of restrictions which need to be specified and verified. This can be done via global invariants in the specification language. For example, in order to prevent delegation all together for a capability, one can use the following invariant:
invariant forall a: address where capability::spec_has_cap<Feature>(a):
len(capability::spec_delegates<Feature>(a)) == 0;
Similarly, the following invariant would enforce that delegates, if existent, must satisfy a certain predicate:
invariant forall a: address where capability::spec_has_cap<Feature>(a):
forall d in capability::spec_delegates<Feature>(a):
is_valid_delegate_for_feature(d);
CapLinearCapCapStateCapDelegateStatecreateacquireacquire_linearvalidate_acquireroot_addrlinear_root_addrdelegaterevokeremove_elementadd_element<a id="0x1_capability_Cap"></a>
CapThe token representing an acquired capability. Cannot be stored in memory, but copied and dropped freely.
<pre><code><b>struct</b> <a href="capability.md#0x1_capability_Cap">Cap</a><Feature> <b>has</b> <b>copy</b>, drop </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>root: <b>address</b></code> </dt> <dd> </dd> </dl> </details><a id="0x1_capability_LinearCap"></a>
LinearCapA linear version of a capability token. This can be used if an acquired capability should be enforced to be used only once for an authorization.
<pre><code><b>struct</b> <a href="capability.md#0x1_capability_LinearCap">LinearCap</a><Feature> <b>has</b> drop </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>root: <b>address</b></code> </dt> <dd> </dd> </dl> </details><a id="0x1_capability_CapState"></a>
CapStateAn internal data structure for representing a configured capability.
<pre><code><b>struct</b> <a href="capability.md#0x1_capability_CapState">CapState</a><Feature> <b>has</b> key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>delegates: <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><<b>address</b>></code> </dt> <dd> </dd> </dl> </details><a id="0x1_capability_CapDelegateState"></a>
CapDelegateStateAn internal data structure for representing a configured delegated capability.
<pre><code><b>struct</b> <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature> <b>has</b> key </code></pre> <details> <summary>Fields</summary> <dl> <dt> <code>root: <b>address</b></code> </dt> <dd> </dd> </dl> </details><a id="@Constants_3"></a>
<a id="0x1_capability_ECAPABILITY_ALREADY_EXISTS"></a>
Capability resource already exists on the specified account
<pre><code><b>const</b> <a href="capability.md#0x1_capability_ECAPABILITY_ALREADY_EXISTS">ECAPABILITY_ALREADY_EXISTS</a>: u64 = 1; </code></pre><a id="0x1_capability_ECAPABILITY_NOT_FOUND"></a>
Capability resource not found
<pre><code><b>const</b> <a href="capability.md#0x1_capability_ECAPABILITY_NOT_FOUND">ECAPABILITY_NOT_FOUND</a>: u64 = 2; </code></pre><a id="0x1_capability_EDELEGATE"></a>
Account does not have delegated permissions
<pre><code><b>const</b> <a href="capability.md#0x1_capability_EDELEGATE">EDELEGATE</a>: u64 = 3; </code></pre><a id="0x1_capability_create"></a>
createCreates a new capability class, owned by the passed signer. A caller must pass a witness that they own the <code>Feature</code> type parameter.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_create">create</a><Feature>(owner: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_create">create</a><Feature>(owner: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature) { <b>let</b> addr = <a href="../../move-stdlib/doc/signer.md#0x1_signer_address_of">signer::address_of</a>(owner); <b>assert</b>!(!<b>exists</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(addr), <a href="../../move-stdlib/doc/error.md#0x1_error_already_exists">error::already_exists</a>(<a href="capability.md#0x1_capability_ECAPABILITY_ALREADY_EXISTS">ECAPABILITY_ALREADY_EXISTS</a>)); <b>move_to</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(owner, <a href="capability.md#0x1_capability_CapState">CapState</a> { delegates: <a href="../../move-stdlib/doc/vector.md#0x1_vector_empty">vector::empty</a>() }); } </code></pre> </details><a id="0x1_capability_acquire"></a>
acquireAcquires a capability token. Only the owner of the capability class, or an authorized delegate, can succeed with this operation. A caller must pass a witness that they own the <code>Feature</code> type parameter.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_acquire">acquire</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature): <a href="capability.md#0x1_capability_Cap">capability::Cap</a><Feature> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_acquire">acquire</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature): <a href="capability.md#0x1_capability_Cap">Cap</a><Feature> <b>acquires</b> <a href="capability.md#0x1_capability_CapState">CapState</a>, <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a> { <a href="capability.md#0x1_capability_Cap">Cap</a><Feature> { root: <a href="capability.md#0x1_capability_validate_acquire">validate_acquire</a><Feature>(requester) } } </code></pre> </details><a id="0x1_capability_acquire_linear"></a>
acquire_linearAcquires a linear capability token. It is up to the module which owns <code>Feature</code> to decide whether to expose a linear or non-linear capability.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_acquire_linear">acquire_linear</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature): <a href="capability.md#0x1_capability_LinearCap">capability::LinearCap</a><Feature> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_acquire_linear">acquire_linear</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>, _feature_witness: &Feature): <a href="capability.md#0x1_capability_LinearCap">LinearCap</a><Feature> <b>acquires</b> <a href="capability.md#0x1_capability_CapState">CapState</a>, <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a> { <a href="capability.md#0x1_capability_LinearCap">LinearCap</a><Feature> { root: <a href="capability.md#0x1_capability_validate_acquire">validate_acquire</a><Feature>(requester) } } </code></pre> </details><a id="0x1_capability_validate_acquire"></a>
validate_acquireHelper to validate an acquire. Returns the root address of the capability.
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_validate_acquire">validate_acquire</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>): <b>address</b> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>fun</b> <a href="capability.md#0x1_capability_validate_acquire">validate_acquire</a><Feature>(requester: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>): <b>address</b> <b>acquires</b> <a href="capability.md#0x1_capability_CapState">CapState</a>, <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a> { <b>let</b> addr = <a href="../../move-stdlib/doc/signer.md#0x1_signer_address_of">signer::address_of</a>(requester); <b>if</b> (<b>exists</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(addr)) { <b>let</b> root_addr = <b>borrow_global</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(addr).root; // double check that requester is actually registered <b>as</b> a delegate <b>assert</b>!(<b>exists</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(root_addr), <a href="../../move-stdlib/doc/error.md#0x1_error_invalid_state">error::invalid_state</a>(<a href="capability.md#0x1_capability_EDELEGATE">EDELEGATE</a>)); <b>assert</b>!(<b>borrow_global</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(root_addr).delegates.contains(&addr), <a href="../../move-stdlib/doc/error.md#0x1_error_invalid_state">error::invalid_state</a>(<a href="capability.md#0x1_capability_EDELEGATE">EDELEGATE</a>)); root_addr } <b>else</b> { <b>assert</b>!(<b>exists</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(addr), <a href="../../move-stdlib/doc/error.md#0x1_error_not_found">error::not_found</a>(<a href="capability.md#0x1_capability_ECAPABILITY_NOT_FOUND">ECAPABILITY_NOT_FOUND</a>)); addr } } </code></pre> </details><a id="0x1_capability_root_addr"></a>
root_addrReturns the root address associated with the given capability token. Only the owner of the feature can do this.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_root_addr">root_addr</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">capability::Cap</a><Feature>, _feature_witness: &Feature): <b>address</b> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_root_addr">root_addr</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">Cap</a><Feature>, _feature_witness: &Feature): <b>address</b> { self.root } </code></pre> </details><a id="0x1_capability_linear_root_addr"></a>
linear_root_addrReturns the root address associated with the given linear capability token.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_linear_root_addr">linear_root_addr</a><Feature>(self: <a href="capability.md#0x1_capability_LinearCap">capability::LinearCap</a><Feature>, _feature_witness: &Feature): <b>address</b> </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_linear_root_addr">linear_root_addr</a><Feature>(self: <a href="capability.md#0x1_capability_LinearCap">LinearCap</a><Feature>, _feature_witness: &Feature): <b>address</b> { self.root } </code></pre> </details><a id="0x1_capability_delegate"></a>
delegateRegisters a delegation relation. If the relation already exists, this function does nothing.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_delegate">delegate</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">capability::Cap</a><Feature>, _feature_witness: &Feature, <b>to</b>: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_delegate">delegate</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">Cap</a><Feature>, _feature_witness: &Feature, <b>to</b>: &<a href="../../move-stdlib/doc/signer.md#0x1_signer">signer</a>) <b>acquires</b> <a href="capability.md#0x1_capability_CapState">CapState</a> { <b>let</b> addr = <a href="../../move-stdlib/doc/signer.md#0x1_signer_address_of">signer::address_of</a>(<b>to</b>); <b>if</b> (<b>exists</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(addr)) <b>return</b>; <b>move_to</b>(<b>to</b>, <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature> { root: self.root }); <a href="capability.md#0x1_capability_add_element">add_element</a>(&<b>mut</b> <b>borrow_global_mut</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(self.root).delegates, addr); } </code></pre> </details><a id="0x1_capability_revoke"></a>
revokeRevokes a delegation relation. If no relation exists, this function does nothing.
<pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_revoke">revoke</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">capability::Cap</a><Feature>, _feature_witness: &Feature, from: <b>address</b>) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>public</b> <b>fun</b> <a href="capability.md#0x1_capability_revoke">revoke</a><Feature>(self: <a href="capability.md#0x1_capability_Cap">Cap</a><Feature>, _feature_witness: &Feature, from: <b>address</b>) <b>acquires</b> <a href="capability.md#0x1_capability_CapState">CapState</a>, <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a> { <b>if</b> (!<b>exists</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(from)) <b>return</b>; <b>let</b> <a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a> { root: _root } = <b>move_from</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(from); <a href="capability.md#0x1_capability_remove_element">remove_element</a>(&<b>mut</b> <b>borrow_global_mut</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(self.root).delegates, &from); } </code></pre> </details><a id="0x1_capability_remove_element"></a>
remove_elementHelper to remove an element from a vector.
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_remove_element">remove_element</a><E: drop>(v: &<b>mut</b> <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><E>, x: &E) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>fun</b> <a href="capability.md#0x1_capability_remove_element">remove_element</a><E: drop>(v: &<b>mut</b> <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><E>, x: &E) { <b>let</b> (found, index) = v.index_of(x); <b>if</b> (found) { v.remove(index); } } </code></pre> </details><a id="0x1_capability_add_element"></a>
add_elementHelper to add an element to a vector.
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_add_element">add_element</a><E: drop>(v: &<b>mut</b> <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><E>, x: E) </code></pre> <details> <summary>Implementation</summary> <pre><code><b>fun</b> <a href="capability.md#0x1_capability_add_element">add_element</a><E: drop>(v: &<b>mut</b> <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><E>, x: E) { <b>if</b> (!v.contains(&x)) { v.push_back(x) } } </code></pre> </details><a id="@Specification_4"></a>
Helper specification function to check whether a capability exists at address.
<a id="0x1_capability_spec_has_cap"></a>
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_spec_has_cap">spec_has_cap</a><Feature>(addr: <b>address</b>): bool { <b>exists</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(addr) } </code></pre>Helper specification function to obtain the delegates of a capability.
<a id="0x1_capability_spec_delegates"></a>
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_spec_delegates">spec_delegates</a><Feature>(addr: <b>address</b>): <a href="../../move-stdlib/doc/vector.md#0x1_vector">vector</a><<b>address</b>> { <b>global</b><<a href="capability.md#0x1_capability_CapState">CapState</a><Feature>>(addr).delegates } </code></pre>Helper specification function to check whether a delegated capability exists at address.
<a id="0x1_capability_spec_has_delegate_cap"></a>
<pre><code><b>fun</b> <a href="capability.md#0x1_capability_spec_has_delegate_cap">spec_has_delegate_cap</a><Feature>(addr: <b>address</b>): bool { <b>exists</b><<a href="capability.md#0x1_capability_CapDelegateState">CapDelegateState</a><Feature>>(addr) } </code></pre><a id="@Specification_4_create"></a>
create<a id="@Specification_4_acquire"></a>
acquire<a id="@Specification_4_acquire_linear"></a>
acquire_linear<a id="0x1_capability_AcquireSchema"></a>
<pre><code><b>schema</b> <a href="capability.md#0x1_capability_AcquireSchema">AcquireSchema</a><Feature> { addr: <b>address</b>; root_addr: <b>address</b>; <b>aborts_if</b> <a href="capability.md#0x1_capability_spec_has_delegate_cap">spec_has_delegate_cap</a><Feature>(addr) && !<a href="capability.md#0x1_capability_spec_has_cap">spec_has_cap</a><Feature>(root_addr); <b>aborts_if</b> <a href="capability.md#0x1_capability_spec_has_delegate_cap">spec_has_delegate_cap</a><Feature>(addr) && !<a href="../../move-stdlib/doc/vector.md#0x1_vector_spec_contains">vector::spec_contains</a>(<a href="capability.md#0x1_capability_spec_delegates">spec_delegates</a><Feature>(root_addr), addr); <b>aborts_if</b> !<a href="capability.md#0x1_capability_spec_has_delegate_cap">spec_has_delegate_cap</a><Feature>(addr) && !<a href="capability.md#0x1_capability_spec_has_cap">spec_has_cap</a><Feature>(addr); } </code></pre><a id="@Specification_4_delegate"></a>
delegate<a id="@Specification_4_revoke"></a>
revoke<a id="@Specification_4_remove_element"></a>
remove_element<a id="@Specification_4_add_element"></a>
add_element