Capability Tutorial
An introduction to capabilities and how they interact with resources in Cadence
Overview
https://play.onflow.org/3a541312-a231-4f11-be79-23bcd2d94a6c
The tutorial will ask you to take various actions to interact with this code.
This tutorial builds on the previous Resource
tutorial.
Before beginning this tutorial, you should have an idea of how accounts,transactions,resources, and signers work with basic field types.
This tutorial will build on your understanding of accounts and resources.
You'll learn how to interact with resources using capabilities
In Cadence, resources are a composite type like a struct or a class, but with some special rules:
- Each instance of a resource can only exist in exactly one location and cannot be copied.
- Resources must be explicitly moved from one location to another when accessed.
- Resources also cannot go out of scope at the end of function execution, they must be explicitly stored somewhere or destroyed.
Use-Cases for Capabilities and Scripts
Let's look at why you would want to use capabilities to expand access to resources in a real-world context.
A real user's account will contain functions and fields that need varying levels of access scope and privacy. For example, if you're working on an app that allows users to exchange tokens. While you definitely need to sign write access for a feature like withdrawing tokens from an account, your app should allow anybody to deposit tokens. After your user authenticates your app for the first time, you can create a capability that allows your app to withdraw tokens, this makes it more convenient to write transactions that can withdraw an account's tokens to spend or trade them.
In this tutorial, you will:
- Interact with the resource we created using transactions
- Create capabilities to extend the resource access scope
- Execute a script that interacts with the resource
Accessing Resources with Capabilities
Before following this tutorial, you should have the HelloWorld
contract deployed in account 0x01
,
just like in the previous Resource
contract tutorial.
Open the Account 0x01
tab with file named HelloWorldResource.cdc
.
HelloWorldResource.cdc
should contain the following code:
pub contract HelloWorld {
// Declare a resource that only includes one function.
pub resource HelloAsset {
// A transaction can call this function to get the "Hello, World!"
// message from the resource.
pub fun hello(): String {
return "Hello, World!"
}
}
// We're going to use the built-in create function to create a new instance
// of the HelloAsset resource
pub fun createHelloAsset(): @HelloAsset {
return <-create HelloAsset()
}
init() {
log("Hello Asset")
}
}
Deploy this code to account 0x01
using the Deploy
button.
Click on the Create Hello
transaction and send it with 0x01
as the signer.
The contract and transaction above creates and stores the resource we'll be using in this tutorial. For a more detailed breakdown of the contract, have a look at the previous tutorial.
Creating Capabilities and References to Stored Resources
You need explicit permission from the owner of an account to access its storage. Capabilities allow an account owner to grant access to specific fields and functions stored in their accounts. (Explained more below)
In this transaction, you create a new capability,
then use the link
function to create a public link to your HelloAsset
resource object.
Next you use that link to borrow a reference
to the underlying object and call the hello()
function.
A detailed explanation of what is happening in this transaction
is below the transaction code so, if you feel lost, keep reading!
Open the transaction named Create Link
.
Create Link
should contain the following code:
import HelloWorld from 0x01
// This transaction creates a new capability
// for the HelloAsset resource in storage
// and adds it to the account's public area.
//
// Other accounts and scripts can use this capability
// to create a reference to the private object to be able to
// access its fields and call its methods.
transaction {
prepare(account: AuthAccount) {
// Create a public capability by linking the capability to
// a `target` object in account storage.
// The capability allows access to the object through an
// interface defined by the owner.
// This does not check if the link is valid or if the target exists.
// It just creates the capability.
// The capability is created and stored at /public/Hello, and is
// also returned from the function.
let capability = account.link<&HelloWorld.HelloAsset>(/public/HelloAssetTutorial, target: /storage/HelloAssetTutorial)
// Use the capability's borrow method to create a new reference
// to the object that the capability links to
// We use optional chaining "??" to get the value because
// result of the borrow could fail, so it is an optional.
// If the optional is nil,
// the panic will happen with a descriptive error message
let helloReference = capability.borrow()
?? panic("Could not borrow a reference to the hello capability")
// Call the hello function using the reference
// to the HelloAsset resource.
//
log(helloReference.hello())
}
}
Ensure account 0x01
is still selected as a transaction signer.
Click the Send
button to send the transaction.
In this transaction, we use the prepare phase to:
- Create a capability with the
link
method to the stored objectHelloWorld.HelloAsset
from the account path/storage/HelloAssetTutorial
- Store the capability in the account path
/public/HelloAssetTutorial
- Use the
borrow
method to create a reference to the object we linked to calledhelloReference
- Call the
hello()
function using the reference we created,helloReference
You should see "Hello, World"
show up in the console again.
You might be confused that we were able to call a method on the HelloAsset
object
without actually being directly in control of it!
It is also stored in the /storage/
domain of the account, which should be private.
This is because we created a capability for the HelloAsset
object.
Capabilities are kind of like pointers in other languages.
Capability Based Access Control
Capabilities allow the owners of objects to specify what functionality of their private objects is available to others. Think of it kind of like an account's public API, if you're familiar with the concept. The account owner has private objects stored in their storage, like their collectibles or their money, but they might still want others to be able to see what collectibles they have in their account, or they want to allow anyone to deposit more money of a certain currency in their account. Since these objects are stored in private storage by default, the owner has to do something to open up access to these while still retaining full control. We create capabilities to accomplish this.
In our example, the owner of HelloAsset
might still want to let other people call the hello
method.
This is what capabilities are for. They represent a link to an object in an account's storage that has the type specified when the link is created.
It is important to remember that someone else who has this capability cannot move or destroy the object that the capability is linked to!
They can only access fields that the owner has explicitly declared in the type specification of the link
method (described below).
Capabilities do not have any meaningful functionality on their own, but every capability has a borrow
method,
which creates a reference to the object that the capability is linked to.
This reference is used to read fields or call methods on the object they reference
as if the owner of the reference had the actual object.
Note that this only allows access to fields and methods. It does not allow copying, moving, or modifying the original object directly.
Let's break down what is happening in this transaction.
First, we create a public link to the private HelloAsset
object in /storage/
:
let capability = account.link<&HelloWorld.HelloAsset>(/public/Hello, target: /storage/Hello)
The link
method returns a capability that can be used to access this link.
The HelloAsset
object is stored in /storage/HelloAssetTutorial
, which only the account owner can access.
They want any user in the network to be able to call the hello()
method. So they make a public capability in /public/HelloAssetTutorial
.
To create a capability, we use the AuthAccount.link
method to link a new capability to an object in storage.
The type contained in <>
is the restricted reference type that the capability represents.
The capability says that whoever borrows a reference from this capability can only have access to the fields and methods
that are specified by the type in <>
.
The specified type has to be a subtype of the type of the object being linked to,
meaning that it cannot contain any fields or functions that the linked object doesn't have.
A reference is referred to by the &
symbol. Here, the capability references the HelloAsset
object,
so we specify <&HelloWorld.HelloAsset>
as the type, which gives access to everything in the HelloAsset
object.
The first argument to the link
function is the path where you want to store the link for the capability
and the target
argument is the path to the object in storage that is to be linked to.
We always store links for capabilities in the /private/
or /public/
domains:
- We choose
/private/
if we only want to allow one or a small number of users to access it - We choose
/public/
if we want any user in the network to be able to access it. Capabilities always link to objects in the/storage/
domain.
To borrow a reference to an object from the capability, we use the capability's borrow
method.
let helloReference = capability.borrow()
?? panic("Could not borrow a reference to the hello capability")
This method creates the reference as the type we specified in <>
in the link
function.
While borrowing the reference, we use
optional chaining
because the borrowing of the reference could fail.
The reference could be nil
if the targeted storage slot is empty, is already borrowed,
or if the requested type exceeds what is allowed by the capability.
We panic with a descriptive error message so the caller can know better what went wrong.
We separate this process into capabilities and references to protect against reentrancy attacks. A reentrancy attack is where a malicious actor could call into an object multiple times. These attacks have plagued other smart contract languages. Only one reference to an object can exist at a time, so this type of vulnerability isn't possible for objects in storage when you use Cadence.
Additionally, the owner of an object can effectively revoke capabilities they have created by moving the underlying object or destroying the link with the unlink
method.
If the referenced object is moved or the link is destroyed, capabilities that have been created from that link are invalidated.
You can find more detailed documentation about capabilities in the language reference.
Now, anyone can call the hello()
method on your HelloAsset
object by borrowing a reference with your public capability in /public/Hello
!
(Covered in the next section)
Lastly, we call the hello()
method with our borrowed reference:
// Call the hello function using the reference to the HelloAsset resource
log(helloReference.hello())
At the end of the transaction execution, the helloReference
value is lost,
but that is ok because while it references a resource, it isn't the actual resource itself, so it is ok to lose it.
In the next section, we look at how capabilities can expand the access a script has to an account.
Executing Scripts
A script is a very simple transaction type in Cadence that cannot perform any writes to the blockchain and can only read the state of an account or contract. It runs without permission from any account, so scripts need capabilities to access account storage.
To execute a script, write a function called pub fun main()
.
You can click the execute script button to run the script.
The result of the script will be printed to the console output.
Open the file Script1.cdc
.
Script1.cdc
should look like the following:
import HelloWorld from 0x01
pub fun main() {
// Cadence code can get an account's public account object
// by using the getAccount() built-in function.
let helloAccount = getAccount(0x01)
// Get the public capability from the public path of the owner's account
let helloCapability = helloAccount.getCapability<&HelloWorld.HelloAsset>(/public/HelloAssetTutorial)
// borrow a reference for the capability
let helloReference = helloCapability.borrow()
?? panic("Could not borrow a reference to the hello capability")
// The log built-in function logs its argument to stdout.
//
// Here we are using optional chaining to call the "hello"
// method on the HelloAsset resource that is referenced
// in the published area of the account.
log(helloReference.hello())
}
Here's what this script does:
- It fetches the
PublicAccount
object withgetAccount
and assigns it to the variablehelloAccount
- Uses the
getCapability
method to get the capability from theCreate Link
transaction - Borrows a reference for the capability using the
borrow
method and assigns it tohelloReference
- Logs the result of the
hello()
function fromhelloReference
to the console.
let helloAccount = getAccount(0x01)
The PublicAccount
object is available to anyone in the network for every account,
but only has access to a small subset of functions that can be read from the /public/
domain in an account.
Most of the account storage API
is not available on the PublicAccount
object,
and only signed transactions can make persistent changes to the AuthAccount
object.
AuthAccount
can now be accessed publicly in scripts with the getAuthAccount
function,
but any changes are discarded after the script execution.
With capabilities we can make resources saved to an account explicitly available in the /public/
domain.
See the language reference for more information about accounts.
Then, the script gets the capability that was created in Create Link
.
// Get the public capability from the public path of the owner's account
let helloCapability = helloAccount.getCapability(/public/HelloAssetTutorial)
To get a capability that is stored in an account, use the account.getCapability()
function.
This function is available on AuthAccount
s and on PublicAccount
s.
getCapability()
returns a capability for the link at the path that is specified,
also with the type that is specified.
It does not check if the target exists, so the borrow will fail if the capability is invalid.
After that, the script borrows a reference from the capability.
let helloReference = helloCapability.borrow()
Then, the script uses the reference to call the hello()
function and prints the result.
Let's execute the script to see it run correctly.
Click the Execute
button in the playground.
You should see something like this print:
> "Hello, World"
> Result > "void"
Good work! Your script ran successfully.
Reviewing Capabilities
This tutorial expanded on the idea of resources in Cadence by expanding access scope to a resource using capabilities and covering more account storage API use-cases.
You deployed a smart contract with a resource, then created a capability to grant access to that resource.
With the capability, you used the borrow method to create a reference and used the reference to call the
resource's hello()
function.
Finally, you used a script to borrow the same capability and create a reference so that the script can
call the resource's hello()
function. This is important because script's cannot access account storage
without using capabilities.
Now that you have completed the tutorial, you have the basic knowledge to write a simple Cadence program that can:
- Implement a resource in a smart contract
- Create capabilities to grant access to resources in an account
- Interact with resources using both signed transactions and scripts
Feel free to modify the smart contract to create different resources, experiment with the available account storage API, and write new transactions and scripts that execute different functions from your smart contract. Have a look at the capability-based access control page to find out more about what you can do with capabilities.
You're on the right track to building more complex applications with Cadence, now is a great time to check out the Cadence Best Practices document and Anti-patterns document as your applications become more complex.