Capabilities

Cadence supports capability-based security through the object-capability model.

A capability in Cadence is a value that represents the right to access an object and perform certain operations on it. A capability specifies what can be accessed, and how it can be accessed.

Capabilities are unforgeable, transferable, and revocable.

Capabilities can be storage capabilities or account capabilities:

• Storage capabilities grant access to objects in account storage, via paths
• Account capabilities grant access to accounts

Capabilities can be borrowed to get a reference to the stored object or the account it refers to.

Capabilities have the type Capability<T: &Any>. The type parameter specifies the kind of reference that can be obtained when borrowing the capability. The type specifies the associated set of access rights through entitlements: the reference type of the capability can be authorized, which grants the owner of the capability the ability to access the fields and functions of the target which require the given entitlements.

For example, a capability which has type Capability<auth(SaveValue) &Account> grants access to an account, and allows saving a value into the account.

Each capability has an ID. The ID is unique per account/address.

Capabilities are created and managed through capability controllers.

Capabilities are structs, so they are copyable. They can be used (e.g. borrowed) arbitrarily many times, as long as the target capability controller has not been deleted.

Capability

_31

access(all)

_31

struct Capability<T: &Any> {

_31

_31

/// The address of the account which the capability targets.

_31

access(all)

_31

let address: Address

_31

_31

/// The ID of the capability.

_31

access(all)

_31

let id: UInt64

_31

_31

/// Returns a reference to the targeted object.

_31

///

_31

/// If the capability is revoked, the function returns nil.

_31

///

_31

/// If the capability targets an object in account storage,

_31

/// and and no object is stored at the target storage path,

_31

/// the function returns nil.

_31

///

_31

/// If the targeted object cannot be borrowed using the given type,

_31

/// the function panics.

_31

///

_31

access(all)

_31

view fun borrow(): T?

_31

_31

/// Returns true if the capability currently targets an object

_31

/// that satisfies the given type, i.e. could be borrowed using the given type.

_31

///

_31

access(all)

_31

view fun check(): Bool

_31

}