Cadence

Introduction

Cadence is a resource-oriented programming language specifically designed for smart-contract programming.

Goals

Cadence Language was designed with these three goals in mind:

Safety and security
- Safety is the underlying reliability of any smart contract. Security is the prevention of attacks on the network or smart contracts.
Clarity
- Code needs to be easy to read, and its meaning should be as unambiguous as possible.
Simplicity
- Writing code and creating programs should be as approachable as possible.

Features

Some features of the Cadence programming language are:

type safety and a strong static type system
resource-oriented programming
- resources are types that can only exist in one location at a time and cannot be copied, lost or stolen; Thus there is a concept of scarcity and ownership over these objects
built-in pre-conditions and post-conditions for functions and transactions
capability-based security
- access to objects is restricted only to the owner of the object and those who have a valid reference to it

Terminology

Invalid: The invalid program is not even be allowed to run. The program error is detected and reported statically by the type checker.
Run-time error: The erroneous program can run, but bad behavior will result in the execution of the program being aborted.

Account

Accounts are address on the flow network, e.g. 0xf233dcee88fe0abe. Every account can be accessed through two types: PublicAccount and AuthAccount, each corresponding to a level of accessibility.

Cadence transactions consist of four optional phases: prepare, precondition, execution and postconditions. Phases can be omitted, but, if present, they must appear in that order. Each account signing the transaction appears as an argument in the prepare() phase. These signers appear as arguments of AuthAccount type, and their number must match the number of signers of the transaction. The prepare phase is the only place where direct access to the signing accounts is possible.

transaction {
    prepare(account: AuthAccount, account2: AuthAccount, (...), accountN: AuthAccount) {
        // ...
    }
}

PublicAccount

PublicAccount represents the publicly available information about an account. This information can be retrieved about any account using the getAccount() function.

struct PublicAccount {

    let address: Address
    // The FLOW balance of the default vault of this account
    let balance: UFix64
    // The FLOW balance of the default vault of this account that is available to be moved
    let availableBalance: UFix64
    // Amount of storage used by the account, in bytes
    let storageUsed: UInt64
    // storage capacity of the account, in bytes
    let storageCapacity: UInt64

    // Contracts deployed to the account
    let contracts: PublicAccount.Contracts

    // Keys assigned to the account
    let keys: PublicAccount.Keys

    // Storage operations

    fun getCapability<T>(_ path: PublicPath): Capability<T>
    fun getLinkTarget(_ path: CapabilityPath): Path?

    struct Contracts {

        let names: [String]

        fun get(name: String): DeployedContract?
    }

    struct Keys {
        // Returns the key at the given index, if it exists.
        // Revoked keys are always returned, but they have `isRevoked` field set to true.
        fun get(keyIndex: Int): AccountKey?
    }
}

AuthAccount

On the other hand, AuthAccount represents an authorized account. Authorized accounts can only be encountered in the prepare function of a signed transaction.

struct AuthAccount {

    let address: Address
    // The FLOW balance of the default vault of this account
    let balance: UFix64
    // The FLOW balance of the default vault of this account that is available to be moved
    let availableBalance: UFix64
    // Amount of storage used by the account, in bytes
    let storageUsed: UInt64
    // storage capacity of the account, in bytes
    let storageCapacity: UInt64

    // Contracts deployed to the account

    let contracts: AuthAccount.Contracts

    // Keys assigned to the account

    let keys: AuthAccount.Keys

    // Key management

    // Adds a public key to the account.
    // The public key must be encoded together with their signature algorithm, hashing algorithm and weight.
    // This method is currently deprecated and is available only for the backward compatibility.
    // `keys.add` method can be use instead.
    fun addPublicKey(_ publicKey: [UInt8])

    // Revokes the key at the given index.
    // This method is currently deprecated and is available only for the backward compatibility.
    // `keys.revoke` method can be use instead.
    fun removePublicKey(_ index: Int)

    // Account storage API (see the section below for documentation)

    fun save<T>(_ value: T, to: StoragePath)
    fun load<T>(from: StoragePath): T?
    fun copy<T: AnyStruct>(from: StoragePath): T?

    fun borrow<T: &Any>(from: StoragePath): T?

    fun link<T: &Any>(_ newCapabilityPath: CapabilityPath, target: Path): Capability<T>?
    fun getCapability<T>(_ path: CapabilityPath): Capability<T>
    fun getLinkTarget(_ path: CapabilityPath): Path?
    fun unlink(_ path: CapabilityPath)

    struct Contracts {

        // The names of each contract deployed to the account
        let names: [String]

        fun add(
            name: String,
            code: [UInt8],
            ... contractInitializerArguments
        ): DeployedContract

        fun update__experimental(name: String, code: [UInt8]): DeployedContract

        fun get(name: String): DeployedContract?

        fun remove(name: String): DeployedContract?
    }

    struct Keys {
        // Adds a new key with the given hashing algorithm and a weight, and returns the added key.
        fun add(
            publicKey: PublicKey,
            hashAlgorithm: HashAlgorithm,
            weight: UFix64
        ): AccountKey

        // Returns the key at the given index, if it exists, or nil otherwise.
        // Revoked keys are always returned, but they have `isRevoked` field set to true.
        fun get(keyIndex: Int): AccountKey?

        // Marks the key at the given index revoked, but does not delete it.
        // Returns the revoked key if it exists, or nil otherwise.
        fun revoke(keyIndex: Int): AccountKey?
    }
}

struct DeployedContract {
    let name: String
    let code: [UInt8]
}

Account Storage

Each account has storage, and this is where resources and structs can be persisted. Authorized accounts have full access to the account storage.

Objects in storage are stored under paths. Each storage path location corresponds to a single register. Paths correspond to the Key part of the register ID. Paths have a format of /<domain>/<identifier>. There are three valid domains — storage, public and private. Objects in storage are always stored in the storage domain — meaning this is where resources and any other data is kept. The public domain allows the account to let other accounts access the objects, links to storage, inside it.

Resources

Resources are types that can exist only in one memory location at a time. At the end of a function which has resources in scope, resources must either be moved or destroyed.

After it was destroyed, the resource can no longer be used. Moving a resource means either assigning it to a different constant or a variable, passing it as an argument to another function, or returning it from a function. After the resource was moved — e.g. assigned to a const, the previous reference to the resource is invalid and cannot be used anymore.

To make the resource behavior clear and explicit, the prefix @ must be used in all type annotations dealing with resources, and the resource movement is denoted with the move operator — <-.

// Resource definition.
pub resource SomeResource {

    // The resource has a single field &#0151 the `value` integer.
    pub var value: Int

    // Define the resource initializer
    init(value: Int) {
        self.value = value
    }
}

// Resource is created using the `create` keyword.
// Note that the const `a` has type of `@SomeResource`.
let a: @SomeResurce <- create SomeResource(value: 2)

// Resource is moved from const a to const b.
// `a` can no longer be used to access the resource.
let b <- a

// Resource is destroyed.
destroy b

// Neither `a` or `b` can now be used to access the resource as it was destroyed.

When a resource is returned from a function, the function caller has the responsibility to use the returned resource.

// This function is invalid as it does not use the resource.
pub fun invalid_use(r: @SomeResource) {
}

// This function uses the resource by moving it to a new const.
// This new const is used by being returned from the function.
pub fun use(res: @SomeResource): @SomeResource {
    let moved <- res
    // Note that the return call still uses the `move` operator.
    return <-moved
}

// Create a new resource.
let a: @SomeResource <- create SomeResource(value: 3)

// Move the function return value to a new const.
// The const `a` can no longer be used to access the resource.
let result <- use(res: <- a)

// Destroy the resource.
destroy result

Resource can have a destructor, which is called when the resource is destroyed.

pub resource SomeResource {

    destroy() {
        // Some logic here, e.g. decrement the variable indicating the number of resources in existence.
    }
}

Since the resource variables cannot be assigned to, there are two options to replace the values of resource variables — the swap operator (<->) and the shift operator (<- target <-)

pub resource SomeResource{}

var x <- create SomeResource()
var y <- create SomeResource()

// Swap the resources.
x <-> y

// Alternatively, use the shift operator.
// The shift operator moves the resource from `x` to `oldX`.
// At the same time, `x` receives the value of the new resource.
let oldX <- x <- create SomeResource()

// oldX still needs to be used.

Resources have an implicit unique identifier in the form of the predeclared public field uuid of type UInt64. This field is incremented on each resource creation, and can never be the same for two resources, even if some of them were destroyed.

Reference

Comments

Single-line comments in Cadence use //, multi-line comments use /* */.

// This is a comment on a single line.

/* This is a comment which
spans multiple lines. */

Documentation Comments

Cadence has a specific way to create documentation comments. For single-line comments use ///, for multi-line comments use the syntax /** **/.

/// This is a single-line documentation comment
/// You can keep them going.

/**
    Multi-line
    Documentation Comment
**/

Names

Names can have letters, underscores and numbers, but can only start with any letter or underscore. By convention, variables, constants, and functions have lowercase names; and types have title-case names.

// Valid: title-case
//
PersonID

// Valid: with underscore
//
token_name

// Valid: leading underscore and characters
//
_balance

// Valid: leading underscore and numbers
_8264

// Valid: characters and number
//
account2

// Invalid: leading number
//
1something

// Invalid: invalid character #
_#1

// Invalid: various invalid characters
//
!@#$%^&*

Types

There are several built-in types for Cadence.

Integer

Cadence supports the following integer types: Int, Int8, Int16, Int32, Int64, Int128, Int256, UInt, UInt8, UInt16, UInt32, UInt64, UInt128, UInt256, Word8, Word16, Word32, Word64.