From 366aa388e4f62e06fa8b172c2c7a8a295aa81c98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Lillo=20Igualada?= Date: Wed, 23 Nov 2022 20:52:41 +0100 Subject: [PATCH] Include contracts docs --- docs/ExampleToken/ExampleToken.md | 160 ++++++++++++++++++ .../ExampleToken_Administrator.md | 33 ++++ docs/ExampleToken/ExampleToken_Burner.md | 24 +++ docs/ExampleToken/ExampleToken_Minter.md | 34 ++++ docs/ExampleToken/ExampleToken_Vault.md | 96 +++++++++++ docs/FungibleToken/FungibleToken.md | 121 +++++++++++++ docs/FungibleToken/FungibleToken_Balance.md | 40 +++++ docs/FungibleToken/FungibleToken_Provider.md | 41 +++++ docs/FungibleToken/FungibleToken_Receiver.md | 27 +++ docs/FungibleToken/FungibleToken_Vault.md | 49 ++++++ .../FungibleTokenMetadataViews.md | 133 +++++++++++++++ .../FungibleTokenMetadataViews_FTDisplay.md | 30 ++++ .../FungibleTokenMetadataViews_FTVaultData.md | 34 ++++ .../FungibleTokenMetadataViews_FTView.md | 22 +++ .../FungibleTokenSwitchboard.md | 91 ++++++++++ .../FungibleTokenSwitchboard_Switchboard.md | 120 +++++++++++++ ...gibleTokenSwitchboard_SwitchboardPublic.md | 35 ++++ 17 files changed, 1090 insertions(+) create mode 100644 docs/ExampleToken/ExampleToken.md create mode 100644 docs/ExampleToken/ExampleToken_Administrator.md create mode 100644 docs/ExampleToken/ExampleToken_Burner.md create mode 100644 docs/ExampleToken/ExampleToken_Minter.md create mode 100644 docs/ExampleToken/ExampleToken_Vault.md create mode 100644 docs/FungibleToken/FungibleToken.md create mode 100644 docs/FungibleToken/FungibleToken_Balance.md create mode 100644 docs/FungibleToken/FungibleToken_Provider.md create mode 100644 docs/FungibleToken/FungibleToken_Receiver.md create mode 100644 docs/FungibleToken/FungibleToken_Vault.md create mode 100644 docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md create mode 100644 docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md create mode 100644 docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md create mode 100644 docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md create mode 100644 docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md create mode 100644 docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md create mode 100644 docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md diff --git a/docs/ExampleToken/ExampleToken.md b/docs/ExampleToken/ExampleToken.md new file mode 100644 index 00000000..353c3c66 --- /dev/null +++ b/docs/ExampleToken/ExampleToken.md @@ -0,0 +1,160 @@ +# Contract `ExampleToken` + +```cadence +contract ExampleToken { + + totalSupply: UFix64 + + VaultStoragePath: StoragePath + + ReceiverPublicPath: PublicPath + + VaultPublicPath: PublicPath + + AdminStoragePath: StoragePath +} +``` + + +Implemented Interfaces: + - `FungibleToken` + +## Structs & Resources + +### resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` +Each user stores an instance of only the Vault in their storage +The functions in the Vault and governed by the pre and post conditions +in FungibleToken when they are called. +The checks happen at runtime whenever a function is called. + +Resources can only be created in the context of the contract that they +are defined in, so there is no way for a malicious user to create Vaults +out of thin air. A special Minter resource needs to be defined to mint +new tokens. + +[More...](ExampleToken_Vault.md) + +--- + +### resource `Administrator` + +```cadence +resource Administrator { +} +``` + +[More...](ExampleToken_Administrator.md) + +--- + +### resource `Minter` + +```cadence +resource Minter { + + allowedAmount: UFix64 +} +``` +Resource object that token admin accounts can hold to mint new tokens. + +[More...](ExampleToken_Minter.md) + +--- + +### resource `Burner` + +```cadence +resource Burner { +} +``` +Resource object that token admin accounts can hold to burn tokens. + +[More...](ExampleToken_Burner.md) + +--- +## Functions + +### fun `createEmptyVault()` + +```cadence +func createEmptyVault(): Vault +``` +Function that creates a new Vault with a balance of zero +and returns it to the calling context. A user must call this function +and store the returned Vault in their storage in order to allow their +account to be able to receive deposits of this token type. + +Returns: The new Vault resource + +--- +## Events + +### event `TokensInitialized` + +```cadence +event TokensInitialized(initialSupply UFix64) +``` +The event that is emitted when the contract is created + +--- + +### event `TokensWithdrawn` + +```cadence +event TokensWithdrawn(amount UFix64, from Address?) +``` +The event that is emitted when tokens are withdrawn from a Vault + +--- + +### event `TokensDeposited` + +```cadence +event TokensDeposited(amount UFix64, to Address?) +``` +The event that is emitted when tokens are deposited to a Vault + +--- + +### event `TokensMinted` + +```cadence +event TokensMinted(amount UFix64) +``` +The event that is emitted when new tokens are minted + +--- + +### event `TokensBurned` + +```cadence +event TokensBurned(amount UFix64) +``` +The event that is emitted when tokens are destroyed + +--- + +### event `MinterCreated` + +```cadence +event MinterCreated(allowedAmount UFix64) +``` +The event that is emitted when a new minter resource is created + +--- + +### event `BurnerCreated` + +```cadence +event BurnerCreated() +``` +The event that is emitted when a new burner resource is created + +--- diff --git a/docs/ExampleToken/ExampleToken_Administrator.md b/docs/ExampleToken/ExampleToken_Administrator.md new file mode 100644 index 00000000..c375b5f0 --- /dev/null +++ b/docs/ExampleToken/ExampleToken_Administrator.md @@ -0,0 +1,33 @@ +# Resource `Administrator` + +```cadence +resource Administrator { +} +``` + +## Functions + +### fun `createNewMinter()` + +```cadence +func createNewMinter(allowedAmount UFix64): Minter +``` +Function that creates and returns a new minter resource + +Parameters: + - allowedAmount : _The maximum quantity of tokens that the minter could create_ + +Returns: The Minter resource that would allow to mint tokens + +--- + +### fun `createNewBurner()` + +```cadence +func createNewBurner(): Burner +``` +Function that creates and returns a new burner resource + +Returns: The Burner resource + +--- diff --git a/docs/ExampleToken/ExampleToken_Burner.md b/docs/ExampleToken/ExampleToken_Burner.md new file mode 100644 index 00000000..c5f0b761 --- /dev/null +++ b/docs/ExampleToken/ExampleToken_Burner.md @@ -0,0 +1,24 @@ +# Resource `Burner` + +```cadence +resource Burner { +} +``` + +Resource object that token admin accounts can hold to burn tokens. +## Functions + +### fun `burnTokens()` + +```cadence +func burnTokens(from FungibleToken.Vault) +``` +Function that destroys a Vault instance, effectively burning the tokens. + +Note: the burned tokens are automatically subtracted from the +total supply in the Vault destructor. + +Parameters: + - from : _The Vault resource containing the tokens to burn_ + +--- diff --git a/docs/ExampleToken/ExampleToken_Minter.md b/docs/ExampleToken/ExampleToken_Minter.md new file mode 100644 index 00000000..2f5ee343 --- /dev/null +++ b/docs/ExampleToken/ExampleToken_Minter.md @@ -0,0 +1,34 @@ +# Resource `Minter` + +```cadence +resource Minter { + + allowedAmount: UFix64 +} +``` + +Resource object that token admin accounts can hold to mint new tokens. + +### Initializer + +```cadence +func init(allowedAmount UFix64) +``` + + +## Functions + +### fun `mintTokens()` + +```cadence +func mintTokens(amount UFix64): ExampleToken.Vault +``` +Function that mints new tokens, adds them to the total supply, +and returns them to the calling context. + +Parameters: + - amount : _The quantity of tokens to mint_ + +Returns: The Vault resource containing the minted tokens + +--- diff --git a/docs/ExampleToken/ExampleToken_Vault.md b/docs/ExampleToken/ExampleToken_Vault.md new file mode 100644 index 00000000..1d398513 --- /dev/null +++ b/docs/ExampleToken/ExampleToken_Vault.md @@ -0,0 +1,96 @@ +# Resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` + +Each user stores an instance of only the Vault in their storage +The functions in the Vault and governed by the pre and post conditions +in FungibleToken when they are called. +The checks happen at runtime whenever a function is called. + +Resources can only be created in the context of the contract that they +are defined in, so there is no way for a malicious user to create Vaults +out of thin air. A special Minter resource needs to be defined to mint +new tokens. + +Implemented Interfaces: + - `FungibleToken.Provider` + - `FungibleToken.Receiver` + - `FungibleToken.Balance` + - `MetadataViews.Resolver` + + +### Initializer + +```cadence +func init(balance UFix64) +``` + + +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): FungibleToken.Vault +``` +Function that takes an amount as an argument +and withdraws that amount from the Vault. +It creates a new temporary Vault that is used to hold +the money that is being transferred. It returns the newly +created Vault to the context that called so it can be deposited +elsewhere. + +Parameters: + - amount : _The amount of tokens to be withdrawn from the vault_ + +Returns: The Vault resource containing the withdrawn funds + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` +Function that takes a Vault object as an argument and adds +its balance to the balance of the owners Vault. +It is allowed to destroy the sent Vault because the Vault +was a temporary holder of the tokens. The Vault's balance has +been consumed and therefore can be destroyed. + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- + +### fun `getViews()` + +```cadence +func getViews(): [Type] +``` +The way of getting all the Metadata Views implemented by ExampleToken + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### fun `resolveView()` + +```cadence +func resolveView(_ Type): AnyStruct? +``` +The way of getting a Metadata View out of the ExampleToken + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/FungibleToken/FungibleToken.md b/docs/FungibleToken/FungibleToken.md new file mode 100644 index 00000000..298d13b5 --- /dev/null +++ b/docs/FungibleToken/FungibleToken.md @@ -0,0 +1,121 @@ +# Contract Interface `FungibleToken` + +```cadence +contract interface FungibleToken { + + totalSupply: UFix64 +} +``` + +The interface that Fungible Token contracts implement. +## Interfaces + +### resource interface `Provider` + +```cadence +resource interface Provider { +} +``` +The interface that enforces the requirements for withdrawing +tokens from the implementing type. + +It does not enforce requirements on `balance` here, +because it leaves open the possibility of creating custom providers +that do not necessarily need their own balance. + +[More...](FungibleToken_Provider.md) + +--- + +### resource interface `Receiver` + +```cadence +resource interface Receiver { +} +``` +The interface that enforces the requirements for depositing +tokens into the implementing type. + +We do not include a condition that checks the balance because +we want to give users the ability to make custom receivers that +can do custom things with the tokens, like split them up and +send them to different places. + +[More...](FungibleToken_Receiver.md) + +--- + +### resource interface `Balance` + +```cadence +resource interface Balance { + + balance: UFix64 +} +``` +The interface that contains the `balance` field of the Vault +and enforces that when new Vaults are created, the balance +is initialized correctly. + +[More...](FungibleToken_Balance.md) + +--- +## Structs & Resources + +### resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` +The resource that contains the functions to send and receive tokens. +The declaration of a concrete type in a contract interface means that +every Fungible Token contract that implements the FungibleToken interface +must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`, +and `Balance` interfaces, and declares their required fields and functions + +[More...](FungibleToken_Vault.md) + +--- +## Functions + +### fun `createEmptyVault()` + +```cadence +func createEmptyVault(): Vault +``` +Allows any user to create a new Vault that has a zero balance + +Returns: The new Vault resource + +--- +## Events + +### event `TokensInitialized` + +```cadence +event TokensInitialized(initialSupply UFix64) +``` +The event that is emitted when the contract is created + +--- + +### event `TokensWithdrawn` + +```cadence +event TokensWithdrawn(amount UFix64, from Address?) +``` +The event that is emitted when tokens are withdrawn from a Vault + +--- + +### event `TokensDeposited` + +```cadence +event TokensDeposited(amount UFix64, to Address?) +``` +The event that is emitted when tokens are deposited into a Vault + +--- diff --git a/docs/FungibleToken/FungibleToken_Balance.md b/docs/FungibleToken/FungibleToken_Balance.md new file mode 100644 index 00000000..90529705 --- /dev/null +++ b/docs/FungibleToken/FungibleToken_Balance.md @@ -0,0 +1,40 @@ +# Resource Interface `Balance` + +```cadence +resource interface Balance { + + balance: UFix64 +} +``` + +The interface that contains the `balance` field of the Vault +and enforces that when new Vaults are created, the balance +is initialized correctly. +## Functions + +### fun `getViews()` + +```cadence +func getViews(): [Type] +``` +Function that returns all the Metadata Views implemented by a Fungible Token + +developers to know which parameter to pass to the resolveView() method. + +Returns: An array of Types defining the implemented views. This value will be used by + +--- + +### fun `resolveView()` + +```cadence +func resolveView(_ Type): AnyStruct? +``` +Function that resolves a metadata view for this fungible token by type. + +Parameters: + - view : _The Type of the desired view._ + +Returns: A structure representing the requested view. + +--- diff --git a/docs/FungibleToken/FungibleToken_Provider.md b/docs/FungibleToken/FungibleToken_Provider.md new file mode 100644 index 00000000..fa47e733 --- /dev/null +++ b/docs/FungibleToken/FungibleToken_Provider.md @@ -0,0 +1,41 @@ +# Resource Interface `Provider` + +```cadence +resource interface Provider { +} +``` + +The interface that enforces the requirements for withdrawing +tokens from the implementing type. + +It does not enforce requirements on `balance` here, +because it leaves open the possibility of creating custom providers +that do not necessarily need their own balance. +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): Vault +``` +Subtracts tokens from the owner's Vault +and returns a Vault with the removed tokens. + +The function's access level is public, but this is not a problem +because only the owner storing the resource in their account +can initially call this function. + +The owner may grant other accounts access by creating a private +capability that allows specific other users to access +the provider resource through a reference. + +The owner may also grant all accounts access by creating a public +capability that allows all users to access the provider +resource through a reference. + +Parameters: + - amount : _The amount of tokens to be withdrawn from the vault_ + +Returns: The Vault resource containing the withdrawn funds + +--- diff --git a/docs/FungibleToken/FungibleToken_Receiver.md b/docs/FungibleToken/FungibleToken_Receiver.md new file mode 100644 index 00000000..8e3c86bf --- /dev/null +++ b/docs/FungibleToken/FungibleToken_Receiver.md @@ -0,0 +1,27 @@ +# Resource Interface `Receiver` + +```cadence +resource interface Receiver { +} +``` + +The interface that enforces the requirements for depositing +tokens into the implementing type. + +We do not include a condition that checks the balance because +we want to give users the ability to make custom receivers that +can do custom things with the tokens, like split them up and +send them to different places. +## Functions + +### fun `deposit()` + +```cadence +func deposit(from Vault) +``` +Takes a Vault and deposits it into the implementing resource type + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- diff --git a/docs/FungibleToken/FungibleToken_Vault.md b/docs/FungibleToken/FungibleToken_Vault.md new file mode 100644 index 00000000..07ca7268 --- /dev/null +++ b/docs/FungibleToken/FungibleToken_Vault.md @@ -0,0 +1,49 @@ +# Resource `Vault` + +```cadence +resource Vault { + + balance: UFix64 +} +``` + +The resource that contains the functions to send and receive tokens. +The declaration of a concrete type in a contract interface means that +every Fungible Token contract that implements the FungibleToken interface +must define a concrete `Vault` resource that conforms to the `Provider`, `Receiver`, +and `Balance` interfaces, and declares their required fields and functions + +Implemented Interfaces: + - `Provider` + - `Receiver` + - `Balance` + + +### Initializer + +```cadence +func init(balance UFix64) +``` + + +## Functions + +### fun `withdraw()` + +```cadence +func withdraw(amount UFix64): Vault +``` + +--- + +### fun `deposit()` + +```cadence +func deposit(from Vault) +``` +Takes a Vault and deposits it into the implementing resource type + +Parameters: + - from : _The Vault resource containing the funds that will be deposited_ + +--- diff --git a/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md new file mode 100644 index 00000000..169b5113 --- /dev/null +++ b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews.md @@ -0,0 +1,133 @@ +# Contract `FungibleTokenMetadataViews` + +```cadence +contract FungibleTokenMetadataViews { +} +``` + +This contract implements the metadata standard proposed +in FLIP-1087. + +Ref: https://github.com/onflow/flow/blob/master/flips/20220811-fungible-tokens-metadata.md + +Structs and resources can implement one or more +metadata types, called views. Each view type represents +a different kind of metadata. +## Structs & Resources + +### struct `FTView` + +```cadence +struct FTView { + + ftDisplay: FTDisplay? + + ftVaultData: FTVaultData? +} +``` +FTView wraps FTDisplay and FTVaultData, and is used to give a complete +picture of a Fungible Token. Most Fungible Token contracts should +implement this view. + +[More...](FungibleTokenMetadataViews_FTView.md) + +--- + +### struct `FTDisplay` + +```cadence +struct FTDisplay { + + name: String + + symbol: String + + description: String + + externalURL: MetadataViews.ExternalURL + + logos: MetadataViews.Medias + + socials: {String: MetadataViews.ExternalURL} +} +``` +View to expose the information needed to showcase this FT. +This can be used by applications to give an overview and +graphics of the FT. + +[More...](FungibleTokenMetadataViews_FTDisplay.md) + +--- + +### struct `FTVaultData` + +```cadence +struct FTVaultData { + + storagePath: StoragePath + + receiverPath: PublicPath + + metadataPath: PublicPath + + providerPath: PrivatePath + + receiverLinkedType: Type + + metadataLinkedType: Type + + providerLinkedType: Type + + createEmptyVault: ((): @FungibleToken.Vault) +} +``` +View to expose the information needed store and interact with a FT vault. +This can be used by applications to setup a FT vault with proper +storage and public capabilities. + +[More...](FungibleTokenMetadataViews_FTVaultData.md) + +--- +## Functions + +### fun `getFTView()` + +```cadence +func getFTView(viewResolver &{MetadataViews.Resolver}): FTView +``` +Helper to get a FT view. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A FTView struct + +--- + +### fun `getFTDisplay()` + +```cadence +func getFTDisplay(_ &{MetadataViews.Resolver}): FTDisplay? +``` +Helper to get FTDisplay in a way that will return a typed optional. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: An optional FTDisplay struct + +--- + +### fun `getFTVaultData()` + +```cadence +func getFTVaultData(_ &{MetadataViews.Resolver}): FTVaultData? +``` +Helper to get FTVaultData in a way that will return a typed Optional. + +Parameters: + - viewResolver : _A reference to the resolver resource_ + +Returns: A optional FTVaultData struct + +--- diff --git a/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md new file mode 100644 index 00000000..28653aa2 --- /dev/null +++ b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTDisplay.md @@ -0,0 +1,30 @@ +# Struct `FTDisplay` + +```cadence +struct FTDisplay { + + name: String + + symbol: String + + description: String + + externalURL: MetadataViews.ExternalURL + + logos: MetadataViews.Medias + + socials: {String: MetadataViews.ExternalURL} +} +``` + +View to expose the information needed to showcase this FT. +This can be used by applications to give an overview and +graphics of the FT. + +### Initializer + +```cadence +func init(name String, symbol String, description String, externalURL MetadataViews.ExternalURL, logos MetadataViews.Medias, socials {String: MetadataViews.ExternalURL}) +``` + + diff --git a/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md new file mode 100644 index 00000000..7a23819e --- /dev/null +++ b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTVaultData.md @@ -0,0 +1,34 @@ +# Struct `FTVaultData` + +```cadence +struct FTVaultData { + + storagePath: StoragePath + + receiverPath: PublicPath + + metadataPath: PublicPath + + providerPath: PrivatePath + + receiverLinkedType: Type + + metadataLinkedType: Type + + providerLinkedType: Type + + createEmptyVault: ((): @FungibleToken.Vault) +} +``` + +View to expose the information needed store and interact with a FT vault. +This can be used by applications to setup a FT vault with proper +storage and public capabilities. + +### Initializer + +```cadence +func init(storagePath StoragePath, receiverPath PublicPath, metadataPath PublicPath, providerPath PrivatePath, receiverLinkedType Type, metadataLinkedType Type, providerLinkedType Type, createEmptyVaultFunction ((): @FungibleToken.Vault)) +``` + + diff --git a/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md new file mode 100644 index 00000000..0bb2b716 --- /dev/null +++ b/docs/FungibleTokenMetadataViews/FungibleTokenMetadataViews_FTView.md @@ -0,0 +1,22 @@ +# Struct `FTView` + +```cadence +struct FTView { + + ftDisplay: FTDisplay? + + ftVaultData: FTVaultData? +} +``` + +FTView wraps FTDisplay and FTVaultData, and is used to give a complete +picture of a Fungible Token. Most Fungible Token contracts should +implement this view. + +### Initializer + +```cadence +func init(ftDisplay FTDisplay?, ftVaultData FTVaultData?) +``` + + diff --git a/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md new file mode 100644 index 00000000..77922eca --- /dev/null +++ b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard.md @@ -0,0 +1,91 @@ +# Contract `FungibleTokenSwitchboard` + +```cadence +contract FungibleTokenSwitchboard { + + StoragePath: StoragePath + + PublicPath: PublicPath + + ReceiverPublicPath: PublicPath +} +``` + +The contract that allows an account to receive payments in multiple fungible +tokens using a single `{FungibleToken.Receiver}` capability. +This capability should ideally be stored at the +`FungibleTokenSwitchboard.ReceiverPublicPath = /public/GenericFTReceiver` +but it can be stored anywhere. +## Interfaces + +### resource interface `SwitchboardPublic` + +```cadence +resource interface SwitchboardPublic { +} +``` +The interface that enforces the method to allow anyone to check on the +available capabilities of a switchboard resource and also exposes the +deposit methods to deposit funds on it. + +[More...](FungibleTokenSwitchboard_SwitchboardPublic.md) + +--- +## Structs & Resources + +### resource `Switchboard` + +```cadence +resource Switchboard { + + receiverCapabilities: {Type: Capability<&{FungibleToken.Receiver}>} +} +``` +The resource that stores the multiple fungible token receiver +capabilities, allowing the owner to add and remove them and anyone to +deposit any fungible token among the available types. + +[More...](FungibleTokenSwitchboard_Switchboard.md) + +--- +## Functions + +### fun `createSwitchboard()` + +```cadence +func createSwitchboard(): Switchboard +``` +Function that allows to create a new blank switchboard. A user must call +this function and store the returned resource in their storage. + +--- +## Events + +### event `VaultCapabilityAdded` + +```cadence +event VaultCapabilityAdded(type Type, switchboardOwner Address?, capabilityOwner Address?) +``` +The event that is emitted when a new vault capability is added to a +switchboard resource. + +--- + +### event `VaultCapabilityRemoved` + +```cadence +event VaultCapabilityRemoved(type Type, switchboardOwner Address?, capabilityOwner Address?) +``` +The event that is emitted when a vault capability is removed from a +switchboard resource. + +--- + +### event `NotCompletedDeposit` + +```cadence +event NotCompletedDeposit(type Type, amount UFix64, switchboardOwner Address?) +``` +The event that is emitted when a deposit can not be completed. + +--- diff --git a/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md new file mode 100644 index 00000000..0f87fda2 --- /dev/null +++ b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_Switchboard.md @@ -0,0 +1,120 @@ +# Resource `Switchboard` + +```cadence +resource Switchboard { + + receiverCapabilities: {Type: Capability<&{FungibleToken.Receiver}>} +} +``` + +The resource that stores the multiple fungible token receiver +capabilities, allowing the owner to add and remove them and anyone to +deposit any fungible token among the available types. + +Implemented Interfaces: + - `FungibleToken.Receiver` + - `SwitchboardPublic` + + +### Initializer + +```cadence +func init() +``` + + +## Functions + +### fun `addNewVault()` + +```cadence +func addNewVault(capability Capability<&{FungibleToken.Receiver}>) +``` +Adds a new fungible token receiver capability to the switchboard +resource. + +token vault deposit function through `{FungibleToken.Receiver}` that +will be added to the switchboard. + +Parameters: + - capability : _The capability to expose a certain fungible_ + +--- + +### fun `addNewVaultsByPath()` + +```cadence +func addNewVaultsByPath(paths [PublicPath], address Address) +``` +Adds a number of new fungible token receiver capabilities by using +the paths where they are stored. + +Parameters: + - paths : _The paths where the public capabilities are stored._ + - address : _The address of the owner of the capabilities._ + +--- + +### fun `removeVault()` + +```cadence +func removeVault(capability Capability<&{FungibleToken.Receiver}>) +``` +Removes a fungible token receiver capability from the switchboard +resource. + +removed from the switchboard. + +Parameters: + - capability : _The capability to a fungible token vault to be_ + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` +Takes a fungible token vault and routes it to the proper fungible +token receiver capability for depositing it. + +Parameters: + - from : _The deposited fungible token vault resource._ + +--- + +### fun `safeDeposit()` + +```cadence +func safeDeposit(from FungibleToken.Vault): FungibleToken.Vault? +``` +Takes a fungible token vault and tries to route it to the proper +fungible token receiver capability for depositing the funds, +avoiding panicking if the vault is not available. + +deposited. + +funds if the deposit was succesful, or still containing the funds +if the reference to the needed vault was not found. + +Parameters: + - vaultType : _The type of the ft vault that wants to be_ + +Returns: The deposited fungible token vault resource, without the + +--- + +### fun `getVaultTypes()` + +```cadence +func getVaultTypes(): [Type] +``` +A getter function to know which tokens a certain switchboard +resource is prepared to receive. + +`{FungibleToken.Receiver}` capabilities that can be efectively +borrowed. + +Returns: The keys from the dictionary of stored + +--- diff --git a/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md new file mode 100644 index 00000000..5065f121 --- /dev/null +++ b/docs/FungibleTokenSwitchboard/FungibleTokenSwitchboard_SwitchboardPublic.md @@ -0,0 +1,35 @@ +# Resource Interface `SwitchboardPublic` + +```cadence +resource interface SwitchboardPublic { +} +``` + +The interface that enforces the method to allow anyone to check on the +available capabilities of a switchboard resource and also exposes the +deposit methods to deposit funds on it. +## Functions + +### fun `getVaultTypes()` + +```cadence +func getVaultTypes(): [Type] +``` + +--- + +### fun `deposit()` + +```cadence +func deposit(from FungibleToken.Vault) +``` + +--- + +### fun `safeDeposit()` + +```cadence +func safeDeposit(from FungibleToken.Vault): FungibleToken.Vault? +``` + +---