Fungible Token Switchboard contract and tests

.github/workflows/ci.yml

@@ -16,4 +16,18 @@ jobs:
  key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
  restore-keys: |
  ${{ runner.os }}-go-
+ - uses: actions/setup-node@v3
+ with:
+ node-version: 14
+ cache: 'npm'
+ cache-dependency-path: lib/js/test/package-lock.json
+ - name: Install Flow CLI
+ run: sh -ci "$(curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/install.sh)" -- v0.33.1-sc-m5
+ - name: Flow cli Version
+ run: flow version
+ - name: Update PATH
+ run: echo "/root/.local/bin" >> $GITHUB_PATH
+ - name: Install dependencies
+ run: cd lib/js/test && npm ci
  - run: make ci
+

.gitignore

@@ -1 +1,2 @@
 .idea
+lib/js/test/node_modules/*

Makefile

@@ -2,7 +2,9 @@
 test:
  $(MAKE) generate -C lib/go
  $(MAKE) test -C lib/go
+ $(MAKE) test -C lib/js/test
 
 .PHONY: ci
 ci:
  $(MAKE) ci -C lib/go
+ $(MAKE) ci -C lib/js/test

README.md

@@ -194,6 +194,183 @@ To use the Flow Token contract as is, you need to follow these steps:
 8. Use the `create_minter.cdc` transaction to create a new MintandBurn resource
  and store it in a new Admin's account.
 
+# Fungible Token Switchboard
+
+`FungibleTokenSwitchboard.cdc`, allows users to receive payments in different fungible tokens using a single `&{FungibleToken.Receiver}` placed in a standard receiver path `/public/GenericFTReceiver`.
+
+ ## How to use it
+
+ Users willing to use the Fungible Token Switchboard will need to setup their accounts by creating a new `FungibleTokenSwitchboard.Switchboard` resource and saving it to their accounts at the `FungibleTokenSwitchboard.StoragePath` path.
+
+ This can be acomplished by executing the transaction found in this repository `transactions/switchboard/setup_account.cdc`. This transaction will create and save a Switchboard resource to the signer's account,
+ and it also will create the needed public capabilities to access it. After setting up their switchboard, in order to make it support receiving a certain token, users will need to add the desired token's receiver capability to their switchboard resource.
+
+ ## Adding a new vault to the switchboard
+ When a user wants to receive a new fungible token through their switchboard, they will need to add a new public capability linked to said FT to their switchboard resource. This can be accomplished in two different ways:
+
+ 1. Adding a single capability using `addNewVault(capability: Capability<&{FungibleToken.Receiver}>)`
+ * Before calling this method on a transaction you should first retrieve the capability to the token's vault you are
+ willing to add to the switchboard, as is done in the template transaction `transactions/switchboard/add_vault_capabilty.cdc`.
+
+ ```cadence
+ transaction {
+ let exampleTokenVaultCapabilty: Capability<&{FungibleToken.Receiver}>
+ let switchboardRef: &FungibleTokenSwitchboard.Switchboard
+
+ prepare(signer: AuthAccount) {
+ // Get the example token vault capability from the signer's account
+ self.exampleTokenVaultCapabilty = 
+ signer.getCapability<&{FungibleToken.Receiver}>
+ (ExampleToken.ReceiverPublicPath)
+ // Get a reference to the signers switchboard
+ self.switchboardRef = signer.borrow<&FungibleTokenSwitchboard.Switchboard>
+ (from: FungibleTokenSwitchboard.StoragePath) 
+ ?? panic("Could not borrow reference to switchboard")
+ }
+
+ execute {
+ // Add the capability to the switchboard using addNewVault method
+ self.switchboardRef.addNewVault(capability: self.exampleTokenVaultCapabilty)
+ }
+ }
+ ```
+ This function will panic if is not possible to `.borrow()` a reference to a `&{FungibleToken.Receiver}` from the passed capability. It will also panic if there is already a capability stored for the same `Type` of resource exposed by the capability.
+
+ 2. Adding one or more capabilities using the paths where they are stored using `addNewVaultsByPath(paths: [PublicPath], address: Address)`
+ * When using this method, an array of `PublicPath` objects should be passed along with the `Address` of the account from where the vaults' capabilities should be retrieved.
+
+ ```cadence
+ transaction (address: Address) {
+
+ let exampleTokenVaultPath: PublicPath
+ let vaultPaths: [PublicPath]
+ let switchboardRef: &FungibleTokenSwitchboard.Switchboard
+
+ prepare(signer: AuthAccount) {
+ // Get the example token vault path from the contract
+ self.exampleTokenVaultPath = ExampleToken.ReceiverPublicPath
+ // And store it in the array of public paths that will be passed to the
+ // switchboard method
+ self.vaultPaths = []
+ self.vaultPaths.append(self.exampleTokenVaultPath)
+ // Get a reference to the signers switchboard
+ self.switchboardRef = signer.borrow<&FungibleTokenSwitchboard.Switchboard>
+ (from: FungibleTokenSwitchboard.StoragePath) 
+ ?? panic("Could not borrow reference to switchboard")
+ }
+
+ execute {
+ // Add the capability to the switchboard using addNewVault method
+ self.switchboardRef.addNewVaultsByPath(paths: self.vaultPaths, 
+ address: address)
+ }
+ }
+ ```
+ This function won't panic, instead it will just not add to the `@Switchboard` any capability which can not be retrieved from any of the provided `PublicPath`s. It will also ignore any type of `&{FungibleToken.Receiver}` that is already present on the `@Switchboard`
+
+ ## Removing a vault from the switchboard
+ If a user no longer wants to be able to receive deposits from a certain FT, or if they want to update the provided capability for one of them, they will need to remove the vault from the switchboard.
+ This can be accomplished by using `removeVault(capability: Capability<&{FungibleToken.Receiver}>)`. 
+This can be observed in the template transaction `transactions/switchboard/remove_vault_capability.cdc`:
+ ```cadence
+ transaction {
+ let exampleTokenVaultCapabilty: Capability<&{FungibleToken.Receiver}>
+ let switchboardRef: &FungibleTokenSwitchboard.Switchboard
+
+ prepare(signer: AuthAccount) {
+ // Get the example token vault capability from the signer's account
+ self.exampleTokenVaultCapabilty = signer.getCapability
+ <&{FungibleToken.Receiver}>(ExampleToken.ReceiverPublicPath)
+ // Get a reference to the signers switchboard 
+ self.switchboardRef = signer.borrow<&FungibleTokenSwitchboard.Switchboard>
+ (from: FungibleTokenSwitchboard.StoragePath) 
+ ?? panic("Could not borrow reference to switchboard")
+
+ }
+
+ execute {
+ // Remove the capability from the switchboard using the 
+ // removeVault method
+ self.switchboardRef.removeVault(capability: self.exampleTokenVaultCapabilty)
+ }
+ }
+ ```
+ This function will panic if is not possible to `.borrow()` a reference to a `&{FungibleToken.Receiver}` from the passed capability.
+
+ ## Transfering tokens through the switchboard
+ The Fungible Token Switchboad provides two different ways of depositing tokens to it, using the `deposit(from: @FungibleToken.Vault)` method enforced by the `{FungibleToken.Receiver}` or using the `safeDeposit(from: @FungibleToken.Vault): @FungibleToken`:
+
+ 1. Using the first method will be just the same as depositing to `&{FungibleToken.Receiver}`. The path for the Switchboard receiver is defined in `FungibleTokenSwitchboard.ReceiverPublicPath`,
+ the generic receiver path `/public/GenericFTReceiver` that can also be obtained from the NFT MetadataViews contract.
+ An example of how to do this can be found in the transaction template on this repo `transactions/switchboard/transfer_tokens.cdc`
+ ```cadence
+ transaction(to: Address, amount: UFix64) {
+ // The Vault resource that holds the tokens that are being transferred
+ let sentVault: @FungibleToken.Vault
+
+ prepare(signer: AuthAccount) {
+
+ // Get a reference to the signer's stored vault
+ let vaultRef = signer.borrow<&ExampleToken.Vault>
+ (from: ExampleToken.VaultStoragePath)
+ ?? panic("Could not borrow reference to the owner's Vault!")
+
+ // Withdraw tokens from the signer's stored vault
+ self.sentVault <- vaultRef.withdraw(amount: amount)
+ }
+
+ execute {
+
+ // Get the recipient's public account object
+ let recipient = getAccount(to)
+
+ // Get a reference to the recipient's Switchboard Receiver
+ let switchboardRef = recipient.getCapability
+ (FungibleTokenSwitchboard.ReceiverPublicPath)
+ .borrow<&{FungibleToken.Receiver}>()
+ ?? panic("Could not borrow receiver reference to switchboard!")
+
+ // Deposit the withdrawn tokens in the recipient's switchboard receiver
+ switchboardRef.deposit(from: <-self.sentVault)
+ }
+ }
+ ```
+
+ 2. The `safeDeposit(from: @FungibleToken.Vault): @FungibleToken` works in a similar way, with the difference that it will not panic if the desired FT Vault can not be obtained from the Switchboard. The method will return the passed vault, empty if the funds were deposited sucessfully or still containing the funds if the transfer of the funds was not possible. Keep in mind that when using this method on a transaction you will allways have to deal with the returned resource. An example of this can be found on `transactions/switchboard/safe_transfer_tokens.cdc`:
+ ```cadence
+ transaction(to: Address, amount: UFix64) {
+ // The reference to the vault from the payer's account
+ let vaultRef: &ExampleToken.Vault
+ // The Vault resource that holds the tokens that are being transferred
+ let sentVault: @FungibleToken.Vault
+
+
+ prepare(signer: AuthAccount) {
+
+ // Get a reference to the signer's stored vault
+ self.vaultRef = signer.borrow<&ExampleToken.Vault>(from: ExampleToken.VaultStoragePath)
+ ?? panic("Could not borrow reference to the owner's Vault!")
+
+ // Withdraw tokens from the signer's stored vault
+ self.sentVault <- self.vaultRef.withdraw(amount: amount)
+ }
+
+ execute {
+
+ // Get the recipient's public account object
+ let recipient = getAccount(to)
+
+ // Get a reference to the recipient's Switchboard Receiver
+ let switchboardRef = recipient.getCapability(FungibleTokenSwitchboard.PublicPath)
+ .borrow<&FungibleTokenSwitchboard.Switchboard{FungibleTokenSwitchboard.SwitchboardPublic}>()
+ ?? panic("Could not borrow receiver reference to switchboard!")
+
+ // Deposit the withdrawn tokens in the recipient's switchboard receiver,
+ // then deposit the returned vault in the signer's vault
+ self.vaultRef.deposit(from: <- switchboardRef.safeDeposit(from: <-self.sentVault))
+ }
+ }
+ ```
 
 # Running Automated Tests