diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..d8477216 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,11 @@ +name: Docs + +on: + pull_request: + +jobs: + test: + uses: FuelLabs/github-actions/.github/workflows/mdbook-docs.yml@master + with: + docs-src-path: 'docs/src' + spellcheck-config-path: 'docs/.spellcheck.yml' \ No newline at end of file diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 00000000..e76a3773 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,4 @@ +[package] +name = "sway-standards" +version = "0.5.0" +edition = "2021" diff --git a/README.md b/README.md index 7608ed59..8f3d5952 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- - Sway Standards logo + + Sway Standards logo

@@ -35,35 +35,35 @@ If you don't find what you're looking for, feel free to create an issue and prop ### Native Assets -- [SRC-20; Native Asset Standard](./SRCs/src-20.md) defines the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language. -- [SRC-3; Mint and Burn](./SRCs/src-3.md) is used to enable mint and burn functionality for fungible assets. -- [SRC-7; Arbitrary Asset Metadata Standard](./SRCs/src-7.md) is used to store metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). -- [SRC-9; Metadata Keys Standard](./SRCs/src-9.md) is used to store standardized metadata keys for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) in combination with the SRC-7 standard. -- [SRC-6; Vault Standard](./SRCs/src-6.md) defines the implementation of a standard API for asset vaults developed in Sway. +- [SRC-20; Native Asset Standard](./docs/src/src-20-native-asset.md) defines the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language. +- [SRC-3; Mint and Burn](./docs/src/src-3-minting-and-burning.md) is used to enable mint and burn functionality for fungible assets. +- [SRC-7; Arbitrary Asset Metadata Standard](./docs/src/src-7-asset-metadata.md) is used to store metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). +- [SRC-9; Metadata Keys Standard](./docs/src/src-9-metadata-keys.md) is used to store standardized metadata keys for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) in combination with the SRC-7 standard. +- [SRC-6; Vault Standard](./docs/src/src-6-vault.md) defines the implementation of a standard API for asset vaults developed in Sway. ### Access Control -- [SRC-5; Ownership Standard](./SRCs/src-5.md) is used to restrict function calls to admin users in contracts. +- [SRC-5; Ownership Standard](./docs/src/src-5-ownership.md) is used to restrict function calls to admin users in contracts. ### Contracts -- [SRC-12; Contract Factory](./SRCs/src-12.md) defines the implementation of a standard API for contract factories. -- [SRC-14; Simple Upgradable Proxies](./SRCs/src-14.md) defines the implementation of a standard API for simple upgradable proxies. +- [SRC-12; Contract Factory](./docs/src/src-12-contract-factory.md) defines the implementation of a standard API for contract factories. +- [SRC-14; Simple Upgradable Proxies](./docs/src/src-14-simple-upgradeable-proxies.md) defines the implementation of a standard API for simple upgradable proxies. ### Bridge -- [SRC-8; Bridged Asset](./SRCs/src-8.md) defines the metadata required for an asset bridged to the Fuel Network. -- [SRC-10; Native Bridge Standard](./SRCs/src-10.md) defines the standard API for the Native Bridge between the Fuel Chain and the canonical base chain. +- [SRC-8; Bridged Asset](./docs/src/src-8-bridged-asset.md) defines the metadata required for an asset bridged to the Fuel Network. +- [SRC-10; Native Bridge Standard](./docs/src/src-10-native-bridge.md) defines the standard API for the Native Bridge between the Fuel Chain and the canonical base chain. ### Documentation -- [SRC-2; Inline Documentation](./SRCs/src-2.md) defines how to document your Sway files. +- [SRC-2; Inline Documentation](./docs/src/src-2-inline-documentation.md) defines how to document your Sway files. ## Using a standard To import a standard the following should be added to the project's `Forc.toml` file under `[dependencies]` with the most recent release: -```rust +```toml standards = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.5.0" } ``` @@ -72,13 +72,13 @@ standards = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.5.0" You may then import your desired standard in your Sway Smart Contract as so: -```rust +```sway use standards::::; ``` For example, to import the SRC-20 Native Asset Standard use the following statement in your Sway Smart Contract file: -```rust +```sway use standards::src20::SRC20; ``` diff --git a/SRCs/.docs/src-10-logo-dark-theme.png b/SRCs/.docs/src-10-logo-dark-theme.png deleted file mode 100644 index 1eee3b59..00000000 Binary files a/SRCs/.docs/src-10-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-10-logo-light-theme.png b/SRCs/.docs/src-10-logo-light-theme.png deleted file mode 100644 index 720e4730..00000000 Binary files a/SRCs/.docs/src-10-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-11-logo-dark-theme.png b/SRCs/.docs/src-11-logo-dark-theme.png deleted file mode 100644 index 4d62fe84..00000000 Binary files a/SRCs/.docs/src-11-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-11-logo-light-theme.png b/SRCs/.docs/src-11-logo-light-theme.png deleted file mode 100644 index 7a36addb..00000000 Binary files a/SRCs/.docs/src-11-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-12-logo-dark-theme.png b/SRCs/.docs/src-12-logo-dark-theme.png deleted file mode 100644 index 3cfe6397..00000000 Binary files a/SRCs/.docs/src-12-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-12-logo-light-theme.png b/SRCs/.docs/src-12-logo-light-theme.png deleted file mode 100644 index d5eef206..00000000 Binary files a/SRCs/.docs/src-12-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-13-logo-dark-theme.png b/SRCs/.docs/src-13-logo-dark-theme.png deleted file mode 100644 index eed048e2..00000000 Binary files a/SRCs/.docs/src-13-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-13-logo-light-theme.png b/SRCs/.docs/src-13-logo-light-theme.png deleted file mode 100644 index b7d13fc6..00000000 Binary files a/SRCs/.docs/src-13-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-2-logo-dark-theme.png b/SRCs/.docs/src-2-logo-dark-theme.png deleted file mode 100644 index e03d0a87..00000000 Binary files a/SRCs/.docs/src-2-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-2-logo-light-theme.png b/SRCs/.docs/src-2-logo-light-theme.png deleted file mode 100644 index 8eafcd4d..00000000 Binary files a/SRCs/.docs/src-2-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-20-logo-dark-theme.png b/SRCs/.docs/src-20-logo-dark-theme.png deleted file mode 100644 index 5a81a7a5..00000000 Binary files a/SRCs/.docs/src-20-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-20-logo-light-theme.png b/SRCs/.docs/src-20-logo-light-theme.png deleted file mode 100644 index 5cd3408e..00000000 Binary files a/SRCs/.docs/src-20-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-5-logo-dark-theme.png b/SRCs/.docs/src-5-logo-dark-theme.png deleted file mode 100644 index 6808e847..00000000 Binary files a/SRCs/.docs/src-5-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-5-logo-light-theme.png b/SRCs/.docs/src-5-logo-light-theme.png deleted file mode 100644 index 55d218b8..00000000 Binary files a/SRCs/.docs/src-5-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-6-logo-dark-theme.png b/SRCs/.docs/src-6-logo-dark-theme.png deleted file mode 100644 index 5795bb9e..00000000 Binary files a/SRCs/.docs/src-6-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-6-logo-light-theme.png b/SRCs/.docs/src-6-logo-light-theme.png deleted file mode 100644 index f635d2ab..00000000 Binary files a/SRCs/.docs/src-6-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-7-logo-dark-theme.png b/SRCs/.docs/src-7-logo-dark-theme.png deleted file mode 100644 index b70e95ca..00000000 Binary files a/SRCs/.docs/src-7-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-7-logo-light-theme.png b/SRCs/.docs/src-7-logo-light-theme.png deleted file mode 100644 index b7b56916..00000000 Binary files a/SRCs/.docs/src-7-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-8-logo-dark-theme.png b/SRCs/.docs/src-8-logo-dark-theme.png deleted file mode 100644 index ebbfa5b5..00000000 Binary files a/SRCs/.docs/src-8-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-8-logo-light-theme.png b/SRCs/.docs/src-8-logo-light-theme.png deleted file mode 100644 index 190e8b27..00000000 Binary files a/SRCs/.docs/src-8-logo-light-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-9-logo-dark-theme.png b/SRCs/.docs/src-9-logo-dark-theme.png deleted file mode 100644 index aac4afc0..00000000 Binary files a/SRCs/.docs/src-9-logo-dark-theme.png and /dev/null differ diff --git a/SRCs/.docs/src-9-logo-light-theme.png b/SRCs/.docs/src-9-logo-light-theme.png deleted file mode 100644 index 0496aecb..00000000 Binary files a/SRCs/.docs/src-9-logo-light-theme.png and /dev/null differ diff --git a/.docs/sway-standards-logo-dark-theme.png b/assets/sway-standards-logo-dark-theme.png similarity index 100% rename from .docs/sway-standards-logo-dark-theme.png rename to assets/sway-standards-logo-dark-theme.png diff --git a/.docs/sway-standards-logo-light-theme.png b/assets/sway-standards-logo-light-theme.png similarity index 100% rename from .docs/sway-standards-logo-light-theme.png rename to assets/sway-standards-logo-light-theme.png diff --git a/docs/.spellcheck.yml b/docs/.spellcheck.yml new file mode 100644 index 00000000..246247ef --- /dev/null +++ b/docs/.spellcheck.yml @@ -0,0 +1,28 @@ +matrix: + - name: SPCheck + aspell: + lang: en + dictionary: + encoding: utf-8 + wordlists: + - docs/spell-check-custom-words.txt + pipeline: + - pyspelling.filters.context: + context_visible_first: true + escapes: \\[\\`~] + delimiters: + # Ignore all code blocks + - open: '(?s)^(?P *`{3,}\s*(\w+\s*,?\s*)+.*?)$' + close: '^( *`{3,})$' + - pyspelling.filters.markdown: + markdown_extensions: + - pymdownx.superfences: + - pyspelling.filters.html: + comments: false + ignores: + - code + - pre + sources: + - 'docs/src/*.md' + - 'docs/src/**/*.md' + default_encoding: utf-8 \ No newline at end of file diff --git a/docs/spell-check-custom-words.txt b/docs/spell-check-custom-words.txt new file mode 100644 index 00000000..e85a196d --- /dev/null +++ b/docs/spell-check-custom-words.txt @@ -0,0 +1,263 @@ +ABI +ABIs +ASM +IDE +IDEs +LSP +namespace +ALU +APIs +JSON +BrowserStack +CLI +Deserialization +deserializing +DApp +intrinsics +Intrinsics +workspace +workspaces +Workspaces +neovim +EVM +EVM's +EOA +ERC +Ethereum +Ethereum's +FVM +FuelVM +Fuelup +Github +GraphQL +Infura +JSON +LSP +Merkle +PoA +PoS +PoW +RPC +SDK +SDK's +SDKs +SauceLabs +Sepolia +Structs +Sway +TAI +TODO +TypeScript +UTF +UTXO +UTXOs +Utils +VM +VSCode +OSS +Linux +abigen +args +async +backend +backtraces +blockchain +blockchain's +breakpoint +breakpoints +bytecode +codespace +codespaces +config +cryptographic +customizable +customizations +dapp +dev +dropdown +enum +enums +env +forc +frontend +fuelup +fullstack +graphQL +graphql +http +https +halfword +js +localhost +mainnet +mempool +merkle +monorepo +monorepos +natively +npm +nvm +onboarding +params +pnpm +prerelease +queryable +quickstart +relayer +relayers +repo +repos +runnable +stateful +struct +structs +struct's +testnet +testnets +toolchain +toolchains +urql +validator +validators +superABI +superABIs +SuperABIs +supertraits +compositional +typeclass +turbofish +DSL +TOML +IPFS +Bitwise +Bitwise +runtime +runtimes +formatter +deployable +Utils +ETH +initializer +initializers +destructuring +instantiation +VMs +superset +CEI +pre +entrancy +interoperable +blockchains +keccak +SHA +UI +backtrace +Collateralized +collateralized +submodule +DEX +TypeChain +inlines +inlining +MiB +FuelVM's +deterministically +CLI +VS +GraphViz +DOT +DCA +AST +GitHub +decrypt +subcommand +subcommands +Subcommands +supertrait +supertraits +Supertraits +incrementor +monomorphization +Booleans +boolean +Orchestrator +orchestrator +growable +arity +tuple's +unary +SRC +DEX +SubId +upgradeable +Upgradeable +transpiler +Pausable +Libs +Reentrancy +reentrancy +mathematic +Soulbound +NFTs +NFT +dApps +fungible +TicTacToe +DAO +Timelock +transpiler +namespacing +unsafety +prioritizations +polymorphism +ContractId +ENS's +OpenSea's +URI +URIs +Multi +sha +EIP +rata +withdrawable +subvault +soulbound +configurables +Configurables +libs +backticks +enum's +NFT's +OpenZeppelin +OpenZeppelin's +UUPS +minimalistic +permissioning +Permissioning +Solana +hardcode +prepended +Farcaster +LinkedIn +Reddit +TikTok +WeChat +WhatsApp +UPU +webpage +linktree +SVG +PNG +URI +URIs +WebP +HEIF +WebM +OGV +OGG +WAV +OGA +glTF +GLB +Uninitalized +upgradeability \ No newline at end of file diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 00000000..da0c2b7f --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,17 @@ +# Summary + +[Sway Standards](./index.md) + +- [SRC-2: Inline Documentation](./src-2-inline-documentation.md) +- [SRC-3: Minting and Burning](./src-3-minting-and-burning.md) +- [SRC-5: Ownership](./src-5-ownership.md) +- [SRC-6: Vault](./src-6-vault.md) +- [SRC-7: Asset Metadata](./src-7-asset-metadata.md) +- [SRC-8: Bridged Asset](./src-8-bridged-asset.md) +- [SRC-9: Metadata Keys](./src-9-metadata-keys.md) +- [SRC-10: Native Bridge](./src-10-native-bridge.md) +- [SRC-11: Security Information](./src-11-security-information.md) +- [SRC-12: Contract Factory](./src-12-contract-factory.md) +- [SRC-13: Soulbound Address](./src-13-soulbound-address.md) +- [SRC-14: Simple Upgradeable Contract](./src-14-simple-upgradeable-proxies.md) +- [SRC-20: Native Asset](./src-20-native-asset.md) diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 00000000..749fd372 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,63 @@ +# Sway Standards + +The purpose of the Sway Standards [repository](https://github.com/FuelLabs/sway-standards) is to contain standards for the Sway Language which users can import and use. + +Standards in this repository may be in various stages of development. Use of draft standards and feedback on the proposed standards is encouraged. To use a draft, search for a standard using the appropriate GitHub label and implement the standard ABI into your contract. + +If you don't find what you're looking for, feel free to create an issue and propose a new standard! + +> **Note** +> All standards currently use `forc v0.60.0`. + +## Using a standard + +To import a standard the following should be added to the project's `Forc.toml` file under `[dependencies]` with the most recent release: + +```toml +standards = { git = "https://github.com/FuelLabs/sway-standards", tag = "v0.5.0" } +``` + +> **NOTE:** +> Be sure to set the tag to the latest release. + +You may then import your desired standard in your Sway Smart Contract as so: + +```sway +use standards::::; +``` + +For example, to import the SRC-20 Native Asset Standard use the following statement in your Sway Smart Contract file: + +```sway +use standards::src20::SRC20; +``` + +## Standards + +### Native Assets + +- [SRC-20; Native Asset Standard](./src-20-native-asset.md) defines the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language. +- [SRC-3; Mint and Burn](./src-3-minting-and-burning.md) is used to enable mint and burn functionality for fungible assets. +- [SRC-7; Arbitrary Asset Metadata Standard](./src-7-asset-metadata.md) is used to store metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). +- [SRC-9; Metadata Keys Standard](./src-9-metadata-keys.md) is used to store standardized metadata keys for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) in combination with the SRC-7 standard. +- [SRC-6; Vault Standard](./src-6-vault.md) defines the implementation of a standard API for asset vaults developed in Sway. +- [SRC-13; Soulbound Address](./src-13-soulbound-address.md) defines the implementation of a soulbound address. + +### Security and Access Control + +- [SRC-5; Ownership Standard](./src-5-ownership.md) is used to restrict function calls to admin users in contracts. +- [SRC-11; Security Information Standard](./src-11-security-information.md) is used to make communication information readily available in the case white hat hackers find a vulnerability in a contract. + +### Contracts + +- [SRC-12; Contract Factory](./src-12-contract-factory.md) defines the implementation of a standard API for contract factories. +- [SRC-14; Simple Upgradeable Proxies](./src-14-simple-upgradeable-proxies.md) defines the implementation of an upgradeable proxy contract. + +### Bridge + +- [SRC-8; Bridged Asset](./src-8-bridged-asset.md) defines the metadata required for an asset bridged to the Fuel Network. +- [SRC-10; Native Bridge Standard](./src-10-native-bridge.md) defines the standard API for the Native Bridge between the Fuel Chain and the canonical base chain. + +### Documentation + +- [SRC-2; Inline Documentation](./src-2-inline-documentation.md) defines how to document your Sway files. diff --git a/SRCs/src-10.md b/docs/src/src-10-native-bridge.md similarity index 71% rename from SRCs/src-10.md rename to docs/src/src-10-native-bridge.md index c8878866..2348b207 100644 --- a/SRCs/src-10.md +++ b/docs/src/src-10-native-bridge.md @@ -1,39 +1,32 @@ -

- - - SRC-10 logo - -

- -# Abstract +# SRC-10: Native Bridge The following standard allows for the implementation of a standard API for Native Bridges using the Sway Language. The standardized design has the bridge contract send a message to the origin chain to register which token it accepts to prevent a loss of funds. -# Motivation +## Motivation -A standard interface for bridges intends to provide a safe and efficient bridge between the settlement or canonical chain and the Fuel Network. +A standard interface for bridges intends to provide a safe and efficient bridge between the settlement or canonical chain and the Fuel Network. -# Prior Art +## Prior Art The standard is centered on Fuel’s [Bridge Architecture](https://github.com/FuelLabs/fuel-bridge/blob/main/docs/ARCHITECTURE.md). Fuel's bridge system is built on a message protocol that allows to send (and receive) messages between entities located in two different blockchains. -The following standard takes reference from the [FungibleBridge](https://github.com/FuelLabs/fuel-bridge/blob/3971081850e7961d9b649edda4cad8a848ee248e/packages/fungible-token/bridge-fungible-token/src/interface.sw#L22) ABI defined in the fuel-bridge repository. +The following standard takes reference from the [`FungibleBridge`](https://github.com/FuelLabs/fuel-bridge/blob/3971081850e7961d9b649edda4cad8a848ee248e/packages/fungible-token/bridge-fungible-token/src/interface.sw#L22) ABI defined in the fuel-bridge repository. -# Specification +## Specification The following functions MUST be implemented to follow the SRC-10; Native Bridge Standard: -## Required Functions +### Required Functions -### - `fn process_message(message_index: u64)` +**`fn process_message(message_index: u64)`** The `process_message()` function accepts incoming deposit messages from the canonical chain and issues the corresponding bridged asset. -- This function MUST parse a message at the given `message_index` index. -- This function SHALL mint an asset that follows the [SRC-8; Bridged Asset Standard](./src-8.md). +- This function MUST parse a message at the given `message_index` index. +- This function SHALL mint an asset that follows the [SRC-8; Bridged Asset Standard](./src-8-bridged-asset.md). - This function SHALL issue a refund if there is an error in the bridging process. -### - `fn withdraw(to_address: b256)` +**`fn withdraw(to_address: b256)`** The `withdraw()` function accepts and burns a bridged Native Asset on Fuel and sends a message to the bridge contract on the canonical chain to release the originally deposited tokens to the `to_address` address. @@ -41,32 +34,32 @@ The `withdraw()` function accepts and burns a bridged Native Asset on Fuel and s - This function MUST ensure the asset's `AssetId` sent in the transaction matches a bridged asset. - This function SHALL burn all coins sent in the transaction. -### - `fn claim_refund(to_address: b256, token_address: b256, token_id: b256, gateway_contract: b256)` +**`fn claim_refund(to_address: b256, token_address: b256, token_id: b256, gateway_contract: b256)`** -The `claim_refund()` function is called if something goes wrong in the bridging process and an error occurs. It sends a message to the `gateway_contract` contract on the canonical chain to release the `token_address` token with token id `token_id` to the `to_address` address. +The `claim_refund()` function is called if something goes wrong in the bridging process and an error occurs. It sends a message to the `gateway_contract` contract on the canonical chain to release the `token_address` token with token id `token_id` to the `to_address` address. - This function SHALL send a message to the `gateway_contract` contract to release the `token_address` token with id `token_id` to the `to_address` address on the canonical chain. - This function MUST ensure a refund was issued. -## Required Data Types +### Required Data Types -### `DepositType` +#### `DepositType` -The `DepositType` enum decribes whether the bridged deposit is made to a address, contract, or contract and contains additional metatdata. There MUST be the following varients in the `DepositType` enum: +The `DepositType` enum describes whether the bridged deposit is made to a address, contract, or contract and contains additional metadata. There MUST be the following variants in the `DepositType` enum: -#### Address: `()` +**`Address`: `()`** -The `Address` varient MUST represent when the deposit is made to an address on the Fuel chain. +The `Address` variant MUST represent when the deposit is made to an address on the Fuel chain. -#### Contract: `()` +**`Contract`: `()`** -The `Contract` varient MUST represent when the deposit is made to an contract on the Fuel chain. +The `Contract` variant MUST represent when the deposit is made to an contract on the Fuel chain. -#### ContractWithData: `()` +**`ContractWithData`: `()`** -The `ContractWithData` varient MUST represent when the deposit is made to an contract and contains additional metadata for the Fuel chain. +The `ContractWithData` variant MUST represent when the deposit is made to an contract and contains additional metadata for the Fuel chain. -#### Example +##### Example Deposit Type ```sway pub enum DepositType { @@ -76,41 +69,41 @@ pub enum DepositType { } ``` -### `DepositMessage` +#### `DepositMessage` The following describes a struct that encapsulates various deposit message metadata to a single type. There MUST be the following fields in the `DepositMessage` struct: -#### - amount: `u256` +**`amount`: `u256`** The `amount` field MUST represent the number of tokens. -#### - from: `b256` +**`from`: `b256`** The `from` field MUST represent the bridging user’s address on the canonical chain. -#### - to: `Identity` +**`to`: `Identity`** The `to` field MUST represent the bridging target destination `Address` or `ContractId` on the Fuel Chain. -#### - token_address: `b256` +**`token_address`: `b256`** The `token_address` field MUST represent the bridged token's address on the canonical chain. -#### - token_id: `b256` +**`token_id`: `b256`** The `token_id` field MUST represent the token's ID on the canonical chain. The `b256::zero()` MUST be used if this is a fungible token and no token ID exists. -#### - decimals: `u8` +**`decimals`: `u8`** The `decimals` field MUST represent the bridged token's decimals on the canonical chain. -#### - deposit_type: `DepositType` +**`deposit_type`: `DepositType`** The `deposit_type` field MUST represent the type of bridge deposit made on the canonical chain. -#### Example +##### Example Deposit Message -```sway +```sway pub struct DepositMessage { pub amount: b256, pub from: b256, @@ -122,29 +115,29 @@ pub struct DepositMessage { } ``` -### `MetadataMessage` +#### `MetadataMessage` The following describes a struct that encapsulates the metadata of token on the canonical chain to a single type. There MUST be the following fields in the `MetadataMessage` struct: -#### token_address: `b256` +**`token_address`: `b256`** The `token_address` field MUST represent the bridged token's address on the canonical chain. -#### token_id: `b256` +**`token_id`: `b256`** The `token_id` field MUST represent the token's ID on the canonical chain. The `b256::zero()` MUST be used if this is a fungible token and no token ID exists. -#### name: `String` +**`name`: `String`** The `name` field MUST represent the bridged token's name field on the canonical chain. -#### symbol: `String` +**`symbol`: `String`** The `symbol` field MUST represent the bridged token's symbol field on the canonical chain. -### Example +##### Example Metadata Message -```sway +```sway pub struct MetadataMessage { pub token_address: b256, pub token_id: b256, @@ -155,17 +148,17 @@ pub struct MetadataMessage { ## Required Standards -Any contract that implements the SRC-10; Native Bridge Standard MUST implement the [SRC-8; Bridged Asset Standard](./src-8.md) for all bridged assets. +Any contract that implements the SRC-10; Native Bridge Standard MUST implement the [SRC-8; Bridged Asset Standard](./src-8-bridged-asset.md) for all bridged assets. -# Rationale +## Rationale -The SRC-10; Native Bridge Standard is designed to standardize the native bridge interface between all Fuel instances. +The SRC-10; Native Bridge Standard is designed to standardize the native bridge interface between all Fuel instances. -# Backwards Compatibility +## Backwards Compatibility This standard is compatible with the SRC-20 and SRC-8 standards. -# Example ABI +## Example ABI ```sway abi SRC10 { @@ -173,4 +166,4 @@ abi SRC10 { fn withdraw(to_address: b256); fn claim_refund(to_address: b256, token_address: b256, token_id: b256, gateway_contract: b256); } -``` \ No newline at end of file +``` diff --git a/SRCs/src-11.md b/docs/src/src-11-security-information.md similarity index 73% rename from SRCs/src-11.md rename to docs/src/src-11-security-information.md index 1bf7a51c..314b3ca5 100644 --- a/SRCs/src-11.md +++ b/docs/src/src-11-security-information.md @@ -1,89 +1,82 @@ -

- - - SRC-11 logo - -

- -# Abstract +# SRC-11: Security Information The following standard allows for contract creators to make communication information readily available to everyone, with the primary purpose of allowing white hat hackers to coordinate a bug-fix or securing of funds. -# Motivation +## Motivation White hat hackers may find bugs or exploits in contracts that they want to report to the project for safeguarding of funds. It is not immediately obvious from a `ContractId`, who the right person to contact is. This standard aims to make the process of bug reporting as smooth as possible. -# Prior Art +## Prior Art -The [security.txt](https://github.com/neodyme-labs/solana-security-txt) library for Solana has explored this idea. This standard takes inspiration from the library, with some changes. +The [`security.txt`](https://github.com/neodyme-labs/solana-security-txt) library for Solana has explored this idea. This standard takes inspiration from the library, with some changes. -# Specification +## Specification -## Security Information Type +### Security Information Type -The following describes the `SecurityInformation` type. +The following describes the `SecurityInformation` type. - The struct MAY contain `None` for `Option` type fields, if they are deemed unnecessary. - The struct MUST NOT contain empty `String` or `Vec` fields. - The struct MAY contain a URL or the information directly for the following fields: `project_url`, `policy`, `encryption`, `source_code`, `auditors`, `acknowledgments`, `additional_information`. - The struct MUST contain the information directly for the following fields: `name`, `contact_information`, `preferred_languages`, `source_release`, and `source_revision`. - The struct MUST contain at least one item in the `preferred_languages` field's `Vec`, if it is not `None`. Furthermore, the string should only contain the [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) language code and nothing else. -- The struct MUST contain at least one item in the `contact_information` field's `Vec`. Furthermore, the string should follow the following format `:`. Where `contact_type` describes the method of contact (eg. `email` or `discord`) and `contact_information` describes the information needed to contact (eg. `example@example.com` or `@EXAMPLE`). +- The struct MUST contain at least one item in the `contact_information` field's `Vec`. Furthermore, the string should follow the following format `:`. Where `contact_type` describes the method of contact (e.g. `email` or `discord`) and `contact_information` describes the information needed to contact (e.g. `example@example.com` or `@EXAMPLE`). -### `name: String` +#### `name: String` The name of the project that the contract is associated with. -### `project_url: Option` +#### `project_url: Option` The website URL of the project that the contract is associated with. -### `contact_information: Vec` +#### `contact_information: Vec` A list of contact information to contact developers of the project. Should be in the format `:`. You should include contact types that will not change over time. -### `policy: String` +#### `policy: String` Text describing the project's security policy, or a link to it. This should describe what kind of bounties your project offers and the terms under which you offer them. -### `preferred_languages: Option>` +#### `preferred_languages: Option>` -A list of preferred languages [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). +A list of preferred languages [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes). If the field is not `None`, it MUST contain at least one item. -### `encryption: Option` +#### `encryption: Option` A PGP public key block (or similar) or a link to one. -### `source_code: Option` +#### `source_code: Option` A URL to the project's source code. -### `source_release: Option` +#### `source_release: Option` -The release identifier of this build, ideally corresponding to a tag on git that can be rebuilt to reproduce the same binary. 3rd party build verification tools will use this tag to identify a matching github release. +The release identifier of this build, ideally corresponding to a tag on git that can be rebuilt to reproduce the same binary. 3rd party build verification tools will use this tag to identify a matching GitHub release. -### `source_revision: Option` +#### `source_revision: Option` -The revision identifier of this build, usually a git commit hash that can be rebuilt to reproduce the same binary. 3rd party build verification tools will use this tag to identify a matching github release. +The revision identifier of this build, usually a git commit hash that can be rebuilt to reproduce the same binary. 3rd party build verification tools will use this tag to identify a matching GitHub release. -### `auditors: Option>` +#### `auditors: Option>` A list of people or entities that audited this smart contract, or links to pages where audit reports are hosted. Note that this field is self-reported by the author of the program and might not be accurate. -### `acknowledgments: Option` +#### `acknowledgments: Option` Text containing acknowledgments to security researchers who have previously found vulnerabilities in the project, or a link to it. -### `additional_information: Option` +#### `additional_information: Option` Text containing any additional information you want to provide, or a link to it. -## Required Functions +### Required Functions The following function MUST be implemented to follow the SRC-11 standard. -### `fn security_information() -> SecurityInformation;` +#### `fn security_information() -> SecurityInformation;` This function takes no input parameters and returns a struct containing contact information for the project owners, information regarding the bug bounty program, other information related to security, and any other information that the developers find relevant. @@ -91,19 +84,19 @@ This function takes no input parameters and returns a struct containing contact - This function's return values MUST follow the specification for the `SecurityInformation` type. - This function MUST NOT revert under any circumstances. -# Rationale +## Rationale The return structure discussed covers most information that may want to be conveyed regarding the security of the contract, with an additional field to convey any additional information. This should allow easy communication between the project owners and any white hat hackers if necessary. -# Backwards Compatibility +## Backwards Compatibility -This standard does not face any issues with backward compatibility. +This standard does not face any issues with backward compatibility. -# Security Considerations +## Security Considerations The information is entirely self reported and as such might not be accurate. Accuracy of information cannot be enforced and as such, anyone using this information should be aware of that. -# Example ABI +## Example ABI ```sway abi SRC11 { @@ -112,12 +105,20 @@ abi SRC11 { } ``` -# Example Implementation +## Example Implementation -## [Hard coded information](../examples/src11-security-information/hardcoded-information) +### Hard coded information A basic implementation of the security information standard demonstrating how to hardcode information to be returned. -## [Variable information](../examples/src11-security-information/variable-information) +```sway +{{#include ../examples/src11-security-information/hardcoded-information/src/main.sw}} +``` + +### Variable information A basic implementation of the security information standard demonstrating how to return variable information that can be edited to keep it up to date. In this example only the contact_information field is variable, but the same method can be applied to any field which you wish to update. + +```sway +{{#include ../examples/src11-security-information/variable-information/src/main.sw}} +``` diff --git a/SRCs/src-12.md b/docs/src/src-12-contract-factory.md similarity index 71% rename from SRCs/src-12.md rename to docs/src/src-12-contract-factory.md index 591d49c6..aca899c0 100644 --- a/SRCs/src-12.md +++ b/docs/src/src-12-contract-factory.md @@ -1,33 +1,26 @@ -

- - - SRC-12 logo - -

- -# Abstract +# SRC-12: Contract Factory The following standard allows for the implementation of a standard ABI for Contract Factories using the Sway Language. The standardized design designates how verification of newly deployed child contracts are handled. -# Motivation +## Motivation A standard interface for Contract Factories provides a safe and effective method of ensuring contracts can verify the validity of another contract as a child of a factory. This is critical on the Fuel Network as contracts cannot deploy other contracts and verification must be done after deployment. -# Prior Art +## Prior Art A Contract Factory is a design where a template contract is used and deployed repeatedly with different configurations. These configurations are often minor changes such as pointing to a different asset. All base functionality remains the same. On Fuel, contracts cannot deploy other contracts. As a result, a Contract Factory on Fuel must register and verify that the bytecode root of a newly deployed child contract matches the expected bytecode root. -When changing something such as a configurable in Sway, the bytecode root is recalculated. The [Bytecode Library](https://github.com/FuelLabs/sway-libs/tree/master/libs/bytecode) has been developed to calculate the bytecode root of a contract with different configurables. +When changing something such as a configurable in Sway, the bytecode root is recalculated. The [Bytecode Library](https://docs.fuel.network/docs/sway-libs/bytecode/) has been developed to calculate the bytecode root of a contract with different configurables. -# Specification +## Specification The following functions MUST be implemented to follow the SRC-12; Contract Factory Standard: -## Required Functions +### Required Functions -### - `fn register_contract(child_contract: ContractId, configurables: Option)>>) -> Result` +#### `fn register_contract(child_contract: ContractId, configurables: Option)>>) -> Result` The `register_contract()` function verifies that a newly deployed contract is the child of a contract factory. @@ -37,41 +30,41 @@ The `register_contract()` function verifies that a newly deployed contract is th - This function MUST return a `Result` containing the `b256` bytecode root of the newly registered contract or an `str` error message. - This function MAY add arbitrary conditions checking a contract factory child’s validity, such as verifying storage variables or initialized values. -### - `fn is_valid(child_contract: ContractId) -> bool` +#### `fn is_valid(child_contract: ContractId) -> bool` -The `is_valid()` function returns a boolean representing the state of whether a contract is registered as a valid child of the contract factory. +The `is_valid()` function returns a boolean representing the state of whether a contract is registered as a valid child of the contract factory. - This function MUST return `true` if this is a valid and registered child, otherwise `false`. -### - `fn factory_bytecode_root() -> Option` +#### `fn factory_bytecode_root() -> Option` The `factory_bytecode_root()` function returns the bytecode root of the default template contract. - This function MUST return the bytecode root of the template contract. -## Optional Functions +### Optional Functions The following are functions that may enhance the use of the SRC-12 standard but ARE NOT required. -### - `fn get_contract_id(configurables: Option)>>) -> Option` +#### `fn get_contract_id(configurables: Option)>>) -> Option` The `get_contract_id()` function returns a registered contract factory child contract with specific implementation details specified by `configurables`. -- This function MUST return `Some(ContractId)` IF a contract that follows the specified `configurables` has been registered with the SRC-12 Contract Factory contract, otherwise `None`. +This function MUST return `Some(ContractId)` IF a contract that follows the specified `configurables` has been registered with the SRC-12 Contract Factory contract, otherwise `None`. -# Rationale +## Rationale -The SRC-12; Contract Factory Standard is designed to standardize the contract factory design implementation interface between all Fuel instances. +The SRC-12; Contract Factory Standard is designed to standardize the contract factory design implementation interface between all Fuel instances. -# Backwards Compatibility +## Backwards Compatibility There are no other standards that the SRC-12 requires compatibility. -# Security Considerations +## Security Considerations This standard takes into consideration child contracts that are deployed with differentiating configurable values, however individual contract behaviors may be dependent on storage variables. As storage variables may change after the contract has been registered with the SRC-12 compliant contract, the standard suggests to check these values upon registration however it is not enforced. -# Example ABI +## Example ABI ```sway abi SRC12 { @@ -89,13 +82,20 @@ abi SRC12_Extension { } ``` -# Example Implementation +## Example Implementation -## [With Configurables](../examples/src12-contract-factory/with_configurables/src/with_configurables.sw) +### With Configurables Example of the SRC-12 implementation where contract deployments contain configurable values that differentiate the bytecode root from other contracts with the same bytecode. -## [Without Configurables](../examples/src12-contract-factory/without_configurables/src/without_configurables.sw) +```sway +{{#include ../examples/src12-contract-factory/with_configurables/src/with_configurables.sw}} +``` + +### Without Configurables -Example of the SRC-12 implementation where all contract deployments are identitcal and thus have the same bytecode and root. +Example of the SRC-12 implementation where all contract deployments are identical and thus have the same bytecode and root. +```sway +{{#include ../examples/src12-contract-factory/without_configurables/src/without_configurables.sw}} +``` diff --git a/SRCs/src-13.md b/docs/src/src-13-soulbound-address.md similarity index 84% rename from SRCs/src-13.md rename to docs/src/src-13-soulbound-address.md index 6d2495bf..5a7b89c5 100644 --- a/SRCs/src-13.md +++ b/docs/src/src-13-soulbound-address.md @@ -1,41 +1,34 @@ -

- - - SRC-13 logo - -

+# SRC-13: Soulbound Address -# Abstract +The following standard allows for the implementation of Soulbound Address on the Fuel Network. Soulbound Assets are [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) sent to the Soulbound Address and cannot be transferred. As Native Assets on the Fuel Network do not require approvals to be spent, any asset sent to an `Address` may be transferable. The SRC-13 standard provides a predicate interface to lock Native Assets as soulbound. -The following standard allows for the implementation of Soulbound Address on the Fuel Network. Soulbound Assets are [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) sent to the Soulbound Address and cannot be transferred. As Native Assets on the Fuel Network do not require approvals to be spent, any asset sent to an `Address` may be transferable. The SRC-13 standard provides a predicate interface to lock Native Assets as soulbound. +## Motivation -# Motivation +This standard enables soulbound assets on Fuel and allows external applications to query and provide soulbound assets, whether that be decentralized exchanges, wallets, or other external applications. -A standard enables soulbound assets on Fuel and allows external applications to query and provide soulbound assets, whether that be decentralized exchanges, wallets, or other external applications. +## Prior Art -# Prior Art - -[Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) on the Fuel Network do not require the implementation of certain functions such as transfer or approval. This is done directly within the FuelVM and there is no smart contract that requires updating of balances. As such, any assets sent to an `Address` may be spendable and ownership of that asset may be transferred. For any soulbound assets, spending must be restricted. +[Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) on the Fuel Network do not require the implementation of certain functions such as transfer or approval. This is done directly within the FuelVM and there is no smart contract that requires updating of balances. As such, any assets sent to an `Address` may be spendable and ownership of that asset may be transferred. For any soulbound assets, spending must be restricted. Predicates are programs that return a Boolean value and which represent ownership of some resource upon execution to true. All predicates evaluate to an `Address` based on their bytecode root. A predicate must evaluate to true such that the assets may be spent. The SRC-13 Soulbound Asset Standard naming pays homage to the [ERC-5192: Minimal Soulbound NFTs](https://eips.ethereum.org/EIPS/eip-5192) seen on Ethereum. While there is functionality we may use as a reference, it is noted that Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) are fundamentally different than Ethereum's tokens. -# Specification +## Specification -## Overview +### Overview To ensure that some asset shall never be spent, we must apply spending conditions. This can be done with Predicates on Fuel. Any asset sent to a Predicate `Address` shall never be spent if the predicate never evaluates to true. We must also ensure every `Address` on Fuel has its own Predicate. This can be guaranteed by using a `configurable` where an `Address` is defined. -## Definitions +### Definitions - **Soulbound Address Predicate** - The resulting predicate which owns assets on behalf of an `Address`. - **Soulbound Address** - The computed `Address` of the *Soulbound Asset Predicate*. - **Soulbound Asset** - Any [Native Asset](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) sent to the *Soulbound Address*. -## Soulbound Address Predicate Specification +### Soulbound Address Predicate Specification - The *Soulbound Address Predicate* SHALL never spend the assets sent to its computed predicate `Address` or *Soulbound Address*. - The *Soulbound Address Predicate* SHALL encode an `Address` of which it represents the soulbound address. @@ -55,33 +48,33 @@ fn main() -> bool { } ``` -## Soulbound Address +### Soulbound Address -The *Soulbound Address* is the *Soulbound Address Predicate*'s predicate address. A predicate's address(the bytecode root) is defined [here](https://github.com/FuelLabs/fuel-specs/blob/master/src/identifiers/predicate-id.md). +The *Soulbound Address* is the *Soulbound Address Predicate*'s predicate address. A predicate's address(the bytecode root) is defined [here](https://github.com/FuelLabs/fuel-specs/blob/master/src/identifiers/predicate-id.md). -The *Soulbound Address* may be computed from the *Soulbound Address Predicate*'s bytecode both on-chain or off-chain. For off-chain computation, please refer to the fuels-rs [predicate docs](https://docs.fuel.network/docs/fuels-rs/predicates/). For on-chain computation, please refer to Sway-Lib's [Bytecode Library](https://github.com/FuelLabs/sway-libs/tree/master/libs/bytecode). +The *Soulbound Address* may be computed from the *Soulbound Address Predicate*'s bytecode both on-chain or off-chain. For off-chain computation, please refer to the fuels-rs [predicate docs](https://docs.fuel.network/docs/fuels-rs/predicates/). For on-chain computation, please refer to Sway-Lib's [Bytecode Library](https://docs.fuel.network/docs/sway-libs/bytecode/). -# Rationale +## Rationale On the Fuel Network, the process for sending any [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) is the same and does not require any approval. This means that any assets sent to an Address may be spendable and does not require any external spending conditions. In the case of a soulbound asset, we need to ensure the asset cannot be spent. -# Backwards Compatibility +## Backwards Compatibility -This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) and the [SRC-20](./src-20.md) standard. +This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) and the [SRC-20](./src-20-native-asset.md) standard. -# Security Considerations +## Security Considerations This standard does not introduce any security concerns, as it does not call external contracts, nor does it define any mutations of the contract state. It should however be noted that any Native Asset on the Fuel Network is not a Soulbound Asset until it is sent to a *Soulbound Address*. -# Example +## Example -The following example shows the *Soulbound Address Predicate* for the `0xe033369a522e3cd2fc19a5a705a7f119938027e8e287c0ec35b784e68dab2be6` `Address`. +The following example shows the *Soulbound Address Predicate* for the `0xe033369a522e3cd2fc19a5a705a7f119938027e8e287c0ec35b784e68dab2be6` `Address`. The resulting *Soulbound Address* is `0x7f28a538d06788a3d98bb72f4b41012d86abc4b0369ee5dedf56cfbaf245d609`. Any Native Assets sent to this address will become Soulbound Assets. -```sway +```sway predicate; configurable { diff --git a/SRCs/src-14.md b/docs/src/src-14-simple-upgradeable-proxies.md similarity index 77% rename from SRCs/src-14.md rename to docs/src/src-14-simple-upgradeable-proxies.md index 4ac73d5c..7c75338f 100644 --- a/SRCs/src-14.md +++ b/docs/src/src-14-simple-upgradeable-proxies.md @@ -1,8 +1,6 @@ -# Simple Upgradable Proxies +# SRC-14: Simple Upgradeable Proxies -## Abstract - -The following proposes a standard for simple upgradable proxies. +The following proposes a standard for simple upgradeable proxies. ## Motivation @@ -13,11 +11,12 @@ We seek to standardize a proxy implementation to improve developer experience an [This OpenZeppelin blog post](https://blog.openzeppelin.com/the-state-of-smart-contract-upgrades#proxies-and-implementations) is a good survey of the state of the art at this time. Proxy designs fall into three essential categories: + 1. Immutable proxies which are lightweight clones of other contracts but can't change targets -2. Upgradable proxies such as [UUPS](https://eips.ethereum.org/EIPS/eip-1822) which store a target in storage and delegate all calls to it -3. [Diamonds](https://eips.ethereum.org/EIPS/eip-2535) which are both upgradable and can point to multiple targets on a per method basis +2. Upgradeable proxies such as [UUPS](https://eips.ethereum.org/EIPS/eip-1822) which store a target in storage and delegate all calls to it +3. [Diamonds](https://eips.ethereum.org/EIPS/eip-2535) which are both upgradeable and can point to multiple targets on a per method basis -This document falls in the second category. We want to standardize the implementation of simple upgradable passthrough contracts. +This document falls in the second category. We want to standardize the implementation of simple upgradeable pass-through contracts. The FuelVM provides an `LDC` instruction that is used by Sway's `std::execution::run_external` to provide a similar behavior to EVM's `delegatecall` and execute instructions from another contract while retaining one's own storage context. This is the intended means of implementation of this standard. @@ -44,7 +43,7 @@ This method SHOULD implement access controls such that the target can only be ch ## Rationale -This standard is meant to provide simple upgradability, it is deliberately minimalistic and does not provide the level of functionality of diamonds. +This standard is meant to provide simple upgradeability, it is deliberately minimalistic and does not provide the level of functionality of diamonds. Unlike in [UUPS](https://eips.ethereum.org/EIPS/eip-1822), this standard requires that the upgrade function is part of the proxy and not its target. This prevents irrecoverable updates if a proxy is made to point to another proxy and no longer has access to upgrade logic. @@ -58,7 +57,7 @@ As it is the first attempt to standardize proxy implementation, we do not consid ## Security Considerations Permissioning proxy target changes is the primary consideration here. -This standard is not opinionated about means of achieving this, use of [SRC-5](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-5.md) is recommended. +This standard is not opinionated about means of achieving this, use of [SRC-5](./src-5-ownership.md) is recommended. ## Example ABI @@ -71,10 +70,18 @@ abi SRC14 { ## Example Implementation -### [Minimal Proxy](../examples/src14-simple-proxy/minimal/src/minimal.sw) +### Minimal Proxy Example of a minimal SRC-14 implementation with no access control. -### [Owned Proxy](../examples/src14-simple-proxy/owned/src/owned.sw) +```sway +{{#include ../../examples/src14-simple-proxy/minimal/src/minimal.sw}} +``` + +### Owned Proxy + +Example of a SRC-14 implementation that also implements [SRC-5](./src-5-ownership.md). -Example of a SRC-14 implementation that also implements [SRC-5](https://github.com/FuelLabs/sway-standards/blob/master/SRCs/src-5.md). +```sway +{{#include ../../examples/src14-simple-proxy/owned/src/owned.sw}} +``` diff --git a/SRCs/src-2.md b/docs/src/src-2-inline-documentation.md similarity index 81% rename from SRCs/src-2.md rename to docs/src/src-2-inline-documentation.md index bd1210dc..83e7f784 100644 --- a/SRCs/src-2.md +++ b/docs/src/src-2-inline-documentation.md @@ -1,106 +1,99 @@ -

- - - SRC-2 logo - -

- -# Abstract +# SRC-2: Inline Documentation The following standard intends to define the structure and organization of inline documentation for functions, structs, enums, storage, configurables, and more within the Sway Language. This is a living standard. -# Motivation +## Motivation The standard seeks to provide a better developer experience using Fuel's tooling and the Language Server. This will allow for better interoperability between applications and enable developers to quickly understand any external code they are using or implementing. -# Prior Art +## Prior Art A number of pre-existing functions in the [sway standard library](https://github.com/FuelLabs/sway/tree/master/sway-lib-std), [sway-applications](https://github.com/FuelLabs/sway-applications), and [sway-libs](https://github.com/FuelLabs/sway-libs) repositories have inline documentation. The inline documentation for these is already compatible with Fuel's VS Code extension. These however do not all follow the same structure and outline. -# Specification +## Specification -## Functions +### Functions -The following describes the structure and order of inline documentation for functions. Some sections MAY NOT apply to each function. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for functions. Some sections MAY NOT apply to each function. When a section is not relevant it SHALL be omitted. -#### - Description +#### Functions: Description -This section has no header. -A simple explanation of the function's intent or functionality. +This section has no header. +A simple explanation of the function's intent or functionality. Example: -```rust +```sway /// This function computes the hash of two numbers. ``` -#### - Additional Information +#### Functions: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the function's intent or functionality. Example: -```rust +```sway /// # Additional Information /// /// This function also has some complex behaviors. ``` -#### - Arguments +#### Functions: Arguments This section has a `h1` header. Lists the arguments of the function's definition with the `*` symbol and describes each one. The list SHALL provide the name, type, and description. The argument SHALL be encapsulated between two backticks: `argument`. The type SHALL be encapsulated between two square brackets: [type]. Example: -```rust +```sway /// # Arguments /// /// * `argument_1`: [Identity] - This argument is a user to be hashed. ``` -#### - Returns +#### Functions: Returns This section has a `h1` header. Lists the return values of the function with the `*` symbol and describes each one. This list SHALL be in the order of the return index and provide the type and description. The type SHALL be encapsulated between two square brackets: [type]. Example: -```rust +```sway /// # Returns /// /// * [u64] - The number of hashes performed. ``` -#### - Reverts +#### Functions: Reverts This section has a `h1` header. Lists the cases in which the function will revert starting with the `*` symbol. The list SHALL be in the order of occurrence within the function. Example: -```rust +```sway /// # Reverts /// /// * When `argument_1` or `argument_2` are a zero [b256]. ``` -#### - Number of Storage Accesses +#### Functions: Number of Storage Accesses -This section has a `h1` header. +This section has a `h1` header. Provides information on how many storage reads, writes, and clears occur within the function. Example: -```rust +```sway /// # Number of Storage Accesses /// /// * Reads: `1` /// * Clears: `2` ``` -#### - Examples +#### Functions: Examples This section has a `h1` header. This section provides an example of the use of the function. This section is not required to follow the SRC-2 standard however encouraged for auxiliary and library functions. Example: -```rust +```sway /// # Examples /// /// ```sway @@ -109,204 +102,205 @@ Example: /// } ``` -## Structs +### Structs -The following describes the structure and order of inline documentation for structs. Some sections MAY NOT apply to each struct. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for structs. Some sections MAY NOT apply to each struct. When a section is not relevant it SHALL be omitted. -#### - Description +#### Structs: Description -This section has no header. -A simple explanation of the struct's purpose or functionality. +This section has no header. +A simple explanation of the struct's purpose or functionality. Example: -```rust +```sway /// This struct contains information on an NFT. ``` -#### - Additional Information +#### Structs: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the struct's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This struct also has some complex behaviors. ``` -### - Fields +### Fields -The following describes the structure and order of inline documentation for fields within structs. Some sections MAY NOT apply to each field. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for fields within structs. Some sections MAY NOT apply to each field. When a section is not relevant it SHALL be omitted. -#### Description +#### Fields: Description -This section has no header. -Each field SHALL have its own description with a simple explanation of the field's purpose or functionality. +This section has no header. +Each field SHALL have its own description with a simple explanation of the field's purpose or functionality. Example: -```rust +```sway /// This field represents an owner. field_1: Identity, ``` -#### - Additional Information +#### Fields: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the field's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This field also has some complex behaviors. ``` -## Enums +### Enums -The following describes the structure and order of inline documentation for enums. Some sections MAY NOT apply to each enum. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for enums. Some sections MAY NOT apply to each enum. When a section is not relevant it SHALL be omitted. -#### - Description +#### Enums: Description -This section has no header. -A simple explanation of the enum's purpose or functionality. +This section has no header. +A simple explanation of the enum's purpose or functionality. Example: -```rust +```sway /// This enum holds the state of a contract. ``` -#### - Additional Information +#### Enums: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the enum's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This enum also has some complex behaviors. ``` -### - Variant +### Variant -The following describes the structure and order of inline documentation for fields within enums. Some sections MAY NOT apply to each field. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for fields within enums. Some sections MAY NOT apply to each field. When a section is not relevant it SHALL be omitted. -#### Description +#### Variant: Description -This section has no header. -Each variant SHALL have its own description with a simple explanation of the variant's purpose or functionality. +This section has no header. +Each variant SHALL have its own description with a simple explanation of the variant's purpose or functionality. Example: -```rust +```sway /// This variant represents the uninitialized state of a contract. variant_1: (), /// This variant represents the initialized state of a contract. variant_2: Identity, ``` -#### - Additional Information +#### Variant: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the variant's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This variant also has some complex behaviors. ``` -## Errors +### Errors -In Sway, errors are recommended to be enums. They SHALL follow the same structure and order for inline documentation as described above for enums. Some sections MAY NOT apply to each error. When a section is not relevant it SHALL be omitted. +In Sway, errors are recommended to be enums. They SHALL follow the same structure and order for inline documentation as described above for enums. Some sections MAY NOT apply to each error. When a section is not relevant it SHALL be omitted. -## Logs +### Logs -In Sway, logs are recommended to be structs. They SHALL follow the same structure and order for inline documentation as described above for structs. Some sections MAY NOT apply to each log. When a section is not relevant it SHALL be omitted. +In Sway, logs are recommended to be structs. They SHALL follow the same structure and order for inline documentation as described above for structs. Some sections MAY NOT apply to each log. When a section is not relevant it SHALL be omitted. -## Storage +### Storage -The following describes the structure and order of inline documentation for variables within the storage block. Some sections MAY NOT apply to each storage variable. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for variables within the storage block. Some sections MAY NOT apply to each storage variable. When a section is not relevant it SHALL be omitted. -#### - Description +#### Storage: Description -This section has no header. -A simple explanation of the storage variable's purpose or functionality. +This section has no header. +A simple explanation of the storage variable's purpose or functionality. Example: -```rust +```sway /// This storage variable is used for state. ``` -#### - Additional Information +#### Storage: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the storage variable's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This storage variable maps a user to a state. ``` -## Configurable +### Configurable -The following describes the structure and order of inline documentation for variables in the configurable block. Some sections MAY NOT apply to each storage variable. When a section is not relevant it SHALL be omitted. +The following describes the structure and order of inline documentation for variables in the configurable block. Some sections MAY NOT apply to each storage variable. When a section is not relevant it SHALL be omitted. -#### - Description +#### Configurable: Description -This section has no header. -A simple explanation of the configurable variable's purpose or functionality. +This section has no header. +A simple explanation of the configurable variable's purpose or functionality. Example: -```rust +```sway /// This configurable variable is used for an address. ``` -#### - Additional Information +#### Configurable: Additional Information This section has a `h1` header. This section is directly below the description and can provide additional information beyond the configurable variable's purpose or functionality. Example: -```rust +```sway /// # Additional Information /// /// This configurable variable makes security assumptions. ``` -## Other Sections +### Other Sections If the above described sections are not relevant for the information that needs to documented, a custom section with a arbitrary `h1` header may be utilized. Example: -``` + +```sway /// # Recommended Message Style /// /// We recommend that `expect` messages are used to describe the reason you *expect* the `Option` should be `Some`. ``` -# Rationale +## Rationale The SRC-2 standard should help provide developers with an easy way to both quickly write inline documentation and get up to speed on other developers' code. This standard in combination with Fuel's VS Code extension provides readily accessible information on functions, structs, and enums ![Screenshot 2023-05-10 125656](https://github.com/FuelLabs/sway-standards/assets/54727135/f03073b9-2a28-44d1-b12a-5603a0738fee) -# Backwards Compatibility +## Backwards Compatibility There are no standards that the SRC-2 standard requires to be backward compatible with. -# Security Considerations +## Security Considerations This standard will improve security by providing developers with relevant information such as revert cases. -# Examples +## Examples -## Function Example +### Function Example -```rust +```sway /// Ensures that the sender is the owner. /// /// # Arguments @@ -345,9 +339,9 @@ pub fn only_owner(self, number: u64) -> bool { } ``` -## Struct Examples +### Struct Examples -```rust +```sway /// Metadata that is tied to an asset. pub struct NFTMetadata { /// Represents the ID of this NFT. @@ -355,7 +349,7 @@ pub struct NFTMetadata { } ``` -```rust +```sway /// Log of a bid. pub struct Bid { /// The number of coins that were bid. @@ -365,9 +359,9 @@ pub struct Bid { } ``` -## Enum Examples +### Enum Examples -```rust +```sway /// Determines the state of ownership. pub enum State { /// The ownership has not been set. @@ -379,7 +373,7 @@ pub enum State { } ``` -```rust +```sway /// Error log for when access is denied. pub enum AccessError { /// Emitted when the caller is not the owner of the contract. @@ -387,9 +381,9 @@ pub enum AccessError { } ``` -## Storage Examples +### Storage Examples -```rust +```sway storage { /// An asset which is to be distributed. asset: Option = Option::None, @@ -402,9 +396,9 @@ storage { } ``` -## Configurable Example +### Configurable Example -```rust +```sway configurable { /// The threshold required for activation. THRESHOLD: u64 = 5, diff --git a/SRCs/src-20.md b/docs/src/src-20-native-asset.md similarity index 83% rename from SRCs/src-20.md rename to docs/src/src-20-native-asset.md index c68ed9ce..2e02fa84 100644 --- a/SRCs/src-20.md +++ b/docs/src/src-20-native-asset.md @@ -1,76 +1,69 @@ -

- - - SRC-20 logo - -

- -# Abstract +# SRC-20: Native Asset The following standard allows for the implementation of a standard API for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) using the Sway Language. This standard provides basic functionality as well as on-chain metadata for other applications to use. -# Motivation +## Motivation A standard interface for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) on Fuel allows external applications to interact with the native asset, whether that be decentralized exchanges, wallets, or Fuel's [Scripts](https://docs.fuel.network/docs/sway/sway-program-types/scripts/) and [Predicates](https://docs.fuel.network/docs/sway/sway-program-types/predicates/). -# Prior Art +## Prior Art The SRC-20 Native Asset Standard naming pays homage to the [ERC-20 Token Standard](https://eips.ethereum.org/EIPS/eip-20) seen on Ethereum. While there is functionality we may use as a reference, it is noted that Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) are fundamentally different than Ethereum's tokens. -There has been a discussion of the Fungible Token Standard on the [Fuel Forum](https://forum.fuel.network/). This discussion can be found [here](https://forum.fuel.network/t/src-20-fungible-token-standard/186). +There has been a discussion of the Fungible Token Standard on the [Fuel Forum](https://forum.fuel.network/). This discussion can be found [here](https://forum.fuel.network/t/src-20-fungible-token-standard/186). There has also been a Fungible Token Standard and Non-Fungible Token Standard implementations added to the [Sway-Libs](https://github.com/FuelLabs/sway-libs) repository before the creation of the [Sway-Standards](https://github.com/FuelLabs/sway-standards) repository. The introduction of this standard in the [Sway-Standards](https://github.com/FuelLabs/sway-standards) repository will deprecate the Sway-Libs Fungible Token Standard. -# Specification +## Specification -## Required Public Functions +### Required Public Functions The following functions MUST be implemented to follow the SRC-20 standard: -### `fn total_assets() -> u64` +#### `fn total_assets() -> u64` This function MUST return the total number of individual assets for a contract. -### `fn total_supply(asset: AssetId) -> Option` +#### `fn total_supply(asset: AssetId) -> Option` This function MUST return the total supply of coins for an asset. This function MUST return `Some` for any assets minted by the contract. -### `fn name(asset: AssetId) -> Option` +#### `fn name(asset: AssetId) -> Option` This function MUST return the name of the asset, such as “Ether”. This function MUST return `Some` for any assets minted by the contract. -### `fn symbol(asset: AssetId) -> Option` +#### `fn symbol(asset: AssetId) -> Option` This function must return the symbol of the asset, such as “ETH”. This function MUST return `Some` for any assets minted by the contract. -### `fn decimals(asset: AssetId) -> Option` +#### `fn decimals(asset: AssetId) -> Option` This function must return the number of decimals the asset uses - e.g. 8, which means to divide the coin amount by 100000000 to get its user representation. This function MUST return `Some` for any assets minted by the contract. -## Non-Fungible Asset Restrictions +### Non-Fungible Asset Restrictions Non-Fungible Tokens (NFT) or Non-Fungible Assets on Fuel are Native Assets and thus follow the same standard as Fungible Native Assets with some restrictions. For a Native Asset on Fuel to be deemed an NFT, the following must be applied: -* Non-Fungible Assets SHALL have a total supply of one per asset. +* Non-Fungible Assets SHALL have a total supply of one per asset. * Non-Fungible Assets SHALL have a decimal of `0u8`. -# Rationale +## Rationale As the SRC-20 Native Asset Standard leverages Native Assets on Fuel, we do not require the implementation of certain functions such as transfer or approval. This is done directly within the FuelVM and there is no smart contract that requires updating of balances. As Fuel is UTXO based, any transfer events may be indexed on transaction receipts. Following this, we have omitted the inclusion of any transfer functions or events. The provided specification outlines only the functions necessary to implement fully functional native assets on the Fuel Network. Additional functionality and properties may be added as needed. -# Backwards Compatibility +## Backwards Compatibility This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). There are no other standards that require compatibility. -# Security Considerations +## Security Considerations This standard does not introduce any security concerns, as it does not call external contracts, nor does it define any mutations of the contract state. -# Example ABI +## Example ABI -```rust +```sway abi MyAsset { #[storage(read)] fn total_assets() -> u64; @@ -85,12 +78,20 @@ abi MyAsset { } ``` -# Example Implementation +## Example Implementation -## [Single Native Asset](../examples/src20-native-asset/multi_asset/src/multi_asset.sw) +### Single Native Asset Example of the SRC-20 implementation where a contract contains a single asset with one `SubId`. This implementation is recommended for users that intend to deploy a single asset with their contract. -## [Multi Native Asset](../examples/src20-native-asset/single_asset/src/single_asset.sw) +```sway +{{#include ../examples/src20-native-asset/multi_asset/src/multi_asset.sw}} +``` + +### Multi Native Asset Example of the SRC-20 implementation where a contract contains multiple assets with differing `SubId`s. This implementation is recommended for users that intend to deploy multiple assets with their contract. + +```sway +{{#include ../examples/src20-native-asset/single_asset/src/single_asset.sw}} +``` diff --git a/SRCs/src-3.md b/docs/src/src-3-minting-and-burning.md similarity index 59% rename from SRCs/src-3.md rename to docs/src/src-3-minting-and-burning.md index 0b9cb78f..53fd3525 100644 --- a/SRCs/src-3.md +++ b/docs/src/src-3-minting-and-burning.md @@ -1,60 +1,60 @@ -# Abstract +# SRC-3: Minting and Burning Native Assets -The following standard enables the minting and burning of native assets for any fungible assets within the Sway Language. It seeks to define mint and burn functions defined separately from the [SRC-20](./src-20.md) standard. +The following standard enables the minting and burning of native assets for any fungible assets within the Sway Language. It seeks to define mint and burn functions defined separately from the [SRC-20](./src-20-native-asset.md) standard. -# Motivation +## Motivation -The intent of this standard is to separate the extensions of minting and burning from the [SRC-20](./src-20.md) standard. +The intent of this standard is to separate the extensions of minting and burning from the [SRC-20](./src-20-native-asset.md) standard. -# Prior Art +## Prior Art -Minting and burning were initially added to the [SRC-20](./src-20.md) standard. +Minting and burning were initially added to the [SRC-20](./src-20-native-asset.md) standard. -# Specification +## Specification -## Required Public Functions +### Required Public Functions The following functions MUST be implemented to follow the SRC-3 standard: -### `fn mint(recipient: Identity, sub_id: SubId, amount: u64)` +#### `fn mint(recipient: Identity, sub_id: SubId, amount: u64)` -This function MUST mint `amount` coins with sub-identifier `sub_id` and transfer them to the `recipient`. +This function MUST mint `amount` coins with sub-identifier `sub_id` and transfer them to the `recipient`. This function MAY contain arbitrary conditions for minting, and revert if those conditions are not met. -##### Arguments +##### Mint Arguments * `recipient` - The `Identity` to which the newly minted asset is transferred to. * `sub_id` - The sub-identifier of the asset to mint. * `amount` - The quantity of coins to mint. -### `fn burn(sub_id: SubId, amount: u64)` +#### `fn burn(sub_id: SubId, amount: u64)` -This function MUST burn `amount` coins with the sub-identifier `sub_id` and MUST ensure the `AssetId` of the asset is the sha-256 hash of `(ContractId, SubId)` for the implementing contract. -This function MUST ensure at least `amount` coins have been transferred to the implementing contract. -This function MUST update the total supply defined in the [SRC-20](./src-20.md) standard. +This function MUST burn `amount` coins with the sub-identifier `sub_id` and MUST ensure the `AssetId` of the asset is the sha-256 hash of `(ContractId, SubId)` for the implementing contract. +This function MUST ensure at least `amount` coins have been transferred to the implementing contract. +This function MUST update the total supply defined in the [SRC-20](./src-20-native-asset.md) standard. This function MAY contain arbitrary conditions for burning, and revert if those conditions are not met. -##### Arguments +##### Burn Arguments * `sub_id` - The sub-identifier of the asset to burn. * `amount` - The quantity of coins to burn. -# Rationale +## Rationale -This standard has been added to enable compatibility between applications and allow minting and burning native assets per use case. This standard has been separated from the [SRC-20](./src-20.md) standard to allow for the minting and burning for all fungible assets, irrelevant of whether they are [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) or not. +This standard has been added to enable compatibility between applications and allow minting and burning native assets per use case. This standard has been separated from the [SRC-20](./src-20-native-asset.md) standard to allow for the minting and burning for all fungible assets, irrelevant of whether they are [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) or not. -# Backwards Compatibility +## Backwards Compatibility -This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) ensuring its compatibility with the [SRC-20](./src-20.md) standard. +This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) ensuring its compatibility with the [SRC-20](./src-20-native-asset.md) standard. -# Security Considerations +## Security Considerations This standard may introduce security considerations if no checks are implemented to ensure the calling of the `mint()` function is deemed valid or permitted. Checks are highly encouraged. -The burn function may also introduce a security consideration if the total supply within the [SRC-20](./src-20.md) standard is not modified. +The burn function may also introduce a security consideration if the total supply within the [SRC-20](./src-20-native-asset.md) standard is not modified. -# Example ABI +## Example ABI -```rust +```sway abi MySRC3Asset { #[storage(read, write)] fn mint(recipient: Identity, sub_id: SubId, amount: u64); @@ -64,12 +64,20 @@ abi MySRC3Asset { } ``` -# Example Implementation +## Example Implementation -## [Single Native Asset](../examples/src3-mint-burn/single_asset/src/single_asset.sw) +### Single Native Asset Example of the SRC-3 implementation where a contract only mints a single asset with one `SubId`. -## [Multi Native Asset](../examples/src3-mint-burn/multi_asset/src/multi_asset.sw) +```sway +{{#include ../examples/src3-mint-burn/single_asset/src/single_asset.sw}} +``` + +### Multi Native Asset -Example of the SRC-3 implementation where a contract mints multiple assets with differing `SubId`s. +Example of the SRC-3 implementation where a contract mints multiple assets with differing `SubId` values. + +```sway +{{#include ../examples/src3-mint-burn/multi_asset/src/multi_asset.sw}} +``` diff --git a/SRCs/src-5.md b/docs/src/src-5-ownership.md similarity index 72% rename from SRCs/src-5.md rename to docs/src/src-5-ownership.md index f8333d6f..4cea7a3b 100644 --- a/SRCs/src-5.md +++ b/docs/src/src-5-ownership.md @@ -1,42 +1,38 @@ -

- - - SRC-5 logo - -

+# SRC-5: Ownership -# Abstract +The following standard intends to enable the use of administrators or owners in Sway contracts. -The following standard intends to enable the use of administrators or owners in Sway contracts. - -# Motivation +## Motivation The standard seeks to provide a method for restricting access to particular users within a Sway contract. -# Prior Art +## Prior Art -The [sway-libs](https://github.com/FuelLabs/sway-libs) repository contains a pre-existing Ownership library. +The [sway-libs](https://github.com/FuelLabs/sway-libs) repository contains a pre-existing Ownership library. Ownership libraries exist for other ecosystems such as OpenZeppelin's [Ownership library](https://docs.openzeppelin.com/contracts/2.x/api/ownership). -# Specification +## Specification -## State +### State There SHALL be 3 states for any library implementing an ownership module in the following order: -### - `Uninitialized` +#### `Uninitialized` + The `Uninitialized` state SHALL be set as the initial state if no owner or admin is set. The `Uninitialized` state MUST be used when an owner or admin MAY be set in the future. -### - `Initialized` +#### `Initialized` + The `Initialized` state SHALL be set as the state if an owner or admin is set with an associated `Identity` type. -### - `Revoked` +#### `Revoked` + The `Revoked` state SHALL be set when there is no owner or admin and there SHALL NOT be one set in the future. Example: -```rust +```sway pub enum State { Uninitialized: (), Initialized: Identity, @@ -44,49 +40,59 @@ pub enum State { } ``` -## Functions +### Functions The following functions MUST be implemented to follow the SRC-5 standard: -### `fn owner() -> State` +#### `fn owner() -> State` + This function SHALL return the current state of ownership for the contract where `State` is either `Uninitialized`, `Initialized`, or `Revoked`. -## Errors +### Errors There SHALL be error handling. -### - `NotOwner` +#### `NotOwner` + This error MUST be emitted when `only_owner()` reverts. -# Rationale +## Rationale In order to provide a universal method of administrative capabilities, SRC-5 will further enable interoperability between applications and provide safeguards for smart contract security. -# Backwards Compatability +## Backwards Compatibility The SRC-5 standard is compatible with the [sway-libs](https://github.com/FuelLabs/sway-libs) repository pre-existing Ownership library. Considerations should be made to best handle multiple owners or admins. There are no standards that SRC-5 requires to be compatible with. -# Security Considerations +## Security Considerations The SRC-5 standard should help improve the security of Sway contracts and their interoperability. -# Examples ABI +## Example ABI -```rust +```sway abi SRC5 { #[storage(read)] fn owner() -> State; } ``` -# Example Implementation +## Example Implementation -## [Uninitalized](../examples/src5-ownership/uninitialized_example/src/uninitialized_example.sw) +### Uninitalized Example of the SRC-5 implementation where a contract does not have an owner set at compile time with the intent to set it during runtime. -## [Initialized](../examples/src5-ownership/initialized_example/src/initialized_example.sw) +```sway +{{#include ../examples/src5-ownership/uninitialized_example/src/uninitialized_example.sw}} +``` + +### Initialized Example of the SRC-5 implementation where a contract has an owner set at compile time. + +```sway +{{#include ../examples/src5-ownership/initialized_example/src/initialized_example.sw}} +``` diff --git a/SRCs/src-6.md b/docs/src/src-6-vault.md similarity index 60% rename from SRCs/src-6.md rename to docs/src/src-6-vault.md index e63e933a..04ac75f0 100644 --- a/SRCs/src-6.md +++ b/docs/src/src-6-vault.md @@ -1,80 +1,73 @@ -

- - - SRC-6 logo - -

+# SRC-6: Vault -# Abstract +The following standard allows for the implementation of a standard API for asset vaults such as yield-bearing asset vaults or asset wrappers. This standard is an optional add-on to the [SRC-20](./src-20-native-asset.md) standard. -The following standard allows for the implementation of a standard API for asset vaults such as yield-bearing asset vaults or asset wrappers. This standard is an optional add-on to the [SRC-20](./src-20.md) standard. - -# Motivation +## Motivation Asset vaults allow users to own shares of variable amounts of assets, such as lending protocols which may have growing assets due to profits from interest. This pattern is highly useful and would greatly benefit from standardization. -# Prior Art +## Prior Art Asset vaults have been thoroughly explored on Ethereum and with [EIP 4626](https://eips.ethereum.org/EIPS/eip-4626) they have their own standard for it. However as Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) are fundamentally different from Ethereum's ERC-20 tokens, the implementation will differ, but the interface may be used as a reference. -# Specification +## Specification -## Required public functions +### Required public functions The following functions MUST be implemented to follow the SRC-6 standard. Any contract that implements the SRC-6 standard MUST implement the SRC-20 standard. -### `fn deposit(receiver: Identity, vault_sub_id: SubId) -> u64` +#### `fn deposit(receiver: Identity, vault_sub_id: SubId) -> u64` This function takes the `receiver` Identity and the SubId `vault_sub_id` of the sub-vault as an argument and returns the amount of shares minted to the `receiver`. - This function MUST allow for depositing of the underlying asset in exchange for pro-rata shares of the vault. - This function MAY reject arbitrary assets based on implementation and MUST revert if unaccepted assets are forwarded. - This function MAY reject any arbitrary `receiver` based on implementation and MUST revert in the case of a blacklisted or non-whitelisted `receiver`. -- This function MUST mint an asset representing the pro-rata share of the vault, with the SubId of the `sha256((underlying_asset, vault_sub_id))` digest, where `underlying_asset` is the AssetId of the deposited asset and the `vault_sub_id` is the id of the vault. +- This function MUST mint an asset representing the pro-rata share of the vault, with the SubId of the `sha256((underlying_asset, vault_sub_id))` digest, where `underlying_asset` is the `AssetId` of the deposited asset and the `vault_sub_id` is the id of the vault. - This function MUST emit a `Deposit` log. - This function MUST return the amount of minted shares. -### `fn withdraw(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> u64` +#### `fn withdraw(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> u64` -This function takes the `receiver` Identity, the `underlying_asset` AssetId, and the `vault_sub_id` of the sub vault, as arguments and returns the amount of assets transferred to the `receiver`. +This function takes the `receiver` Identity, the `underlying_asset` `AssetId`, and the `vault_sub_id` of the sub vault, as arguments and returns the amount of assets transferred to the `receiver`. - This function MUST allow for redeeming of the vault shares in exchange for a pro-rata amount of the underlying assets. -- This function MUST revert if any AssetId other than the AssetId representing the underlying asset's shares for the given sub vault at `vault_sub_id` is forwarded. (i.e. transferred share's AssetId must be equal to `AssetId::new(ContractId::this(), sha256((underlying_asset, vault_sub_id))`) +- This function MUST revert if any `AssetId` other than the `AssetId` representing the underlying asset's shares for the given sub vault at `vault_sub_id` is forwarded. (i.e. transferred share's `AssetId` must be equal to `AssetId::new(ContractId::this(), sha256((underlying_asset, vault_sub_id))`) - This function MUST burn the received shares. - This function MUST emit a `Withdraw` log. - This function MUST return amount of assets transferred to the receiver. -### `fn managed_assets(underlying_asset: AssetId, vault_sub_id: SubId) -> u64` +#### `fn managed_assets(underlying_asset: AssetId, vault_sub_id: SubId) -> u64` -This function returns the total assets under management by vault. Includes assets controlled by the vault but not directly possessed by vault. It takes the `underlying_asset` AssetId and the `vault_sub_id` of the sub vault as arguments and returns the total amount of assets of AssetId under management by vault. +This function returns the total assets under management by vault. Includes assets controlled by the vault but not directly possessed by vault. It takes the `underlying_asset` `AssetId` and the `vault_sub_id` of the sub vault as arguments and returns the total amount of assets of `AssetId` under management by vault. -- This function MUST return total amount of assets of `underlying_asset` AssetId under management by vault. -- This function MUST return 0 if there are no assets of `underlying_asset` AssetId under management by vault. +- This function MUST return total amount of assets of `underlying_asset` `AssetId` under management by vault. +- This function MUST return 0 if there are no assets of `underlying_asset` `AssetId` under management by vault. - This function MUST NOT revert under any circumstances. -### `fn max_depositable(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> Option` +#### `fn max_depositable(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> Option` -This is a helper function for getting the maximum amount of assets that can be deposited. It takes the hypothetical `receiver` Identity, the `underlying_asset` AssetId, and the `vault_sub_id` SubId of the sub vault as an arguments and returns the maximum amount of assets that can be deposited into the contract, for the given asset. +This is a helper function for getting the maximum amount of assets that can be deposited. It takes the hypothetical `receiver` `Identity`, the `underlying_asset` `AssetId`, and the `vault_sub_id` `SubId` of the sub vault as an arguments and returns the maximum amount of assets that can be deposited into the contract, for the given asset. - This function MUST return the maximum amount of assets that can be deposited into the contract, for the given `underlying_asset`, if the given `vault_sub_id` vault exists. - This function MUST return an `Some(amount)` if the given `vault_sub_id` vault exists. - This function MUST return an `None` if the given `vault_sub_id` vault does not exist. - This function MUST account for both global and user specific limits. For example: if deposits are disabled, even temporarily, MUST return 0. -### `fn max_withdrawable(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> Option` +#### `fn max_withdrawable(receiver: Identity, underlying_asset: AssetId, vault_sub_id: SubId) -> Option` -This is a helper function for getting maximum withdrawable. It takes the hypothetical `receiver` Identity, the `underlying_asset` AssetId, and the `vault_sub_id` SubId of the sub vault as an argument and returns the maximum amount of assets that can be withdrawn from the contract, for the given asset. +This is a helper function for getting maximum withdrawable. It takes the hypothetical `receiver` `Identity`, the `underlying_asset` `AssetId`, and the `vault_sub_id` SubId of the sub vault as an argument and returns the maximum amount of assets that can be withdrawn from the contract, for the given asset. - This function MUST return the maximum amount of assets that can be withdrawn from the contract, for the given `underlying_asset`, if the given `vault_sub_id` vault exists. - This function MUST return an `Some(amount)` if the given `vault_sub_id` vault exists. - This function MUST return an `None` if the given `vault_sub_id` vault does not exist. - This function MUST account for global limits. For example: if withdrawals are disabled, even temporarily, MUST return 0. -## Required logs +### Required logs The following logs MUST be emitted at the specified occasions. -### `Deposit` +#### `Deposit` `caller` has called the `deposit()` method sending `deposited_amount` assets of the `underlying_asset` Asset to the subvault of `vault_sub_id`, in exchange for `minted_shares` shares sent to the receiver `receiver`. @@ -82,31 +75,31 @@ The `Deposit` struct MUST be logged whenever new shares are minted via the `depo The `Deposit` log SHALL have the following fields. -#### - `caller`: Identity +**`caller`: `Identity`** -The `caller` field MUST represent the Identity which called the deposit function. +The `caller` field MUST represent the `Identity` which called the deposit function. -#### - `receiver`: Identity +**`receiver`: `Identity`** -The `receiver` field MUST represent the Identity which received the vault shares. +The `receiver` field MUST represent the `Identity` which received the vault shares. -#### - `underlying_asset`: AssetId +**`underlying_asset`: `AssetId`** -The `underlying_asset` field MUST represent the AssetId of the asset which was deposited into the vault. +The `underlying_asset` field MUST represent the `AssetId` of the asset which was deposited into the vault. -#### - `vault_sub_id`: SubId +**`vault_sub_id`: `SubId`** -The `vault_sub_id` field MUST represent the SubId of the vault which was deposited into. +The `vault_sub_id` field MUST represent the `SubId` of the vault which was deposited into. -#### - `deposited_amount`: u64 +**`deposited_amount`: `u64`** -The `deposited_amount` field MUST represent the u64 amount of assets deposited into the vault. +The `deposited_amount` field MUST represent the `u64` amount of assets deposited into the vault. -#### - `minted_shares`: u64 +**`minted_shares`: `u64`** -The `minted_shares` field MUST represent the u64 amount of shares minted. +The `minted_shares` field MUST represent the `u64` amount of shares minted. -### `Withdraw` +#### `Withdraw` `caller` has called the `withdraw()` method sending `burned_shares` shares in exchange for `withdrawn_amount` assets of the `underlying_asset` Asset from the subvault of `vault_sub_id` to the receiver `receiver`. @@ -114,43 +107,43 @@ The `Withdraw` struct MUST be logged whenever shares are redeemed for assets via The `Withdraw` log SHALL have the following fields. -#### - `caller`: Identity +**`caller`: `Identity`** The `caller` field MUST represent the Identity which called the withdraw function. -#### - `receiver`: Identity +**`receiver`: `Identity`** The `receiver` field MUST represent the Identity which received the withdrawn assets. -#### - `underlying_asset`: AssetId +**`underlying_asset`: `AssetId`** -The `underlying_asset` field MUST represent the AssetId of the asset that was withdrawn. +The `underlying_asset` field MUST represent the `AssetId` of the asset that was withdrawn. -#### - `vault_sub_id`: SubId +**`vault_sub_id`: `SubId`** The `vault_sub_id` field MUST represent the SubId of the vault from which was withdrawn. -#### - `withdrawn_amount`: u64 +**`withdrawn_amount`: `u64`** -The `withdrawn_amount` field MUST represent the u64 amount of coins withdrawn. +The `withdrawn_amount` field MUST represent the `u64` amount of coins withdrawn. -#### - `burned_shares`: u64 +**`burned_shares`: `u64`** -The `burned_shares` field MUST represent the u64 amount of shares burned. +The `burned_shares` field MUST represent the `u64` amount of shares burned. -# Rationale +## Rationale The ABI discussed covers the known use cases of asset vaults while allowing safe implementations. -# Backwards Compatibility +## Backwards Compatibility -This standard is fully compatible with the [SRC-20 standard](./src-20.md). +This standard is fully compatible with the [SRC-20 standard](./src-20-native-asset.md). -# Security Considerations +## Security Considerations Incorrect implementation of asset vaults could allow attackers to steal underlying assets. It is recommended to properly audit any code using this standard to ensure exploits are not possible. -# Example ABI +## Example ABI ```sway abi SRC6 { @@ -173,16 +166,28 @@ abi SRC6 { } ``` -# Example Implementation +## Example Implementation + +### Multi Asset Vault + +A basic implementation of the vault standard that supports any number of sub vaults being created for every `AssetId`. + +```sway +{{#include ../examples/src6-vault/multi_asset_vault/src/main.sw}} +``` -## [Multi Asset Vault](../examples/src6-vault/multi_asset_vault) +### Single Asset Vault -A basic implementation of the vault standard that supports any number of sub vaults being created for every AssetId. +A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single `AssetId`. -## [Single Asset Vault](../examples/src6-vault/single_asset_vault) +```sway +{{#include ../examples/src6-vault/single_asset_vault/src/main.sw}} +``` -A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single AssetId. +## Single Asset Single Sub Vault -## [Single Asset Single Sub Vault](../examples/src6-vault/single_asset_single_sub_vault) +A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single `AssetId`, and to a single Sub vault. -A basic implementation of the vault standard demonstrating how to restrict deposits and withdrawals to a single AssetId, and to a single Sub vault. +```sway +{{#include ../examples/src6-vault/single_asset_single_sub_vault/src/main.sw}} +``` diff --git a/SRCs/src-7.md b/docs/src/src-7-asset-metadata.md similarity index 74% rename from SRCs/src-7.md rename to docs/src/src-7-asset-metadata.md index d99a80de..0dcb7df2 100644 --- a/SRCs/src-7.md +++ b/docs/src/src-7-asset-metadata.md @@ -1,83 +1,84 @@ -

- - - SRC-7 logo - -

+# SRC-7: Arbitrary Native Asset Metadata -# Abstract +The following standard attempts to define the retrieval of on-chain arbitrary metadata for any [Native Asset](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-7 standard MUST implement the [SRC-20](./src-20-native-asset.md) standard. -The following standard attempts to define the retrieval of on-chain arbitrary metadata for any [Native Asset](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-7 standard MUST implement the [SRC-20](./src-20.md) standard. - -# Motivation +## Motivation The SRC-7 standard seeks to enable data-rich assets on the Fuel Network while maintaining compatibility between multiple assets minted by the same contract. The standard ensures type safety with the use of an `enum` and an `Option`. All metadata queries are done through a single function to facilitate cross-contract calls. -# Prior Art +## Prior Art -The use of generic metadata was originally found in the Sway-Lib's [NFT Library](https://github.com/FuelLabs/sway-libs/tree/v0.12.0/libs/nft) which did not use Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). This library has since been deprecated. +The use of generic metadata was originally found in the Sway-Lib's [NFT Library](https://github.com/FuelLabs/sway-libs/tree/v0.12.0/libs/nft) which did not use Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). This library has since been deprecated. -A previous definition for a metadata standard was written in the original edit of the now defunct [SRC-721](https://github.com/FuelLabs/sway-standards/issues/2). This has since been replaced with the [SRC-20](./src-20.md) standard as `SubId` was introduced to enable multiple assets to be minted from a single contract. +A previous definition for a metadata standard was written in the original edit of the now defunct [SRC-721](https://github.com/FuelLabs/sway-standards/issues/2). This has since been replaced with the [SRC-20](./src-20-native-asset.md) standard as `SubId` was introduced to enable multiple assets to be minted from a single contract. The standard takes inspiration from [ENS's public resolver](https://docs.ens.domains/contract-api-reference/publicresolver) with the use of a `String` as the key. This should enable human-readable keys to help minimize errors and enable the standardization of certain keys, such as "image" as opposed to an `enum` or `u64` representation of keys. -We also take a look at existing common metadata practices such as [OpenSea's Metadata Standards](https://docs.opensea.io/docs/metadata-standards) and seek to stay backwards compatible with them while enabling more functionality. Through the combination of `String` keys and various return types, both pre-defined URIs or specific attributes may be stored and retrieved with the SRC-7 standard. +We also take a look at existing common metadata practices such as [OpenSea's Metadata Standards](https://docs.opensea.io/docs/metadata-standards) and seek to stay backwards compatible with them while enabling more functionality. Through the combination of `String` keys and various return types, both pre-defined URIs or specific attributes may be stored and retrieved with the SRC-7 standard. -# Specification +## Specification -## Metadata Type +### Metadata Type The following describes an enum that wraps various metadata types into a single return type. There SHALL be the following variants in the `Metadata` enum: -### - `B256` +#### `B256` The `B256` variant SHALL be used when the stored metadata for the corresponding `AssetId` and `Sting` key pair is of the `b256` type. -### - `Bytes` +#### `Bytes` The `Bytes` variant SHALL be used when the stored metadata for the corresponding `AssetId` and `String` key pair is of the `Bytes` type. The `Bytes` variant should be used when storing custom data such as but not limited to structs and enums. -### - `Int` +#### `Int` The `Int` variant SHALL be used when the stored metadata for the corresponding `AssetId` and `Sting` key pair is of the `u64` type. -### - `String` +#### `String` -The `String` variant SHALL be used when the stored metadata for the corresponding `AssetId` and `String` key pair is of the `String` type. The `String` variant MUST be used when a URI is required but MAY contain any arbitrary `String` data. +The `String` variant SHALL be used when the stored metadata for the corresponding `AssetId` and `String` key pair is of the `String` type. The `String` variant MUST be used when a URI is required but MAY contain any arbitrary `String` data. -## Required Functions +### Required Functions -### `fn metadata(asset: AssetId, key: String) -> Option` +#### `fn metadata(asset: AssetId, key: String) -> Option` This function MUST return valid metadata for the corresponding `asset` and `key`, where the data is either a `B256`, `Bytes`, `Int`, or `String` variant. If the asset does not exist or no metadata exists, the function MUST return `None`. -# Rationale +## Rationale -The SRC-7 standard should allow for data-rich assets to interact with one another in a safe manner. +The SRC-7 standard should allow for data-rich assets to interact with one another in a safe manner. -# Backwards Compatibility +## Backwards Compatibility -This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) and the [SRC-20](./src-20.md) standard. It also maintains compatibility with existing standards in other ecosystems. +This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) and the [SRC-20](./src-20-native-asset.md) standard. It also maintains compatibility with existing standards in other ecosystems. -# Security Considerations +## Security Considerations This standard does not introduce any security concerns, as it does not call external contracts, nor does it define any mutations of the contract state. -# Example ABI +## Example ABI -```rust +```sway abi SRC7Metadata { #[storage(read)] fn metadata(asset: AssetId, key: String) -> Option; } ``` -# Example Implementation +## Example Implementation -## [Single Native Asset](../examples/src7-metadata/single_asset/src/single_asset.sw) +### Single Native Asset Example of the SRC-7 implementation where metadata exists for only a single asset with one `SubId`. -## [Mutli Native Asset](../examples/src7-metadata/multi_asset/src/multi_asset.sw) +```sway +{{#include ../examples/src7-metadata/single_asset/src/single_asset.sw}} +``` + +### Multi Native Asset -Example of the SRC-7 implementation where metadata exists for multiple assets with differing `SubId`s. +Example of the SRC-7 implementation where metadata exists for multiple assets with differing `SubId` values. + +```sway +{{#include ../examples/src7-metadata/multi_asset/src/multi_asset.sw}} +``` diff --git a/SRCs/src-8.md b/docs/src/src-8-bridged-asset.md similarity index 83% rename from SRCs/src-8.md rename to docs/src/src-8-bridged-asset.md index cc336b9d..5409998c 100644 --- a/SRCs/src-8.md +++ b/docs/src/src-8-bridged-asset.md @@ -1,26 +1,18 @@ -

- - - SRC-8 logo - -

+# SRC-8: Bridged Asset +The following standard attempts to define the retrieval of relevant on-chain metadata for any bridged [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-8 standard MUST implement the [SRC-7](./src-7-asset-metadata.md) and [SRC-20](./src-20-native-asset.md) standards. -# Abstract - -The following standard attempts to define the retrieval of relevant on-chain metadata for any bridged [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-8 standard MUST implement the [SRC-7](./src-7.md) and [SRC-20](./src-20.md) standards. - -# Motivation +## Motivation The SRC-8 standard seeks to enable relevant data for bridged assets on the Fuel Network. This data includes the origin chain, address, ID, decimals, and any arbitrary data. All metadata queries are done through a single function to facilitate cross-contract calls. -# Prior Art +## Prior Art -The use of generic metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) is defined in the [SRC-7](./src-7.md) standard. This standard integrates into the existing [SRC-7](./src-7.md) standard. +The use of generic metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) is defined in the [SRC-7](./src-7-asset-metadata.md) standard. This standard integrates into the existing [SRC-7](./src-7-asset-metadata.md) standard. -# Specification +## Specification -## Asset Creation +### Asset Creation The `SubId` of the asset MUST be the digest of the `sha256(origin_chain_id, origin_asset_address, origin_asset_id)` hash where: @@ -28,45 +20,45 @@ The `SubId` of the asset MUST be the digest of the `sha256(origin_chain_id, orig - `origin_asset_address` is a `b256` of the asset's address on the chain where the asset was originally minted. - `origin_asset_id` is a `b256` of the asset's ID such as an NFT's ID on the chain where the asset was originally minted. IF there is no ID, `b256::zero()` SHALL be used. -## SRC-20 Metadata +### SRC-20 Metadata -Any bridged assets MUST use the name and symbol of the asset on the chain where the asset was originally minted. +Any bridged assets MUST use the name and symbol of the asset on the chain where the asset was originally minted. -## SRC-7 Metadata +### SRC-7 Metadata -### - `bridged:chain` +#### `bridged:chain` The key `bridged:chain` SHALL return an `String` variant of the chain ID where the asset was originally minted. -### - `bridged:address` +#### `bridged:address` The key `bridged:address` SHALL return a `B256` variant of the asset's address on the chain where the asset was originally minted. Native assets of a chain that do not have an address such as Ether on Ethereum SHALL use `b256::zero()`. -### - `bridged:id` +#### `bridged:id` The key `bridged:id` MAY return a `B256` variant of the asset's ID such as an NFT's ID on the chain where the asset was originally minted. IF there is no ID, `None` SHALL be returned. -### - `bridged:decimals` +#### `bridged:decimals` The key `bridged:decimals` MAY return an `Int` variant of the asset's decimals on the chain where the asset was originally minted. IF there are no decimals, `None` SHALL be returned. -# Rationale +## Rationale The SRC-8 standard should allow for data on any bridged assets on the Fuel Network. This standard builds off existing standards and should allow other contracts to query any relevant information on the bridged asset. -# Backwards Compatibility +## Backwards Compatibility -This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets), the [SRC-20](./src-20.md) standard, and the [SRC-7](./src-7.md) standard. +This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets), the [SRC-20](./src-20-native-asset.md) standard, and the [SRC-7](./src-7-asset-metadata.md) standard. The standard is also compatible with both tokens and NFTs native to other ecosystems by introducing a token ID element of the original chain. -# Security Considerations +## Security Considerations This standard does not call external contracts, nor does it define any mutations of the contract state. -# Example +## Example -```rust +```sway impl SRC7 for Contract { fn metadata(asset: AssetId, key: String) -> Option { if (asset != AssetId::default()) { @@ -126,4 +118,4 @@ impl SRC20 for Contract { } } } -``` \ No newline at end of file +``` diff --git a/SRCs/src-9.md b/docs/src/src-9-metadata-keys.md similarity index 82% rename from SRCs/src-9.md rename to docs/src/src-9-metadata-keys.md index a355ba10..9558b3cd 100644 --- a/SRCs/src-9.md +++ b/docs/src/src-9-metadata-keys.md @@ -1,360 +1,363 @@ -

- - - SRC-9 logo - -

+# SRC-9: Native Asset -# Abstract +The following standard attempts to define the keys of relevant on-chain metadata for any [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-9 standard MUST implement the [SRC-7](./src-7-asset-metadata.md) and [SRC-20](./src-20-native-asset.md) standards. This is a living standard where revisions may be made as the ecosystem evolves. -The following standard attempts to define the keys of relevant on-chain metadata for any [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets). Any contract that implements the SRC-9 standard MUST implement the [SRC-7](./src-7.md) and [SRC-20](./src-20.md) standards. This is a living standard where revisions may be made as the ecosystem evolves. - -# Motivation +## Motivation The SRC-9 standard seeks to enable relevant data for assets on the Fuel Network. This data may include images, text, contact, or all of the above. All metadata queries are done through a single function to facilitate cross-contract calls. -# Prior Art +## Prior Art -The use of generic metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) is defined in the [SRC-7](./src-7.md) standard. This standard integrates into the existing [SRC-7](./src-7.md) standard. +The use of generic metadata for [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets) is defined in the [SRC-7](./src-7-asset-metadata.md) standard. This standard integrates into the existing [SRC-7](./src-7-asset-metadata.md) standard. -# Specification +## Specification The following keys are reserved for the SRC-9 standard. Use of the keys should follow the SRC-9 specification. -All keys SHALL use snake case. +All keys SHALL use snake case. -## Social +### Social The social prefix SHALL be used for any social media platform and SHALL return usernames. Any social media metadata keys SHALL follow the following syntax `social:site` where: + - The `social` keyword must be prepended to denote this is a social platform - The `site` keyword must be the website or platform of the social -#### - `social:discord` +#### `social:discord` The key `social:discord` SHALL return a `String` variant of a username for the Discord platform. -#### - `social:facebook` +#### `social:facebook` The key `social:facebook` SHALL return a `String` variant of a username for the Facebook platform. -#### - `social:farcaster` +#### `social:farcaster` The key `social:farcaster` SHALL return a `String` variant of a username for the Farcaster platform. -#### - `social:friend.tech` +#### `social:friend.tech` The key `social:friend.tech` SHALL return a `String` variant of a username for the Friend.tech platform. -#### - `social:github` +#### `social:github` The key `social:github` SHALL return a `String` variant of a username for the Github platform. -#### - `social:instagram` +#### `social:instagram` The key `social:instagram` SHALL return a `String` variant of a username for the Instagram platform. -#### - `social:lens` +#### `social:lens` The key `social:lens` SHALL return a `String` variant of a username for the Lens Protocol. -#### - `social:linkedin` +#### `social:linkedin` The key `social:linkedin` SHALL return a `String` variant of a username for the LinkedIn platform. -#### - `social:reddit` +#### `social:reddit` The key `social:reddit` SHALL return a `String` variant of a username for the Reddit platform. -#### - `social:signal` +#### `social:signal` The key `social:signal` SHALL return a `String` variant of a username for the Signal platform. -#### - `social:telegram` +#### `social:telegram` The key `social:telegram` SHALL return a `String` variant of a username for the Telegram platform. -#### - `social:tiktok` +#### `social:tiktok` The key `social:tiktok` SHALL return a `String` variant of a username for the TikTok platform. -#### - `social:x` +#### `social:x` The key `social:x` SHALL return a `String` variant of a username for the X or formerly Twitter platform. -#### - `social:wechat` +#### `social:wechat` The key `social:wechat` SHALL return a `String` variant of a username for the WeChat platform. -#### - `social:whatsapp` +#### `social:whatsapp` The key `social:whatsapp` SHALL return a `String` variant of a username for the WhatsApp platform. -#### - `social:youtube` +#### `social:youtube` The key `social:youtube` SHALL return a `String` variant of a username for the YouTube platform. -## Contact +### Contact The `contact` prefix SHALL be used for any contact information on a particular project's team for an asset. Any contact information metadata keys SHALL follow the following syntax `contract:type` where: + - The `contact` keyword must be prepended to denote this is contact information - The `type` keyword must be the method of contact -The key SHALL use snake case. +The key SHALL use snake case. -#### - `contact:email` +#### `contact:email` The key `contact:email` SHALL return a `String` variant of an email. -#### - `contact:mailing` +#### `contact:mailing` The key `contact:mailing` SHALL return a `String` variant of a mailing address. All mailing addresses MUST follow the UPU addressing format. -#### - `contact:phone` +#### `contact:phone` The key `contact:phone` SHALL return a `String` variant of a phone number. All phone numbers SHALL follow the E.164 standard. -#### - `contact:company` +#### `contact:company` The key `contact:company` SHALL return a `String` variant of a company name. -## External Links +### External Links The `link` prefix SHALL be used for any external webpage hyperlink associated with an asset. Any external webpage metadata keys SHALL follow the following syntax `link:site` where: + - The `link` keyword must be prepended to denote this is an external webpage - The `site` keyword must be an external website -#### - `link:home` +#### `link:home` The key `link:home` SHALL return a `String` variant of the asset's project homepage. -#### - `link:contact` +#### `link:contact` The key `link:contact` SHALL return a `String` variant of the asset's project contact information webpage. -#### - `link:docs` +#### `link:docs` The key `link:docs` SHALL return a `String` variant of the asset's project documentation webpage. -#### - `link:forum` +#### `link:forum` The key `link:forum` SHALL return a `String` variant of the asset's project forum webpage. -#### - `link:blog` +#### `link:blog` The key `link:blog` SHALL return a `String` variant of the asset's project blog. -#### - `link:linktree` +#### `link:linktree` The key `link:linktree` SHALL return a `String` variant of the asset's project linktree information webpage. -## Resources +### Resources The `res` prefix SHALL be used for any resources or general information on an asset. Any resource metadata keys SHALL follow the following syntax `rec:type` where: + - The `res` keyword must be prepended to denote this is a resource - The `type` keyword must be the type of resource -#### - `res:license` +#### `res:license` The key `res:license` SHALL return a `String` variant of the asset's project license. -#### - `res:tos` +#### `res:tos` The key `res:tos` SHALL return a `String` variant of the asset's project Terms of Service. -#### - `res:author` +#### `res:author` The key `res:author` SHALL return a `String` variant of the asset's project author. This MAY be a full name or pseudonym. -#### - `res:about` +#### `res:about` The key `res:about` SHALL return a `String` variant about the asset's project up to 2048 characters. -#### - `res:description` +#### `res:description` The key `res:description` SHALL return a `String` variant describing the asset's project up to 256 characters. -#### - `res:date` +#### `res:date` The key `res:date` SHALL return a `Int` variant of a UNIX timestamp. -#### - `res:block` +#### `res:block` The key `res:block` SHALL return a `Int` variant of a block number. -## Images +### Images The `image` prefix SHALL be used for any image files associated with a singular asset. Any image metadata keys SHALL follow the following syntax `image:type` where: + - The `image` keyword must be prepended to denote this is an image - The `type` keyword must be the file type of the image -#### - `image:svg` +#### `image:svg` The key `image:svg` SHALL return a `String` variant of an SVG image. -#### - `image:png` +#### `image:png` The key `image:png` SHALL return a `String` variant of a URI for a PNG image. -#### - `image:jpeg` +#### `image:jpeg` The key `image:jpeg` SHALL return a `String` variant of a URI for a JPEG image. -#### - `image:webp` +#### `image:webp` The key `image:webp` SHALL return a `String` variant of a URI for a WebP image. -#### - `image:gif` +#### `image:gif` The key `image:gif` SHALL return a `String` variant of a URI for a GIF image. -#### - `image:heif` +#### `image:heif` The key `image:heif` SHALL return a `String` variant of a URI for a HEIF image. -## Video +### Video The `video` prefix SHALL be used for any video files associated with a singular asset. Any video metadata keys SHALL follow the following syntax `video:type` where: + - The `video` keyword must be prepended to denote this is a video - The `type` keyword must be the file type of the video -#### - `video:mp4` +#### `video:mp4` The key `video:mp4` SHALL return a `String` variant of a URI for an MP4 video. -#### - `video:webm` +#### `video:webm` The key `video:webm` SHALL return a `String` variant of a URI for a WebM video. -#### - `video:m4v` +#### `video:m4v` The key `video:m4v` SHALL return a `String` variant of a URI for a M4V video. -#### - `video:ogv` +#### `video:ogv` The key `video:ogv` SHALL return a `String` variant of a URI for an OGV video. -#### - `video:ogg` +#### `video:ogg` The key `video:ogg` SHALL return a `String` variant of a URI for an OGG video. -## Audio +### Audio The `audio` prefix SHALL be used for any audio files associated with a singular asset. Any audio metadata keys SHALL follow the following syntax `audio:type` where: + - The `audio` keyword must be prepended to denote this is audio metadata - The `type` keyword must be the file type of the audio -#### - `audio:mp3` +#### `audio:mp3` The key `audio:mp3` SHALL return a `String` variant of a URI for an MP3 file. -#### - `audio:wav` +#### `audio:wav` The key `audio:wav` SHALL return a `String` variant of a URI for a WAV file. -#### - `audio:oga` +#### `audio:oga` The key `audio:oga` SHALL return a `String` variant of a URI for an OGA file. -## Media +### Media The `media` prefix SHALL be used for any media associated with a particular singular asset. Any media metadata keys SHALL follow the following syntax `media:type` where: + - The `media` keyword must be prepended to denote this is a video - The `type` keyword must be the file type of the media -#### - `media:gltf` +#### `media:gltf` The key `media:gltf` SHALL return a `String` variant of a URI for a glTF file. -#### - `media:glb` +#### `media:glb` The key `media:glb` SHALL return a `String` variant of a URI for a GLB file. -## Logos +### Logos The `logo` prefix SHALL be used for any images associated with a particular asset or project. Any logo metadata keys SHALL follow the following syntax `logo:type` where: + - The `logo` keyword must be prepended to denote this is a logo - The `type` keyword must be the type of logo -#### - `logo:svg` +#### `logo:svg` The key `logo:svg` SHALL return a `String` variant of an SVG image of a logo. -#### - `logo:svg_light` +#### `logo:svg_light` The key `logo:svg_light` SHALL return a `String` variant of an SVG image of a logo for light themes. -#### - `logo:svg_dark` +#### `logo:svg_dark` The key `logo:svg_dark` SHALL return a `String` variant of an SVG image of a logo for dark themes. -#### - `logo:small_light` +#### `logo:small_light` The key `logo:small_light` SHALL return a `String` variant of a URI for a 32x32 PNG image of a logo for light themes. -#### - `logo:small_dark` +#### `logo:small_dark` The key `logo:small_dark` SHALL return a `String` variant of a URI for a 32x32 PNG image of a logo for dark themes. -#### - `logo:medium_light` +#### `logo:medium_light` The key `logo:medium_light` SHALL return a `String` variant of a URI for a 256x256 PNG image of a logo for light themes. -#### - `logo:medium_dark` +#### `logo:medium_dark` The key `logo:medium_dark` SHALL return a `String` variant of a URI for a 256x256 PNG image of a logo for dark themes. -#### - `logo:large_light` +#### `logo:large_light` The key `logo:large_light` SHALL return a `String` variant of a URI for a 1024x1024 PNG image of a logo for light themes. -#### - `logo:large_dark` +#### `logo:large_dark` The key `logo:large_dark` SHALL return a `String` variant of a URI for a 1024x1024 PNG image of a logo for dark themes. -## Attributes +### Attributes The `attr` prefix SHALL be used for any attributes associated with a singular asset. Any attribute metadata keys SHALL follow the following syntax `attr:type` where: + - The `attr` keyword must be prepended to denote this is an attribute - The `type` keyword must be the type of attribute There are no standardized types of attributes. Example: `attr:eyes`. -# Rationale +## Rationale The SRC-9 standard should allow for standardized keys for metadata on the Fuel Network. This standard builds off existing standards and should allow other contracts to query any relevant information on the asset. -# Backwards Compatibility +## Backwards Compatibility -This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets), the [SRC-20](./src-20.md) standard, and the [SRC-7](./src-7.md) standard. +This standard is compatible with Fuel's [Native Assets](https://docs.fuel.network/docs/sway/blockchain-development/native_assets), the [SRC-20](./src-20-native-asset.md) standard, and the [SRC-7](./src-7-asset-metadata.md) standard. -# Security Considerations +## Security Considerations This standard does not call external contracts, nor does it define any mutations of the contract state. -# Example +## Example -```rust +```sway impl SRC7 for Contract { fn metadata(asset: AssetId, key: String) -> Option { if (asset != AssetId::default()) {