Contracts
A contract in Cadence is a collection of type definitions of interfaces, structs, resources, data (its state), and code (its functions) that lives in the contract storage area of an account in Flow.
Contracts are where all composite types like structs, resources, events, and interfaces for these types in Cadence have to be defined. Therefore, an object of one of these types cannot exist without having been defined in a deployed Cadence contract.
Contracts can be created, updated, and removed using the contracts
object of authorized accounts.
This functionality is covered in the next section
Contracts are types. They are similar to composite types, but are stored differently than structs or resources and cannot be used as values, copied, or moved like resources or structs.
Contracts stay in an account's contract storage area and can only be added, updated, or removed by the account owner with special commands.
Contracts are declared using the contract
keyword. The keyword is followed
by the name of the contract.
Contracts cannot be nested in each other.
One of the simplest forms of a contract would just be one with a state field,
a function, and an init
function that initializes the field:
This contract could be deployed to an account and live permanently in the contract storage. Transactions and other contracts can interact with contracts by importing them at the beginning of a transaction or contract definition.
Anyone could call the above contract's hello
function by importing
the contract from the account it was deployed to and using the imported
object to call the hello function.
There can be any number of contracts per account and they can include an arbitrary amount of data. This means that a contract can have any number of fields, functions, and type definitions, but they have to be in the contract and not another top-level definition.
Another important feature of contracts is that instances of resources and events that are declared in contracts can only be created/emitted within functions or types that are declared in the same contract.
It is not possible create instances of resources and events outside the contract.
The contract below defines a resource interface Receiver
and a resource Vault
that implements that interface. The way this example is written,
there is no way to create this resource, so it would not be usable.
If a user tried to run a transaction that created an instance of the Vault
type,
the type checker would not allow it because only code in the FungibleToken
contract can create new Vault
s.
The contract would have to either define a function that creates new
Vault
instances or use its init
function to create an instance and
store it in the owner's account storage.
This brings up another key feature of contracts in Cadence. Contracts
can interact with its account's storage
and published
objects to store
resources, structs, and references.
They do so by using the special self.account
object that is only accessible within the contract.
Imagine that these were declared in the above FungibleToken
contract.
Now, any account could call the createVault
function declared in the contract
to create a Vault
object.
Or the owner could call the withdraw
function on their own Vault
to send new vaults to others.
Account access
Contracts have the implicit field let account: AuthAccount
,
which is the account in which the contract is deployed too.
This gives the contract the ability to e.g. read and write to the account's storage.
Deploying, Updating, and Removing Contracts
In order for a contract to be used in Cadence, it needs to be deployed to an account.
The deployed contracts of an account can be accessed through the contracts
object.
Deployed Contracts
Accounts store "deployed contracts", that is, the code of the contract:
Note that this is not the contract instance that can be acquired by importing it.
Deploying a New Contract
A new contract can be deployed to an account using the add
function:
Adds the given contract to the account.
The code
parameter is the UTF-8 encoded representation of the source code.
The code must contain exactly one contract or contract interface,
which must have the same name as the name
parameter.
All additional arguments that are given are passed further to the initializer of the contract that is being deployed.
Fails if a contract/contract interface with the given name already exists in the account, if the given code does not declare exactly one contract or contract interface, or if the given name does not match the name of the contract/contract interface declaration in the code.
Returns the deployed contract.
For example, assuming the following contract code should be deployed:
The contract can be deployed as follows:
Updating a Deployed Contract
Updating contracts is experimental.
Updating contracts is currently limited to maintain data consistency. Certain restrictions are imposed.
A deployed contract can be updated using the update__experimental
function:
Updates the code for the contract/contract interface in the account.
The code
parameter is the UTF-8 encoded representation of the source code.
The code must contain exactly one contract or contract interface,
which must have the same name as the name
parameter.
Does not run the initializer of the contract/contract interface again. The contract instance in the world state stays as is.
Fails if no contract/contract interface with the given name exists in the account, if the given code does not declare exactly one contract or contract interface, or if the given name does not match the name of the contract/contract interface declaration in the code.
Returns the deployed contract for the updated contract.
For example, assuming that a contract named Test
is already deployed to the account
and it should be updated with the following contract code:
The contract can be updated as follows:
Updating a contract does not currently change any existing stored data. Only the code of the contract is updated.
Getting a Deployed Contract
A deployed contract can be gotten from an account using the get
function:
Returns the deployed contract for the contract/contract interface with the given name in the account, if any.
Returns nil
if no contract/contract interface with the given name exists in the account.
For example, assuming that a contract named Test
is deployed to an account, the contract can be retrieved as follows:
Borrowing a Deployed Contract
In contrast to a static contract import import T from 0x1
,
which will always perform an import of a type,
contracts can be "borrowed" to effectively perform a dynamic import dependent on a specific execution path.
A reference to a deployed contract contract can obtained using the borrow
function:
This returns a reference to the contract value stored with that name on the account,
if it exists, and if it has the provided type T
.
Returns nil
if no contract/contract interface with the given name exists in the account.
For example, assuming that a contract named Test
which conforms to the TestInterface
interface is deployed to an account, the contract can be retrieved as follows:
Removes the contract/contract interface from the account which has the given name, if any.
Returns the removed deployed contract, if any.
Returns nil
if no contract/contract interface with the given name exist in the account.
For example, assuming that a contract named Test
is deployed to an account, the contract can be removed as follows:
Contract Interfaces
Like composite types, contracts can have interfaces that specify rules about their behavior, their types, and the behavior of their types.
Contract interfaces have to be declared globally. Declarations cannot be nested in other types.
If a contract interface declares a concrete type, implementations of it must also declare the same concrete type conforming to the type requirement.
If a contract interface declares an interface type, the implementing contract
does not have to also define that interface. They can refer to that nested
interface by saying {ContractInterfaceName}.{NestedInterfaceName}