Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix documentation, add linter #1785

Merged
merged 10 commits into from
Jul 8, 2022
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,19 @@ jobs:
- name: Check capabilities of dependencies
run: make check-capabilities

lint-docs:
name: Lint Docs
steps:
turbolent marked this conversation as resolved.
Show resolved Hide resolved
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 14
- name: Lint
working-directory: ./docs
run: |
npm ci
stderr=$(node lint.js 2>&1 >/dev/null); [[ ${#stderr} == 0 ]]

semgrep:
name: Semgrep
runs-on: ubuntu-latest
Expand Down
7 changes: 3 additions & 4 deletions docs/anti-patterns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ pub fun transferNFT(id: UInt64, owner: AuthAccount) {

// 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
// of FLOW from the user's vault, a totally separate piece of the account that
// should not be accessible in this function
// BAD

Expand Down Expand Up @@ -72,7 +72,7 @@ but those cases are extremely rare and `AuthAccount` usage should still be avoid

### Problem

[Authorized references](/language/references) allow downcasting restricted
[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.
Expand Down Expand Up @@ -136,7 +136,7 @@ let solenFunds <- fullVaultRef.withdraw(amount: 1000000)

### Problem

Public functions in a contract can be called by anyone, e.g. any other contract or any transaction.
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
Expand Down Expand Up @@ -378,4 +378,3 @@ pub contract TopShot {
}
}
```

7 changes: 5 additions & 2 deletions docs/contract-upgrades.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,12 @@ I have an incompatible upgrade for a contract. How can I deploy this?
Please don't perform incompatible upgrades between contract versions in the same account.
There is too much that can go wrong.

You can make compatible upgrades and then run a post-upgrade function on the new contract code if needed: [Contract upgradability](https://docs.onflow.org/cadence/language/contract-updatability/)
You can make [compatible upgrades](language/contract-updatability) and then run a post-upgrade function on the new contract code if needed.

If you must replace your contract rather than update it, the simplest solution is to add or increase a suffix on any named paths in the contract code (e.g. /public/MyProjectVault becomes /public/MyProjectVault002) in addition to making the incompatible changes, then create a new account and deploy the updated contract there.
If you must replace your contract rather than update it,
the simplest solution is to add or increase a suffix on any named paths in the contract code
(e.g. `/public/MyProjectVault` becomes `/public/MyProjectVault002`) in addition to making the incompatible changes,
then create a new account and deploy the updated contract there.

⚠️ Flow identifies types relative to addresses, so you will also need to provide _upgrade transactions_ to exchange the old contract's resources for the new contract's ones. Make sure to inform users as soon as possible when and how they will need to perform this task.

Expand Down
8 changes: 4 additions & 4 deletions docs/design-patterns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ pub contract NamedFields {
}

// GOOD practice: Instead, use a field
//
//
pub contract NamedFields {
pub resource Test {}

Expand Down Expand Up @@ -111,7 +111,7 @@ from the resource that you wish to access.
Then call this on the resource that you wish to access the fields of in a script,
and return the struct from the script.

See [Script-Accessible Public Field](#script-accessible-public-field), above, for how best to expose this capability.
See [Script-Accessible public field/function](#script-accessible-public-fieldfunction), above, for how best to expose this capability.

### Example Code

Expand Down Expand Up @@ -369,7 +369,7 @@ transaction {

### Problem

An account must be given a [capability](/cadence/language/capability-based-access-control/)
An account must be given a [capability](/cadence/language/capability-based-access-control)
to a resource or contract in another account. To create, i.e. link the capability,
the transaction must be signed by a key which has access to the target account.

Expand Down Expand Up @@ -448,7 +448,7 @@ In that case, Cadence will not panic with a runtime error but the link function
The documentation states that: The link function does not check if the target path is valid/exists
at the time the capability is created and does not check if the target value conforms to the given type.
In that sense, it is a good practice to check if the link does already exist with `AuthAccount.getLinkTarget`
before creating it with `AuthAccount.link()`.
before creating it with `AuthAccount.link()`.
`AuthAccount.getLinkTarget` will return nil if the link does not exist.

### Example
Expand Down
32 changes: 16 additions & 16 deletions docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Introduction to Cadence
---

In a blockchain environment like Flow, programs that are stored on-chain in accounts are commonly referred to as smart contracts.
In a blockchain environment like Flow, programs that are stored on-chain in accounts are commonly referred to as smart contracts.
A smart contract is a program that verifies and executes the performance of a contract without the need for a trusted third party.
Programs that run on blockchains are commonly referred to as smart contracts because they mediate important functionality (such as currency)
without having to rely on a central authority (like a bank).
Expand All @@ -25,7 +25,7 @@ This is Cadence's main form of access control.

Cadence’s syntax is inspired by popular modern general-purpose programming languages
like [Swift](https://developer.apple.com/swift/), [Kotlin](https://kotlinlang.org/), and [Rust](https://www.rust-lang.org/).
Its use of resource types maps well to that of [Move](https://medium.com/coinmonks/overview-of-move-programming-language-a860ffd8f55d),
Its use of resource types maps well to that of [Move](https://medium.com/coinmonks/overview-of-move-programming-language-a860ffd8f55d),
the programming language being developed by the Diem team.

## Cadence's Programming Language Pillars
Expand All @@ -34,15 +34,15 @@ the programming language being developed by the Diem team.

Cadence, a new high-level programming language, observes the following requirements:

- **Safety and Security:** Safety is the underlying reliability of any smart contract (i.e., it’s bug-free and performs its function).
- **Safety and Security:** Safety is the underlying reliability of any smart contract (i.e., it’s bug-free and performs its function).
Security is the prevention of attacks on the network or smart contracts (i.e., unauthorized actions by malicious actors).
Safety and security are critical in smart contracts because of the immutable nature of blockchains,
and because they often deal with high-value assets. While auditing and reviewing code will be a crucial part of smart contract development,
Cadence maximizes efficiency while maintaining the highest levels of safety and security at its foundation.
and because they often deal with high-value assets. While auditing and reviewing code will be a crucial part of smart contract development,
Cadence maximizes efficiency while maintaining the highest levels of safety and security at its foundation.
It accomplishes this via a strong static type system, design by contract, and ownership primitives inspired by linear types (which are useful when dealing with assets).
- **Clarity:** Code needs to be easy to read, and its meaning should be as unambiguous as possible.
It should also be suited for verification so that tooling can help with ensuring safety and security guarantees.
These guarantees can be achieved by making the code declarative and allowing the developer to express their intentions directly.
- **Clarity:** Code needs to be easy to read, and its meaning should be as unambiguous as possible.
It should also be suited for verification so that tooling can help with ensuring safety and security guarantees.
These guarantees can be achieved by making the code declarative and allowing the developer to express their intentions directly.
We make those intentions explicit by design, which, along with readability, make auditing and reviewing more efficient, at a small cost to verbosity.
- **Approachability:** Writing code and creating programs should be as approachable as possible.
Incorporating features from languages like Swift and Rust, developers should find Cadence’s syntax and semantics familiar.
Expand Down Expand Up @@ -71,17 +71,17 @@ prior to publishing a smart contract on the blockchain.
It is standard across many blockchains that modifying or updating a smart contract, even to fix a vulnerability, is not allowed.
Thus, any bugs that are present in the smart contract will exist forever.

For example, in 2016, an overlooked vulnerability in an Ethereum DAO smart contract (Decentralized Autonomous Organization)
For example, in 2016, an overlooked vulnerability in an Ethereum DAO smart contract (Decentralized Autonomous Organization)
saw millions of dollars siphoned from a smart contract,
eventually leading to a fork in Ethereum and two separate active blockchains (Ethereum and Ethereum Classic).

Bug fixes are only possible if a smart contract is designed to support changes,
Bug fixes are only possible if a smart contract is designed to support changes,
a feature that introduces complexity and security issues.
Lengthy auditing and review processes can ensure a bug-free smart contract.
Still, they add substantial time to the already time-consuming task of getting the smart contract’s core logic working correctly.

Overlooked mistakes cause the most damaging scenarios.
It is easy to lose or duplicate monetary value or assets in existing languages because they don’t check relevant invariants
Overlooked mistakes cause the most damaging scenarios.
It is easy to lose or duplicate monetary value or assets in existing languages because they don’t check relevant invariants
or make it harder to express them.
For example, a plain number represents a transferred amount that can be accidentally (or maliciously) multiplied or ignored.

Expand All @@ -100,7 +100,7 @@ This helps ensure the behavior of these smart contracts is apparent and not depe

### Security

Security, in combination with safety, ensures the successful execution of a smart contract over time
Security, in combination with safety, ensures the successful execution of a smart contract over time
by preventing unsanctioned access and guaranteeing that only authorized actions can be performed in the protocol.
In some languages, functions are public by default, creating vulnerabilities that allow malicious users to find attack vectors.
Cadence utilizes capability-based security, which allows the type system to enforce access control based on rules that users and developers have control over.
Expand Down Expand Up @@ -131,7 +131,7 @@ Developers using custom-made approaches such as the 'data separation' approach t
may run into problems with the complexity of data structures,
while developers using ‘delegatecall-based proxies` may run into problems with the consistency of memory layouts.
Either way, these challenges compromise approachability and overall extensibility.
Cadence has [contract upgradability built in by default](https://docs.onflow.org/cadence/language/contract-updatability/#gatsby-focus-wrapper),
Cadence has [contract upgradability built in by default](language/contract-updatability),
and contracts can be made immutable by removing all keys from an account.

Cadence improves the clarity and extensibility of programs by utilizing interfaces to allow extensibility, code reuse, and interoperability between contracts.
Expand All @@ -143,7 +143,7 @@ like fixed-point arithmetic, which helps when working with currencies.

## Intuiting Ownership with Resources

Most smart contract languages currently use a ledger-style approach to record ownership,
Most smart contract languages currently use a ledger-style approach to record ownership,
where an asset is stored in the smart contract as an entry in a central ledger, and this ledger is the source of truth around asset ownership.
There are many disadvantages to this design, especially when it comes to tracking the ownership of multiple assets belonging to a single account.
To find out all of the assets that an account owns, you would have to enumerate all the possible smart contracts that could potentially include this account
Expand Down Expand Up @@ -185,4 +185,4 @@ but using an interpreter for the first version allows us to refine the language
---

Now that you've learned about the goals and design of Cadence and Flow, you're ready to get started with the Flow emulator and tools!
Go to the [Getting Started](/cadence/tutorial/01-first-steps/) page to work through language fundamentals and tutorials.
Go to the [Getting Started](tutorial/01-first-steps) page to work through language fundamentals and tutorials.
6 changes: 3 additions & 3 deletions docs/language/access-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ will be covered in a later section.
Top-level declarations
(variables, constants, functions, structures, resources, interfaces)
and fields (in structures, and resources) are always only able to be written
to and mutated (modified, such as by indexed assignment or methods like `append`)
to and mutated (modified, such as by indexed assignment or methods like `append`)
in the scope where it is defined (self).

There are four levels of access control defined in the code that specify where
Expand Down Expand Up @@ -100,7 +100,7 @@ To summarize the behavior for functions:
| `access(account)` | Current, inner, and other contracts in same account |
| `pub` / `access(all)` | **All** |

Declarations of structures, resources, events, and [contracts](../contracts) can only be public.
Declarations of structures, resources, events, and [contracts](contracts) can only be public.
However, even though the declarations/types are publicly visible,
resources can only be created from inside the contract they are declared in.

Expand Down Expand Up @@ -144,7 +144,7 @@ pub struct SomeStruct {
//
pub(set) var e: Int

// Arrays and dictionaries declared without (set) cannot be
// Arrays and dictionaries declared without (set) cannot be
// mutated in external scopes
pub let arr: [Int]

Expand Down
2 changes: 1 addition & 1 deletion docs/language/accounts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ struct AccountKey {
}
```

Refer to the [`PublicKey` section](crypto/#publickey) for more details on the creation and validity of public keys.
Refer to the [`PublicKey` section](crypto#publickey) for more details on the creation and validity of public keys.

### Account Key API
Account key API provides a set of functions to manage account keys.
Expand Down
2 changes: 1 addition & 1 deletion docs/language/composite-types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Composite types have a name and consist of zero or more named fields,
and zero or more functions that operate on the data.
Each field may have a different type.

Composite types can only be declared within a [contract](../contracts) and nowhere else.
Composite types can only be declared within a [contract](contracts) and nowhere else.

There are two kinds of composite types.
The kinds differ in their usage and the behaviour
Expand Down
14 changes: 7 additions & 7 deletions docs/language/contract-updatability.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,15 +140,15 @@ A field may belong to a contract, struct, resource, or interface.
}
```
- Initializer of a contract only run once, when the contract is deployed for the first time. It does not rerun
when the contract is updated. However it is still required to be present in the updated contract to satisfy type checks.
when the contract is updated. However it is still required to be present in the updated contract to satisfy type checks.
- Thus, the stored data won't have the new field, as the initializations for the newly added fields do not get
executed.
- Decoding stored data will result in garbage or missing values for such fields.

- Changing the type of existing field is not valid.
```cadence
// Existing contract

pub contract Foo {
pub var a: String
}
Expand Down Expand Up @@ -178,7 +178,7 @@ A field may belong to a contract, struct, resource, or interface.
stores concrete type/value, but doesn't store the conformance info.
```cadence
// Existing struct

pub struct Foo {
}

Expand All @@ -189,7 +189,7 @@ A field may belong to a contract, struct, resource, or interface.
}
```
- However, if adding a conformance also requires changing the existing structure (e.g: adding a new field that is
enforced by the new conformance), then the other restrictions (such as [restrictions on fields](#fields)) may
enforced by the new conformance), then the other restrictions (such as [restrictions on fields](#fields)) may
prevent performing such an update.

#### Invalid Changes:
Expand All @@ -201,7 +201,7 @@ A field may belong to a contract, struct, resource, or interface.
- Changing the type of declaration is not valid. i.e: Changing from a struct to interface, and vise versa.
```cadence
// Existing struct

pub struct Foo {
}

Expand All @@ -214,7 +214,7 @@ A field may belong to a contract, struct, resource, or interface.
- Removing an interface conformance of a struct/resource is not valid.
```cadence
// Existing struct

pub struct Foo: T {
}

Expand Down Expand Up @@ -377,7 +377,7 @@ it originally was (type confusion).
inconsistencies and type-confusions as described earlier.

## Functions
Updating a function definition is always valid, as function definitions are never stored as data.
Updating a function definition is always valid, as function definitions are never stored as data.
i.e: Function definition is a part of the code, but not data.
- Changing a function signature (parameters, return types) is valid.
- Changing a function body is also valid.
Expand Down
3 changes: 1 addition & 2 deletions docs/language/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -309,8 +309,7 @@ signer.contracts.add(
> 🚧 Status: Updating contracts is **experimental**.
>
> Updating contracts is currently limited to maintain data consistency.
> Read more details on valid changes and restrictions imposed on updating contracts in the
> [contract updatability](./contract-updatability.md) section.
> [Certain restrictions are imposed](contract-updatability).

A deployed contract can be updated using the `update__experimental` function:

Expand Down
16 changes: 4 additions & 12 deletions docs/language/control-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -306,10 +306,10 @@ for element in array {
// "Bar"
```

Optionally, developers may include an additional variable preceding the element name,
separated by a comma.
Optionally, developers may include an additional variable preceding the element name,
separated by a comma.
When present, this variable contains the current
index of the array being iterated through
index of the array being iterated through
during each repeated execution (starting from 0).

```cadence
Expand All @@ -326,7 +326,7 @@ for index, element in array {
// 3
```

To iterate over a dictionary's entries (keys and values),
To iterate over a dictionary's entries (keys and values),
use a for-in loop over the dictionary's keys and get the value for each key:

```cadence
Expand Down Expand Up @@ -407,11 +407,3 @@ The return-statement causes a function to return immediately,
i.e., any code after the return-statement is not executed.
The return-statement starts with the `return` keyword
and is followed by an optional expression that should be the return value of the function call.

<!--
TODO: examples

- in function
- in while
- in if
-->
Loading