clean up core contracts pages, add CTF addresses, and add events docs

onflow · May 16, 2024 · 59ed6d5 · 59ed6d5
1 parent ad3f333
commit 59ed6d5
Show file tree

Hide file tree

Showing 15 changed files with 451 additions and 409 deletions.
diff --git a/docs/build/core-contracts/02-fungible-token.md b/docs/build/core-contracts/02-fungible-token.md
@@ -1,11 +1,15 @@
 ---
 title: Fungible Token Contract
-sidebar_position: 3
+sidebar_position: 2
 sidebar_label: Fungible Token
 ---
 
 The `FungibleToken` contract implements the Fungible Token Standard. It is the second contract ever deployed on Flow.
 
+* [Basic Fungible Token Tutorial](https://cadence-lang.org/docs/1.0/tutorial/fungible-tokens)
+* [Fungible Token Guide](../guides/fungible-token.md)
+* [Fungible Token Standard Repo](https://github.com/onflow/flow-ft)
+
 The `FungibleTokenMetadataViews` and `FungibleTokenSwitchboard` contracts
 are also deployed to the same account as `FungibleToken`.
 
@@ -14,7 +18,127 @@ Source: [FungibleToken.cdc](https://github.com/onflow/flow-ft/blob/master/contra
 | Network           | Contract Address     |
 | ----------------- | -------------------- |
 | Emulator          | `0xee82856bf20e2aa6` |
+| Cadence Testing Framework | `0x0000000000000002` |
 | PreviewNet        | `0xa0225e7000ac82a9` |
-| Testnet/Crescendo | `0x9a0766d93b6608b7` |
+| Testnet           | `0x9a0766d93b6608b7` |
 | Mainnet           | `0xf233dcee88fe0abe` |
 
+# Transactions
+
+All `FungibleToken` projects are encouraged to use
+the generic token transactions and scripts in the `flow-ft` [repo](https://github.com/onflow/flow-ft/tree/master/transactions).
+They can be used for any token that implements the fungible token standard properly
+without changing any code besides import addresses on different networks.
+
+# Events
+
+Events emitted from all contracts follow a standard format:
+
+```
+A.{contract address}.{contract name}.{event name}
+```
+
+The components of the format are:
+- `contract address` - the address of the account the contract has been deployed to
+- `contract name` - the name of the contract in the source code
+- `event name` - the name of the event as declared in the source code
+
+## FungibleToken Events
+
+Contracts that implement the Fungible Token standard get access
+to standard events that are emitted every time a relevant action occurs,
+like depositing and withdrawing tokens.
+
+This means that projects do not have to implement their own custom events
+unless the standard events do not satisfy requirements they have for events.
+
+The `FungibleToken` events will have the following format:
+```
+A.{contract address}.FungibleToken.Deposited
+A.{contract address}.FungibleToken.Withdrawn
+```
+Where the `contract address` is the `FungibleToken` address on the network being queried.
+The addresses on the various networks are shown above.
+
+### FungibleToken.Deposited
+
+```cadence
+access(all) event Deposited (
+    type: String, 
+    amount: UFix64,
+    to: Address?,
+    toUUID: UInt64,
+    depositedUUID: UInt64,
+    balanceAfter: UFix64
+)
+```
+
+Whenever `deposit()` is called on a resource type that implements
+`FungibleToken.Vault`, the `FungibleToken.Deposited` event is emitted
+with the following arguments:
+
+* `type: String`: The type identifier of the token being deposited.
+    * Example: `A.4445e7ad11568276.FlowToken.Vault`
+* `amount: UFix64`: The amount of tokens that were deposited.
+    * Example: `0.00017485`
+* `to: Address?`: The address of the account that owns the Vault that received
+                  the tokens. If the vault is not stored in an account, `to` will be `nil`.
+    * Example: `0x4445e7ad11568276`
+* `toUUID: UInt64`: The UUID of the Vault that received the tokens.
+    * Example: `177021372071991`
+* `depositedUUID`: The UUID of the Vault that was deposited (and therefore destroyed).
+    * Example: `177021372071991`
+* `balanceAfter: UFix64`: The balance of the Vault that received the tokens after the deposit happened.
+    * Example: `1.00047545`
+
+### FungibleToken.Withdrawn
+
+```cadence
+access(all) event Withdrawn (
+    type: String, 
+    amount: UFix64,
+    from: Address?,
+    fromUUID: UInt64,
+    withdrawnUUID: UInt64,
+    balanceAfter: UFix64
+)
+```
+
+Whenever `withdraw()` is called on a resource type that implements
+`FungibleToken.Vault`, the `FungibleToken.Withdrawn` event is emitted
+with the following arguments:
+
+* `type: String`: The type identifier of the token being withdrawn.
+    * Example: `A.4445e7ad11568276.FlowToken.Vault`
+* `amount: UFix64`: The amount of tokens that were withdrawn.
+    * Example: `0.00017485`
+* `from: Address?`: The address of the account that owns the Vault that the tokens
+    were withdrawn from. If the vault is not stored in an account, `to` will be `nil`.
+    * Example: `0x4445e7ad11568276`
+* `fromUUID: UInt64`: The UUID of the Vault that the tokens were withdrawn from.
+    * Example: `177021372071991`
+* `withdrawnUUID`: The UUID of the Vault that was withdrawn.
+    * Example: `177021372071991`
+* `balanceAfter: UFix64`: The balance of the Vault that the tokens
+    were withdrawn from after the withdrawal.
+    * Example: `1.00047545`
+
+### FungibleToken.Burned
+
+```cadence
+access(all) event Burned (
+    type: String,
+    amount: UFix64,
+    fromUUID: UInt64
+)
+```
+
+Whenever a fungible token that implements `FungibleToken.Vault` is burned
+via the `Burner.burn()` method, this event is emitted with the following arguments:
+
+* `type: String`: The type identifier of the token that was burnt.
+    * Example: `A.4445e7ad11568276.FlowToken.Vault`
+* `amount: UFix64`: The amount of tokens that were burnt.
+    * Example: `0.00017485`
+* `fromUUID: UInt64`: The UUID of the Vault that was burnt.
+    * Example: `177021372071991`
diff --git a/docs/build/core-contracts/03-flow-token.md b/docs/build/core-contracts/03-flow-token.md
@@ -1,5 +1,6 @@
 ---
 title: Flow Token Contract
+sidebar_position: 3
 sidebar_label: Flow Token
 ---
 
@@ -10,18 +11,17 @@ Source: [FlowToken.cdc](https://github.com/onflow/flow-core-contracts/blob/maste
 | Network           | Contract Address     |
 | ----------------- | -------------------- |
 | Emulator          | `0x0ae53cb6e3f42a79` |
+| Cadence Testing Framework | `0x0000000000000003` |
 | Previewnet        | `0x4445e7ad11568276` |
-| Testnet/Crescendo | `0x7e60df042a9c0868` |
+| Testnet | `0x7e60df042a9c0868` |
 | Mainnet           | `0x1654653399040a61` |
 
 # Transactions
 
-| ID          | Name                     | Source                                                                                                                                        |
-| ----------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`FT.01`** | Transfer FLOW            | [flowToken/transfer_tokens.cdc](https://github.com/onflow/flow-core-contracts/blob/master/transactions/flowToken/transfer_tokens.cdc)         |
-| **`FT.02`** | Get an account's balance | [flowToken/scripts/get_balance.cdc](https://github.com/onflow/flow-core-contracts/blob/master/transactions/flowToken/scripts/get_balance.cdc) |
-| **`FT.03`** | Get total supply         | [flowToken/scripts/get_supply.cdc](https://github.com/onflow/flow-core-contracts/blob/master/transactions/flowToken/scripts/get_supply.cdc)   |
+Transactions and scripts for `FlowToken` are in the `flow-core-contracts` [repo](https://github.com/onflow/flow-core-contracts/tree/master/transactions/flowToken).
 
+As mentioned in the `FungibleToken` page, developers are encouraged to use
+the generic token transactions in the `flow-ft` [repo](https://github.com/onflow/flow-ft/tree/master/transactions) instead.
 
 # Events
 

diff --git a/docs/build/core-contracts/04-service-account.md b/docs/build/core-contracts/04-service-account.md
@@ -1,32 +1,91 @@
 ---
 title: Service Account Contracts
+sidebar_position: 4
 sidebar_label: Service Account
 ---
 
 The service account is the account that manages the core protocol requirements of Flow.
-There are three contracts deployed to the service account:
 
-- `FlowServiceAccount` tracks transaction fees, deployment permissions, and provides 
+| Network           | Contract Address     |
+| ----------------- | -------------------- |
+| Emulator          | `0xf8d6e0586b0a20c7` |
+| Cadence Testing Framework | `0x0000000000000001` |
+| PreviewNet        | `0xb6763b4399a888c8` |
+| Testnet | `0x8c5303eaa26202d6` |
+| Mainnet           | `0xe467b9dd11fa00df` |
+
+Here are three important contracts deployed to the service account:
+
+# FlowServiceAccount
+
+`FlowServiceAccount` tracks transaction fees, deployment permissions, and provides 
 some convenience methods for Flow Token operations.
 
 Source: [FlowServiceAccount.cdc](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowServiceAccount.cdc)
 
+## Events
+
+Important events from `FlowServiceAccount` are:
+
+```cadence
+access(all) event TransactionFeeUpdated(newFee: UFix64)
+access(all) event AccountCreationFeeUpdated(newFee: UFix64)
+```
+
+# RandomBeaconHistory
+
 - `RandomBeaconHistory` stores the history of random sources generated by
 the Flow network. The defined Heartbeat resource is
 updated by the Flow Service Account at the end of every block
 with that block's source of randomness.
 
 Source: [RandomBeaconHistory.cdc](https://github.com/onflow/flow-core-contracts/blob/master/contracts/RandomBeaconHistory.cdc)
 
+## Events
+
+Important events from `RandomBeaconHistory` are:
+
+```cadence
+// Event emitted when missing SoRs from past heartbeats are detected and will be backfilled:
+//  - `blockHeight` is the height where the gap is detected
+//  - `gapStartHeight` is the height of the first missing entry detected
+access(all) event RandomHistoryMissing(blockHeight: UInt64, gapStartHeight: UInt64)
+
+// Event emitted when missing SoRs are backfilled on the current heartbeat:
+//  - `blockHeight` is the height where the backfill happened, it also defines the SoR used to backfill
+//  - `gapStartHeight` is the height of the first backfilled entry
+//  - `count` is the number of backfilled entries
+// Note that in very rare cases, the backfilled gap may not be contiguous. This event does not
+// fully define the backfilled entries in this case.
+access(all) event RandomHistoryBackfilled(blockHeight: UInt64, gapStartHeight: UInt64, count: UInt64)
+```
+
+# NodeVersionBeacon
+
 - `NodeVersionBeacon` holds the past
 and future protocol versions that should be used
 to execute/handle blocks at a given block height.
 
 Source: [NodeVersionBeacon.cdc](https://github.com/onflow/flow-core-contracts/blob/master/contracts/NodeVersionBeacon.cdc)
 
-| Network           | Contract Address     |
-| ----------------- | -------------------- |
-| Emulator          | `0xf8d6e0586b0a20c7` |
-| PreviewNet        | `0xb6763b4399a888c8` |
-| Testnet/Crescendo | `0x8c5303eaa26202d6` |
-| Mainnet           | `0xe467b9dd11fa00df` |
+## Events
+
+Important events from `NodeVersionBeacon` are:
+
+```cadence
+/// Event emitted when the version table is updated.
+/// It contains the current version and all the upcoming versions
+/// sorted by block height.
+/// The sequence increases by one each time an event is emitted.
+/// It can be used to verify no events were missed.
+access(all) event VersionBeacon(
+    versionBoundaries: [VersionBoundary],
+    sequence: UInt64
+)
+
+/// Event emitted any time the version boundary freeze period is updated.
+/// freeze period is measured in blocks (from the current block).
+access(all) event NodeVersionBoundaryFreezePeriodChanged(freezePeriod: UInt64)
+```
+
+
diff --git a/docs/build/core-contracts/05-flow-fees.md b/docs/build/core-contracts/05-flow-fees.md
@@ -1,19 +1,42 @@
 ---
 title: Flow Fees Contract
+sidebar_position: 5
 sidebar_label: Flow Fees
 ---
 
+# FlowFees
+
 The `FlowFees` contract is where all the collected flow fees are gathered.
 
 Source: [FlowFees.cdc](https://github.com/onflow/flow-core-contracts/blob/master/contracts/FlowFees.cdc)
 
 | Network           | Contract Address     |
 | ----------------- | -------------------- |
 | Emulator          | `0xe5a8b7f23e8b548f` |
+| Cadence Testing Framework | `0x0000000000000004` |
 | PreviewNet        | `0xab086ce9cc29fc80` |
-| Testnet/Crescendo | `0x912d5440f7e3769e` |
+| Testnet | `0x912d5440f7e3769e` |
 | Mainnet           | `0xf919ee77447b7497` |
 
+## Events
+
+Important events for `FlowFees` are:
+
+```cadence
+// Event that is emitted when tokens are deposited to the fee vault
+access(all) event TokensDeposited(amount: UFix64)
+
+// Event that is emitted when tokens are withdrawn from the fee vault
+access(all) event TokensWithdrawn(amount: UFix64)
+
+// Event that is emitted when fees are deducted
+access(all) event FeesDeducted(amount: UFix64, inclusionEffort: UFix64, executionEffort: UFix64)
+
+// Event that is emitted when fee parameters change
+access(all) event FeeParametersChanged(surgeFactor: UFix64, inclusionEffortCost: UFix64, executionEffortCost: UFix64)
+```
+
+# FlowStorageFees
 
 The `FlowStorageFees` contract defines the parameters and utility methods for storage fees.
 
@@ -22,6 +45,19 @@ Source: [FlowStorageFees.cdc](https://github.com/onflow/flow-core-contracts/blob
 | Network           | Contract Address     |
 | ----------------- | -------------------- |
 | Emulator          | `0xf8d6e0586b0a20c7` |
+| Cadence Testing Framework | `0x0000000000000001` |
 | PreviewNet        | `0xab086ce9cc29fc80` |
-| Testnet/Crescendo | `0x8c5303eaa26202d6` |
+| Testnet | `0x8c5303eaa26202d6` |
 | Mainnet           | `0xe467b9dd11fa00df` |
+
+## Events
+
+Important events for `FlowStorageFees` are:
+
+```cadence
+// Emitted when the amount of storage capacity an account has per reserved Flow token changes
+access(all) event StorageMegaBytesPerReservedFLOWChanged(_ storageMegaBytesPerReservedFLOW: UFix64)
+
+// Emitted when the minimum amount of Flow tokens that an account needs to have reserved for storage capacity changes.
+access(all) event MinimumStorageReservationChanged(_ minimumStorageReservation: UFix64)
+```