access(all)
struct Capabilities {
 
    /// The storage capabilities of the account.
    access(mapping CapabilitiesMapping)
    let storage: Account.StorageCapabilities
 
    /// The account capabilities of the account.
    access(mapping CapabilitiesMapping)
    let account: Account.AccountCapabilities
 
    /// Returns the capability at the given public path.
    /// If the capability does not exist,
    /// or if the given type is not a supertype of the capability's borrow type,
    /// returns an "invalid" capability with ID 0 that will always fail to `check` or `borrow`
    access(all)
    view fun get<T: &Any>(_ path: PublicPath): Capability<T>
 
    /// Borrows the capability at the given public path.
    /// Returns nil if the capability does not exist, or cannot be borrowed using the given type.
    /// The function is equivalent to `get(path).borrow()`.
    access(all)
    view fun borrow<T: &Any>(_ path: PublicPath): T?
 
    /// Returns true if a capability exists at the given public path.
    access(all)
    view fun exists(_ path: PublicPath): Bool
 
    /// Publish the capability at the given public path.
    ///
    /// If there is already a capability published under the given path, the program aborts.
    ///
    /// The path must be a public path, i.e., only the domain `public` is allowed.
    access(Capabilities | PublishCapability)
    fun publish(_ capability: Capability, at: PublicPath)
 
    /// Unpublish the capability published at the given path.
    ///
    /// Returns the capability if one was published at the path.
    /// Returns nil if no capability was published at the path.
    access(Capabilities | UnpublishCapability)
    fun unpublish(_ path: PublicPath): Capability?
}
 
entitlement Capabilities
 
entitlement PublishCapability
entitlement UnpublishCapability

access(all)
view fun exists(_ path: PublicPath): Bool

access(all)
view fun get<T: &Any>(_ path: PublicPath): Capability<T>

access(all)
view fun borrow<T: &Any>(_ path: PublicPath): T?

access(all)
struct StorageCapabilities {
 
    /// Issue/create a new storage capability.
    access(Capabilities | StorageCapabilities | IssueStorageCapabilityController)
    fun issue<T: &Any>(_ path: StoragePath): Capability<T>
 
    /// Issue/create a new storage capability.
    access(Capabilities | StorageCapabilities | IssueStorageCapabilityController)
    fun issueWithType(_ path: StoragePath, type: Type): Capability
 
    /// Get the storage capability controller for the capability with the specified ID.
    ///
    /// Returns nil if the ID does not reference an existing storage capability.
    access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
    view fun getController(byCapabilityID: UInt64): &StorageCapabilityController?
 
    /// Get all storage capability controllers for capabilities that target this storage path
    access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
    view fun getControllers(forPath: StoragePath): [&StorageCapabilityController]
 
    /// Iterate over all storage capability controllers for capabilities that target this storage path,
    /// passing a reference to each controller to the provided callback function.
    ///
    /// Iteration is stopped early if the callback function returns `false`.
    ///
    /// If a new storage capability controller is issued for the path,
    /// an existing storage capability controller for the path is deleted,
    /// or a storage capability controller is retargeted from or to the path,
    /// then the callback must stop iteration by returning false.
    /// Otherwise, iteration aborts.
    access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
    fun forEachController(
        forPath: StoragePath,
        _ function: fun(&StorageCapabilityController): Bool
    )
}
 
access(all)
struct AccountCapabilities {
 
    /// Issue/create a new account capability.
    access(Capabilities | AccountCapabilities | IssueAccountCapabilityController)
    fun issue<T: &Account>(): Capability<T>
 
    /// Issue/create a new account capability.
    access(Capabilities | AccountCapabilities | IssueAccountCapabilityController)
    fun issueWithType(_ type: Type): Capability
 
    /// Get capability controller for capability with the specified ID.
    ///
    /// Returns nil if the ID does not reference an existing account capability.
    access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
    view fun getController(byCapabilityID: UInt64): &AccountCapabilityController?
 
    /// Get all capability controllers for all account capabilities.
    access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
    view fun getControllers(): [&AccountCapabilityController]
 
    /// Iterate over all account capability controllers for all account capabilities,
    /// passing a reference to each controller to the provided callback function.
    ///
    /// Iteration is stopped early if the callback function returns `false`.
    ///
    /// If a new account capability controller is issued for the account,
    /// or an existing account capability controller for the account is deleted,
    /// then the callback must stop iteration by returning false.
    /// Otherwise, iteration aborts.
    access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
    fun forEachController(_ function: fun(&AccountCapabilityController): Bool)
}
 
entitlement StorageCapabilities
entitlement AccountCapabilities
 
entitlement GetStorageCapabilityController
entitlement IssueStorageCapabilityController
 
entitlement GetAccountCapabilityController
entitlement IssueAccountCapabilityController
 
entitlement mapping CapabilitiesMapping {
    include Identity
 
    StorageCapabilities -> GetStorageCapabilityController
    StorageCapabilities -> IssueStorageCapabilityController
 
    AccountCapabilities -> GetAccountCapabilityController
    AccountCapabilities -> IssueAccountCapabilityController
}

access(all)
struct AccountCapabilityController {
 
    /// The capability that is controlled by this controller.
    access(all)
    let capability: Capability
 
    /// An arbitrary "tag" for the controller.
    /// For example, it could be used to describe the purpose of the capability.
    /// Empty by default.
    access(all)
    var tag: String
 
    /// Updates this controller's tag to the provided string
    access(all)
    fun setTag(_ tag: String)
 
    /// The type of the controlled capability, i.e. the T in `Capability<T>`.
    access(all)
    let borrowType: Type
 
    /// The identifier of the controlled capability.
    /// All copies of a capability have the same ID.
    access(all)
    let capabilityID: UInt64
 
    /// Delete this capability controller,
    /// and disable the controlled capability and its copies.
    ///
    /// The controller will be deleted from storage,
    /// but the controlled capability and its copies remain.
    ///
    /// Once this function returns, the controller is no longer usable,
    /// all further operations on the controller will panic.
    ///
    /// Borrowing from the controlled capability or its copies will return nil.
    ///
    access(all)
    fun delete()
}

access(all)
struct StorageCapabilityController {
 
    /// The capability that is controlled by this controller.
    access(all)
    let capability: Capability
 
    /// An arbitrary "tag" for the controller.
    /// For example, it could be used to describe the purpose of the capability.
    /// Empty by default.
    access(all)
    var tag: String
 
    /// Updates this controller's tag to the provided string
    access(all)
    fun setTag(_ tag: String)
 
    /// The type of the controlled capability, i.e. the T in `Capability<T>`.
    access(all)
    let borrowType: Type
 
    /// The identifier of the controlled capability.
    /// All copies of a capability have the same ID.
    access(all)
    let capabilityID: UInt64
 
    /// Delete this capability controller,
    /// and disable the controlled capability and its copies.
    ///
    /// The controller will be deleted from storage,
    /// but the controlled capability and its copies remain.
    ///
    /// Once this function returns, the controller is no longer usable,
    /// all further operations on the controller will panic.
    ///
    /// Borrowing from the controlled capability or its copies will return nil.
    ///
    access(all)
    fun delete()
 
    /// Returns the targeted storage path of the controlled capability.
    access(all)
    fun target(): StoragePath
 
    /// Retarget the controlled capability to the given storage path.
    /// The path may be different or the same as the current path.
    access(all)
    fun retarget(_ target: StoragePath)
}

access(Capabilities | StorageCapabilities | IssueStorageCapabilityController)
fun issue<T: &Any>(_ path: StoragePath): Capability<T>

transaction {
    prepare(signer: auth(IssueStorageCapabilityController) &Account) {
        let capability = signer.capabilities.storage.issue<auth(Withdraw) &Vault>(/storage/vault)
        // ...
    }
}

access(Capabilities | AccountCapabilities | IssueAccountCapabilityController)
fun issue<T: &Account>(): Capability<T>

transaction {
    prepare(signer: auth(IssueAccountCapabilityController) &Account) {
        let capability = signer.capabilities.account.issue<auth(SaveValue) &Account>()
        // ...
    }
}

access(Capabilities | PublishCapability)
fun publish(_ capability: Capability, at: PublicPath)

transaction {
    prepare(signer: auth(Capabilities) &Account) {
        let capability = signer.capabilities.storage.issue<&Vault>(/storage/vault)
        signer.capabilities.publish(capability, at: /public/vault)
    }
}

access(Capabilities | UnpublishCapability)
fun unpublish(_ path: PublicPath): Capability?

transaction {
    prepare(signer: auth(Capabilities) &Account) {
        signer.capabilities.unpublish(/public/vault)
    }
}

access(all)
var tag: String
 
access(all)
fun setTag(_ tag: String)

access(all)
fun target(): StoragePath
 
access(all)
fun retarget(_ target: StoragePath)

access(all)
fun delete()

access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
view fun getController(byCapabilityID: UInt64): &StorageCapabilityController?

access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
view fun getController(byCapabilityID: UInt64): &AccountCapabilityController?

access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
view fun getControllers(forPath: StoragePath): [&StorageCapabilityController]
 
access(Capabilities | StorageCapabilities | GetStorageCapabilityController)
fun forEachController(
    forPath: StoragePath,
    _ function: fun(&StorageCapabilityController): Bool
)

access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
view fun getControllers(): [&AccountCapabilityController]
 
access(Capabilities | AccountCapabilities | GetAccountCapabilityController)
fun forEachController(_ function: fun(&AccountCapabilityController): Bool)

entitlement Increment
 
// Declare a resource named `Counter` that has a field `count`
// and a function `increment`, which requires the `Increment` entitlement.
//
access(all)
resource Counter {
 
    access(all)
    var count: UInt
 
    access(all)
    init(count: UInt) {
        self.count = count
    }
 
    access(Increment)
    fun increment(by amount: UInt) {
        self.count = self.count + amount
    }
}
 
// In this example an account reference is available through the constant `account`,
// which has the type `auth(Storage, Capabilities) &Account`,
// i.e., the reference is authorized to perform storage and capability operations.
 
// Create a new instance of the resource type `Counter`
// and save it in the storage of the account.
//
// The path `/storage/counter` is used to refer to the stored value.
// Its identifier `counter` was chosen freely and could be something else.
//
account.storage.save(
    <-create Counter(count: 42),
    to: /storage/counter
)
 
// Issue a new storage capability that allows access to the stored counter resource
//
let capability = account.capabilities.storage.issue<&Counter>(/storage/counter)
 
// Publish the capability under the path `/public/counter`,
// so that anyone can access the counter resource.
//
// Its identifier `counter` was chosen freely and could be something else.
//
account.capabilities.publish(capability, at: /public/counter)

 
// Get a reference to the account that stores the counter
//
let account = getAccount(0x1)
 
// Borrow the capability for the counter that is made publicly accessible
// through the path `/public/counter`.
//
// The call of `borrow` returns an optional reference `&Counter?`.
// The borrow succeeds, and the result is not `nil`,
// it is a valid reference, because:
//
// 1. The path `/public/counter` stores a capability.
//
// 2. The capability allows to be borrowed as `&Counter`,
//    as it has the type `Capability<&Counter>`.
//
// 3. The target of the storage capability, the *path* `/storage/counter`,
//    stores an object and it has a type which is a subtype of the borrowed type
//    (type equality is also considered a subtype relationship).
//
// Finally, force-unwrap the optional reference.
// After the call, the declared constant `counterRef` has type `&Counter`.
//
let counterRef = account.capabilities.borrow<&Counter>(/public/counter)!
 
// Read the field `count` of the `Counter`.
// The field can be accessed, because it has the access modifier `access(all)`.
//
// Even though it is a variable field (`var`),
// it cannot be assigned to from outside of the object.
//
counterRef.count  // is `42`
 
// Invalid: The `increment` function is not accessible for the reference,
// because the reference has the type `&Counter`,
// which does not authorize the entitlement `Increment`,
// which is required by the `increment` function
// (it has the access modifier ` access(Increment)`).
//
counterRef.increment(by: 5)
 
// Again, attempt to borrow the capability for the counter,
// but use the type `auth(Increment) &Counter` to re-attempt the call to `increment`.
//
// Getting the capability fails, because the capability was issued using the type `&Counter`.
// After the call, `counterRef2` is `nil`.
//
let counterRef2 = account.capabilities.borrow<auth(Increment) &Counter>(/public/counter)