@flowtyio/flow-contracts 0.0.2 → 0.0.3

package/README.md

@@ -1,7 +1,7 @@
 # flow-contracts
 
 ```
-npm i @flowtyio/flow-contracts
+npm i @flowty/flow-contracts
 ```
 
 This repository publishes common Flow contracts as an npm package so that they can be more easily consumed. 
@@ -36,7 +36,7 @@ For example, here is how you might add `NonFungibleToken` to your flow.json :
 	},
 	"contracts": {
 		"NonFungibleToken": {
-			"source": "./node_modules/@flowtyio/flow-contracts/contracts/NonFungibleToken.cdc",
+			"source": "./node_modules/@flowty/flow-contracts/contracts/NonFungibleToken.cdc",
 			"aliases": {
 				"emulator": "0xf8d6e0586b0a20c7",
 				"testnet": "0x631e88ae7f1d7c20",
@@ -83,7 +83,7 @@ you will need to:
 	},
 	"contracts": {
 		"FungibleToken": {
-			"source": "./node_modules/@flowtyio/flow-contracts/contracts/FungibleToken.cdc",
+			"source": "./node_modules/@flowty/flow-contracts/contracts/FungibleToken.cdc",
 			"aliases": {
 				"emulator": "0xee82856bf20e2aa6",
 			}

package/add.js

@@ -0,0 +1,133 @@
+const {getConfig, writeConfig, getProjectConfig, getDefaultConfigPath} = require("./utils");
+const {getImports} = require("./dependency-tree");
+
+const specialContractsHandlers = {
+  "FungibleToken": (contract, userConfig, account) => {
+    console.log("FungibleToken requires some special setup. The account `emulator-ft` " +
+      "will be created and the contract will be deployed to it on the emulator. \nGoing forward, any deployments to the " +
+      "flow emulator will require the --update flag to work correctly.")
+
+    const name = "FungibleToken"
+
+    const serverPK = userConfig.accounts[account].key
+    const ftAccount = {
+      address: "ee82856bf20e2aa6", // this is the FungibleToken address on the flow emulator
+      key: serverPK
+    }
+    const emulatorAcct = "emulator-ft"
+
+    // ensure emulator-ft is an account
+    userConfig.accounts[emulatorAcct] = ftAccount
+    if (!userConfig.deployments) {
+      userConfig.deployments = {}
+    }
+
+    // ensure that emulator-ft is a deployment account
+    if (!userConfig.deployments.emulator) {
+      userConfig.deployments.emulator = {}
+    }
+
+    if (!userConfig.deployments.emulator[emulatorAcct]) {
+      userConfig.deployments.emulator[emulatorAcct] = []
+    }
+
+    userConfig.contracts[name] = contract
+
+    if (!userConfig.deployments.emulator[emulatorAcct].includes(name)) {
+      userConfig.deployments.emulator[emulatorAcct].push(name)
+    }
+  }
+}
+
+const importContract = (contractName, source, config, account) => {
+  let newConfig = {...config}
+
+  const contract = source.contracts[contractName]
+  if (!contract) {
+    console.error(`Contract "${contractName}" could not be found`)
+    return
+  }
+
+  if (specialContractsHandlers[contractName]) {
+    specialContractsHandlers[contractName](contract, newConfig, account)
+  } else {
+    // only add the contract if it doesn't already exist
+    if (!newConfig.contracts[contractName]) {
+      newConfig.contracts[contractName] = contract
+    }
+
+    // add this contract to the deployment list of the specified account
+    if (!newConfig.deployments.emulator[account].includes(contractName)) {
+      newConfig.deployments.emulator[account].push(contractName)
+    }
+  }
+
+  return newConfig
+}
+
+const add = ({name, config, account}) => {
+  let userConfig = getConfig(config)
+
+  const exampleConfigLocation = `${__dirname}/flow.json`
+  const exampleConfig = getConfig(exampleConfigLocation)
+  const contract = exampleConfig.contracts[name]
+  if (!contract) {
+    console.error(`Contract "${name}" could not be found`)
+    return
+  }
+
+  if (!userConfig.contracts) {
+    userConfig.contracts = {}
+  }
+
+  // validate the specified account exists
+  if (!userConfig.accounts[account]) {
+    console.error(`Account "${account}" could not be found`)
+    return
+  }
+
+  if (!userConfig.deployments) {
+    userConfig.deployments = {}
+  }
+
+  if (!userConfig.deployments.emulator) {
+    userConfig.deployments.emulator = {}
+  }
+
+  if (!userConfig.deployments.emulator[account]) {
+    userConfig.deployments.emulator[account] = []
+  }
+
+  // get all imports, add them first, then add the one being requested.
+  const imports = getImports(name)
+  if (imports) {
+    console.log("The following contracts will also be added to the config: ", imports.join(", "))
+    imports.forEach(contractName => {
+      userConfig = importContract(contractName, exampleConfig, userConfig, account)
+    })
+  }
+
+  console.log("finished adding dependencies, adding requested contract")
+  userConfig = importContract(name, exampleConfig, userConfig, account)
+
+  writeConfig(config, userConfig)
+
+  console.log(`Contract "${name}" added to ${config}`)
+}
+
+const addAll = (path, account) => {
+  const configPath = path ?? getDefaultConfigPath()
+
+  console.log(`Adding all contracts to config found at ${configPath}`)
+  const projectConfig = getProjectConfig()
+  const userConfig = getConfig(configPath)
+
+  Object.keys(projectConfig.contracts).forEach(name => {
+    add({name, config: configPath, account})
+  })
+}
+
+module.exports = {
+  add,
+  addAll
+}

package/contracts/FungibleToken.cdc

@@ -0,0 +1,237 @@
+/**
+
+# The Flow Fungible Token standard
+
+## `FungibleToken` contract interface
+
+The interface that all Fungible Token contracts would have to conform to.
+If a users wants to deploy a new token contract, their contract
+would need to implement the FungibleToken interface.
+
+Their contract would have to follow all the rules and naming
+that the interface specifies.
+
+## `Vault` resource
+
+Each account that owns tokens would need to have an instance
+of the Vault resource stored in their account storage.
+
+The Vault resource has methods that the owner and other users can call.
+
+## `Provider`, `Receiver`, and `Balance` resource interfaces
+
+These interfaces declare pre-conditions and post-conditions that restrict
+the execution of the functions in the Vault.
+
+They are separate because it gives the user the ability to share
+a reference to their Vault that only exposes the fields functions
+in one or more of the interfaces.
+
+It also gives users the ability to make custom resources that implement
+these interfaces to do various things with the tokens.
+For example, a faucet can be implemented by conforming
+to the Provider interface.
+
+By using resources and interfaces, users of Fungible Token contracts
+can send and receive tokens peer-to-peer, without having to interact
+with a central ledger smart contract. To send tokens to another user,
+a user would simply withdraw the tokens from their Vault, then call
+the deposit function on another user's Vault to complete the transfer.
+
+*/
+
+/// The interface that Fungible Token contracts implement.
+///
+pub contract interface FungibleToken {
+
+    /// The total number of tokens in existence.
+    /// It is up to the implementer to ensure that the total supply
+    /// stays accurate and up to date
+    pub var totalSupply: UFix64
+
+    /// The event that is emitted when the contract is created
+    pub event TokensInitialized(initialSupply: UFix64)
+
+    /// The event that is emitted when tokens are withdrawn from a Vault
+    pub event TokensWithdrawn(amount: UFix64, from: Address?)
+
+    /// The event that is emitted when tokens are deposited into a Vault
+    pub event TokensDeposited(amount: UFix64, to: Address?)
+
+    /// 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.
+    ///
+    pub resource interface Provider {
+
+        /// 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.
+        ///
+        /// @param amount: The amount of tokens to be withdrawn from the vault
+        /// @return The Vault resource containing the withdrawn funds
+        /// 
+        pub fun withdraw(amount: UFix64): @Vault {
+            post {
+                // `result` refers to the return value
+                result.balance == amount:
+                    "Withdrawal amount must be the same as the balance of the withdrawn Vault"
+            }
+        }
+    }
+
+    /// 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.
+    ///
+    pub resource interface Receiver {
+
+        /// Takes a Vault and deposits it into the implementing resource type
+        ///
+        /// @param from: The Vault resource containing the funds that will be deposited
+        ///
+        pub fun deposit(from: @Vault)
+
+        /// Below is referenced from the FLIP #69 https://github.com/onflow/flips/blob/main/flips/20230206-fungible-token-vault-type-discovery.md
+        /// 
+        /// Returns the dictionary of Vault types that the the receiver is able to accept in its `deposit` method
+        /// this then it would return `{Type<@FlowToken.Vault>(): true}` and if any custom receiver
+        /// uses the default implementation then it would return empty dictionary as its parent
+        /// resource doesn't conform with the `FungibleToken.Vault` resource.
+        ///
+        /// Custom receiver implementations are expected to upgrade their contracts to add an implementation
+        /// that supports this method because it is very valuable for various applications to have.
+        ///
+        /// @return dictionary of supported deposit vault types by the implementing resource.
+        /// 
+        pub fun getSupportedVaultTypes(): {Type: Bool} {
+            // Below check is implemented to make sure that run-time type would
+            // only get returned when the parent resource conforms with `FungibleToken.Vault`. 
+            if self.getType().isSubtype(of: Type<@FungibleToken.Vault>()) {
+                return {self.getType(): true}
+            } else {
+                // Return an empty dictionary as the default value for resource who don't
+                // implement `FungibleToken.Vault`, such as `FungibleTokenSwitchboard`, `TokenForwarder` etc.
+                return {}
+            }
+        }
+    }
+
+    /// The interface that contains the `balance` field of the Vault
+    /// and enforces that when new Vaults are created, the balance
+    /// is initialized correctly.
+    ///
+    pub resource interface Balance {
+
+        /// The total balance of a vault
+        ///
+        pub var balance: UFix64
+
+        init(balance: UFix64) {
+            post {
+                self.balance == balance:
+                    "Balance must be initialized to the initial balance"
+            }
+        }
+
+        /// Function that returns all the Metadata Views implemented by a Fungible Token
+        ///
+        /// @return An array of Types defining the implemented views. This value will be used by
+        ///         developers to know which parameter to pass to the resolveView() method.
+        ///
+        pub fun getViews(): [Type] {
+            return []
+        }
+
+        /// Function that resolves a metadata view for this fungible token by type.
+        ///
+        /// @param view: The Type of the desired view.
+        /// @return A structure representing the requested view.
+        ///
+        pub fun resolveView(_ view: Type): AnyStruct? {
+            return nil
+        }
+    }
+
+    /// 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
+    ///
+    pub resource Vault: Provider, Receiver, Balance {
+
+        /// The total balance of the vault
+        pub var balance: UFix64
+
+        // The conforming type must declare an initializer
+        // that allows providing the initial balance of the Vault
+        //
+        init(balance: UFix64)
+
+        /// Subtracts `amount` from the Vault's balance
+        /// and returns a new Vault with the subtracted balance
+        ///
+        /// @param amount: The amount of tokens to be withdrawn from the vault
+        /// @return The Vault resource containing the withdrawn funds
+        ///
+        pub fun withdraw(amount: UFix64): @Vault {
+            pre {
+                self.balance >= amount:
+                    "Amount withdrawn must be less than or equal than the balance of the Vault"
+            }
+            post {
+                // use the special function `before` to get the value of the `balance` field
+                // at the beginning of the function execution
+                //
+                self.balance == before(self.balance) - amount:
+                    "New Vault balance must be the difference of the previous balance and the withdrawn Vault"
+            }
+        }
+
+        /// Takes a Vault and deposits it into the implementing resource type
+        ///
+        /// @param from: The Vault resource containing the funds that will be deposited
+        ///
+        pub fun deposit(from: @Vault) {
+            // Assert that the concrete type of the deposited vault is the same
+            // as the vault that is accepting the deposit
+            pre {
+                from.isInstance(self.getType()): 
+                    "Cannot deposit an incompatible token type"
+            }
+            post {
+                self.balance == before(self.balance) + before(from.balance):
+                    "New Vault balance must be the sum of the previous balance and the deposited Vault"
+            }
+        }
+    }
+
+    /// Allows any user to create a new Vault that has a zero balance
+    ///
+    /// @return The new Vault resource
+    ///
+    pub fun createEmptyVault(): @Vault {
+        post {
+            result.balance == 0.0: "The newly created Vault must have zero balance"
+        }
+    }
+}