Skip to content

Commit

Permalink
Merge branch 'master' into bastian/sync-stable-cadence
Browse files Browse the repository at this point in the history
  • Loading branch information
@turbolent
turbolent committed May 29, 2023
2 parents 6b69080 + 326312c commit 710a57d
Show file tree
Hide file tree
Showing 206 changed files with 18,822 additions and 22,514 deletions.
11 changes: 3 additions & 8 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
# Documentation

This directory contains the documentation for Cadence.
This directory documention for contributors to/developers of Cadence.

The [`language` directory](https://github.com/onflow/cadence/tree/master/docs/language) contains the Cadence Language Reference.
The contents of this directory are deployed to the [Flow Documentation website](https://docs.onflow.org).
This is done through the `docs` directory in the [`onflow/flow` repository](https://github.com/onflow/flow),
which pulls in the content when it is built.
If you are looking for documentation for Cadence, it can be found at https://developers.flow.com/cadence.

The remaining files in this directory can be considered developer/contributor documentation.

Documentation is written in Markdown or [MDX](https://mdxjs.com/), an extension of Markdown.
The source for the user documentation is at https://github.com/onflow/docs/tree/main/docs/cadence, not in this repository.
381 changes: 2 additions & 379 deletions docs/anti-patterns.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,380 +1,3 @@
---
title: Cadence Anti-Patterns
---
# This document has been moved to a new location:

This is an opinionated list of issues that can be improved if they are found in Cadence code intended for production.

# Security and Robustness

## Avoid using `AuthAccount` as a function parameter

### Problem

Some may choose to authenticate or perform operations for their users by using the users' account addresses.
In order to do this, a commonly seen case would be to pass the user's `AuthAccount` object
as a parameter to a contract function to use for querying the account or storing objects directly.
This is problematic, as the `AuthAccount` object allows access to ALL private areas of the account,
for example, all of the user's storage, authorized keys, etc.,
which provides the opportunity for bad actors to take advantage of.

### Example:

```cadence
...
// BAD CODE
// DO NOT COPY
// Imagine this code is in a contract that uses AuthAccount to authenticate users
// To transfer NFTs
// They could deploy the contract with an Ethereum-style access control list functionality
pub fun transferNFT(id: UInt64, owner: AuthAccount) {
assert(owner(id) == owner.address)
transfer(id)
}
// But they could upgrade the function to have the same signature
// so it looks like it is doing the same thing, but they could also drain a little bit
// of FLOW from the user's vault, a totally separate piece of the account that
// should not be accessible in this function
// BAD
pub fun transferNFT(id: UInt64, owner: AuthAccount) {
assert(owner(id) == owner.address)
transfer(id)
// Sneakily borrow a reference to the user's Flow Token Vault
// and withdraw a bit of FLOW
// BAD
let vaultRef = owner.borrow<&FlowToken.Vault>(/storage/flowTokenVault)!
let stolenTokens <- vaultRef.withdraw(amount: 0.1)
// deposit the stolen funds in the contract owners vault
// BAD
contractVault.deposit(from: <-stolenTokens)
}
...
```

### Solution

Projects should find other ways to authenticate users, such as using resources and capabilities as authentication objects.
They should also expect to perform most storage and linking operations within transaction bodies
rather than inside contract utility functions.

There are some scenarios where using an `AuthAccount` object is necessary, such as a cold storage multi-sig,
but those cases are extremely rare and `AuthAccount` usage should still be avoided unless absolutely necessary.

## Auth references and capabilities should be avoided

### Problem

[Authorized references](language/references) allow downcasting restricted
types to their unrestricted type and should be avoided unless necessary.
The type that is being restricted could expose functionality that was not intended to be exposed.
If the `auth` keyword is used on local variables they will be references.
References are ephemeral and cannot be stored.
This prevents any reference casting to be stored under account storage.
Additionally, if the `auth` keyword is used to store a public capability, serious harm
could happen since the value could be downcasted to a type
that has functionality and values altered.

### Example

A commonly seen pattern in NFT smart contracts is including a public borrow function
that borrows an auth reference to an NFT (eg. [NBA Top Shot](https://github.com/dapperlabs/nba-smart-contracts/blob/95fe72b7e94f43c9eff28412ce3642b69dcd8cd5/contracts/TopShot.cdc#L889-L906)).
This allows anyone to access the stored metadata or extra fields that weren't part
of the NFT standard. While generally safe in most scenarios, not all NFTs are built the same.
Some NFTs may have privileged functions that shouldn't be exposed by this method,
so please be cautious and mindful when imitating NFT projects that use this pattern.

### Another Example

When we create a public capability for our `FungibleToken.Vault` we do not use an auth capability:

```cadence
// GOOD: Create a public capability to the Vault that only exposes
// the balance field through the Balance interface
signer.link<&FlowToken.Vault{FungibleToken.Balance}>(
/public/flowTokenBalance,
target: /storage/flowTokenVault
)
```

If we were to use an authorized type for the capability, like so:

```cadence
// BAD: Create an Authorized public capability to the Vault that only exposes
// the balance field through the Balance interface
// Authorized referenced can be downcasted to their unrestricted types, which is dangerous
signer.link<auth &FlowToken.Vault{FungibleToken.Balance}>(
/public/flowTokenBalance,
target: /storage/flowTokenVault
)
```

Then anyone in the network could take that restricted reference
that is only supposed to expose the balance field and downcast it to expose the withdraw field
and steal all our money!

```cadence
// Exploit of the auth capability to expose withdraw
let balanceRef = getAccount(account)
.getCapability<auth &FlowToken.Vault{FungibleToken.Balance}>(/public/flowTokenBalance)
.borrow()!
let fullVaultRef = balanceRef as! &FlowToken.Vault
// Withdraw the newly exposed funds
let stolenFunds <- fullVaultRef.withdraw(amount: 1000000)
```

## Events from resources may not be unique

### Problem

Public functions in a contract can be called by anyone, e.g. any other contract or any transaction.
If that function creates a resource, and that resource has functions that emit events,
that means any account can create an instance of that resource and emit those events.
If those events are meant to indicate actions taken using a single instance of that resource
(eg. admin object, registry), or instances created through a particular workflow,
it's possible that events from other instances may be mixed in with the ones you're querying for -
making the event log search and management more cumbersome.

### Solution

To fix this, if there should be only a single instance of the resource,
it should be created and `link()`ed to a public path in an admin account's storage
during the contracts's initializer.

# Access Control

## Public functions and fields should be avoided

### Problem

Be sure to keep track of access modifiers when structuring your code, and make public only what should be public.
Accidentally exposed fields can be a security hole.

### Solution

When writing your smart contract, look at every field and function and make sure
that they are all `access(self)`, `access(contract)`, or `access(account)`, unless otherwise needed.

## Capability-Typed public fields are a security hole

This is a specific case of "Public Functions And Fields Should Be Avoided", above.

### Problem

The values of public fields can be copied. Capabilities are value types,
so if they are used as a public field, anyone can copy it from the field
and call the functions that it exposes.
This almost certainly is not what you want if a capability
has been stored as a field on a contract or resource in this way.

### Solution

For public access to a capability, place it in an accounts public area so this expectation is explicit.

## Array or dictionary fields should be private

<Callout type="info">

This anti-pattern has been addressed with [FLIP #703](https://github.com/onflow/flips/blob/main/flips/20211129-cadence-mutability-restrictions.md)

</Callout>

### Problem

This is a specific case of "Public Functions And Fields Should Be Avoided", above.
Public array or dictionary fields are not directly over-writable,
but their members can be accessed and overwritten if the field is public.
This could potentially result in security vulnerabilities for the contract
if these fields are mistakenly made public.

Ex:

```cadence
pub contract Array {
// array is intended to be initialized to something constant
pub let shouldBeConstantArray: [Int]
}
```

Anyone could use a transaction like this to modify it:

```cadence
import Array from 0x01
transaction {
execute {
Array.shouldbeConstantArray[0] = 1000
}
}
```

### Solution

Make sure that any array or dictionary fields in contracts, structs, or resources
are `access(contract)` or `access(self)` unless they need to be intentionally made public.

```cadence
pub contract Array {
// array is inteded to be initialized to something constant
access(self) let shouldBeConstantArray: [Int]
}
```

## Public admin resource creation functions are unsafe

This is a specific case of "Public Functions And Fields Should Be Avoided", above.

### Problem

A public function on a contract that creates a resource can be called by any account.
If that resource provides access to admin functions then the creation function should not be public.

### Solution

To fix this, a single instance of that resource should be created in the contract's `init()` method,
and then a new creation function can be potentially included within the admin resource, if necessary.
The admin resource can then be `link()`ed to a private path in an admin's account storage during the contract's initializer.

### Example

```cadence
// Pseudo-code
// BAD
pub contract Currency {
pub resource Admin {
pub fun mintTokens()
}
// Anyone in the network can call this function
// And use the Admin resource to mint tokens
pub fun createAdmin(): @Admin {
return <-create Admin()
}
}
// This contract makes the admin creation private and in the initializer
// so that only the one who controls the account can mint tokens
// GOOD
pub contract Currency {
pub resource Admin {
pub fun mintTokens()
// Only an admin can create new Admins
pub fun createAdmin(): @Admin {
return <-create Admin()
}
}
init() {
// Create a single admin resource
let firstAdmin <- create Admin()
// Store it in private account storage in `init` so only the admin can use it
self.account.save(<-firstAdmin, to: /storage/currencyAdmin)
}
}
```

## Do not modify smart contract state or emit events in public struct initializers

This is another example of the risks of having publicly accessible parts to your smart contract.

### Problem

Data structure definitions in Cadence currently must be declared as public so that they can be used by anyone.
Structs do not have the same restrictions that resources have on them,
which means that anyone can create a new instance of a struct without going through any authorization.

### Solution

Any contract state-modifying operations related to the creation of structs
should be contained in restricted resources instead of the initializers of structs.

### Example

This used to be a bug in the NBA Top Shot smart contract, so we'll use that as an example.
Before, when it created a new play,
[it would initialize the play record with a struct,](https://github.com/dapperlabs/nba-smart-contracts/blob/55645478594858a6830e4ab095034068ef9753e9/contracts/TopShot.cdc#L155-L158)
which increments the number that tracks the play IDs and emits an event:

```cadence
// Simplified Code
// BAD
//
pub contract TopShot {
// The Record that is used to track every unique play ID
pub var nextPlayID: UInt32
pub struct Play {
pub let playID: UInt32
init() {
self.playID = TopShot.nextPlayID
// Increment the ID so that it isn't used again
TopShot.nextPlayID = TopShot.nextPlayID + 1
emit PlayCreated(id: self.playID, metadata: metadata)
}
}
}
```

This is a risk because anyone can create the `Play` struct as many times as they want,
which could increment the `nextPlayID` field to the max `UInt32` value,
effectively preventing new plays from being created. It also would emit bogus events.

This bug was fixed by
[instead updating the contract state in the admin function](https://github.com/dapperlabs/nba-smart-contracts/blob/master/contracts/TopShot.cdc#L682-L685)
that creates the plays.


```cadence
// Update contract state in admin resource functions
// GOOD
//
pub contract TopShot {
// The Record that is used to track every unique play ID
pub var nextPlayID: UInt32
pub struct Play {
pub let playID: UInt32
init() {
self.playID = TopShot.nextPlayID
}
}
pub resource Admin {
// Protected within the private admin resource
pub fun createPlay() {
// Create the new Play
var newPlay = Play()
// Increment the ID so that it isn't used again
TopShot.nextPlayID = TopShot.nextPlayID + UInt32(1)
emit PlayCreated(id: newPlay.playID, metadata: metadata)
// Store it in the contract storage
TopShot.playDatas[newPlay.playID] = newPlay
}
}
}
```
https://github.com/onflow/docs/tree/main/docs/cadence/anti-patterns.mdx
Loading

0 comments on commit 710a57d

Please sign in to comment.