@flowtyio/flow-contracts 0.0.11 → 0.0.15

package/README.md

@@ -51,6 +51,12 @@ Currently, the list includes:
 | NFTCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | NFTProviderAndCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | NFTProviderFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| NFTCatalog | 0x49a7cda3a1eecc29 | 0x324c34e1c517e4db |
+| NFTCatalogAdmin | 0x49a7cda3a1eecc29 | 0x324c34e1c517e4db |
+| FlowToken | 0x7e60df042a9c0868 | 0x1654653399040a61 |
+| TokenForwarding | 0x51ea0e37c27a1f1a | 0xe544175ee0461c4b |
+| DapperUtilityCoin | 0x82ec283f88a62e65 | 0xead892083b3e2c6c |
+| FlowUtilityToken | 0x82ec283f88a62e65 | 0xead892083b3e2c6c |
 
 
 ## Using a contract

package/add.js

@@ -3,18 +3,24 @@ const {getImports} = require("./dependency-tree");
 
 const specialContractsHandlers = {
   "FungibleToken": (contract, userConfig, account) => {
-    console.log("FungibleToken requires some special setup. The account `emulator-ft` " +
+    return handleFungibleTokenAccountContract(contract, userConfig, account, "FungibleToken")
+  },
+  "FungibleTokenMetadataViews": (contract, userConfig, account) => {
+    return handleFungibleTokenAccountContract(contract, userConfig, account, "FungibleTokenMetadataViews")
+  },
+  "FlowToken": (contract, userConfig, account) => {
+    console.log("FlowToken requires some special setup. The account `emulator-flowtoken` " +
       "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 name = "FlowToken"
 
     const serverPK = userConfig.accounts[account].key
     const ftAccount = {
-      address: "ee82856bf20e2aa6", // this is the FungibleToken address on the flow emulator
+      address: "0ae53cb6e3f42a79", // this is the FungibleToken address on the flow emulator
       key: serverPK
     }
-    const emulatorAcct = "emulator-ft"
+    const emulatorAcct = "emulator-flowtoken"
 
     // ensure emulator-ft is an account
     userConfig.accounts[emulatorAcct] = ftAccount
@@ -131,6 +137,40 @@ const addAll = (path, account) => {
   })
 }
 
+const handleFungibleTokenAccountContract = (contract, userConfig, account, contractName) => {
+  console.log(`FungibleToken requires some special setup. The account "emulator-ft"\n
+  will be created and the contract will be deployed to it on the emulator. \nGoing forward, any deployments to the\n
+  flow emulator will require the --update flag to work correctly.`)
+
+  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[contractName] = contract
+
+  if (!userConfig.deployments.emulator[emulatorAcct].includes(contractName)) {
+    userConfig.deployments.emulator[emulatorAcct].push(contractName)
+  }
+}
+
 module.exports = {
   add,
   addAll

package/contracts/FlowStorageFees.cdc

@@ -0,0 +1,193 @@
+/*
+ * The FlowStorageFees smart contract
+ *
+ * An account's storage capacity determines up to how much storage on chain it can use. 
+ * A storage capacity is calculated by multiplying the amount of reserved flow with `StorageFee.storageMegaBytesPerReservedFLOW`
+ * The minimum amount of flow tokens reserved for storage capacity is `FlowStorageFees.minimumStorageReservation` this is paid during account creation, by the creator.
+ * 
+ * At the end of all transactions, any account that had any value changed in their storage 
+ * has their storage capacity checked against their storage used and their main flow token vault against the minimum reservation.
+ * If any account fails this check the transaction wil fail.
+ * 
+ * An account moving/deleting its `FlowToken.Vault` resource will result 
+ * in the transaction failing because the account will have no storage capacity.
+ * 
+ */
+
+import "FungibleToken"
+import "FlowToken"
+
+pub contract FlowStorageFees {
+
+    // Emitted when the amount of storage capacity an account has per reserved Flow token changes
+    pub event StorageMegaBytesPerReservedFLOWChanged(_ storageMegaBytesPerReservedFLOW: UFix64)
+
+    // Emitted when the minimum amount of Flow tokens that an account needs to have reserved for storage capacity changes.
+    pub event MinimumStorageReservationChanged(_ minimumStorageReservation: UFix64)
+
+    // Defines how much storage capacity every account has per reserved Flow token.
+    // definition is written per unit of flow instead of the inverse, 
+    // so there is no loss of precision calculating storage from flow, 
+    // but there is loss of precision when calculating flow per storage.
+    pub var storageMegaBytesPerReservedFLOW: UFix64
+
+    // Defines the minimum amount of Flow tokens that every account needs to have reserved for storage capacity.
+    // If an account has less then this amount reserved by the end of any transaction it participated in, the transaction will fail.
+    pub var minimumStorageReservation: UFix64
+
+    // An administrator resource that can change the parameters of the FlowStorageFees smart contract.
+    pub resource Administrator {
+
+        // Changes the amount of storage capacity an account has per accounts' reserved storage FLOW.
+        pub fun setStorageMegaBytesPerReservedFLOW(_ storageMegaBytesPerReservedFLOW: UFix64) {
+            if FlowStorageFees.storageMegaBytesPerReservedFLOW == storageMegaBytesPerReservedFLOW {
+              return
+            }
+            FlowStorageFees.storageMegaBytesPerReservedFLOW = storageMegaBytesPerReservedFLOW
+            emit StorageMegaBytesPerReservedFLOWChanged(storageMegaBytesPerReservedFLOW)
+        }
+
+        // Changes the minimum amount of FLOW an account has to have reserved.
+        pub fun setMinimumStorageReservation(_ minimumStorageReservation: UFix64) {
+            if FlowStorageFees.minimumStorageReservation == minimumStorageReservation {
+              return
+            }
+            FlowStorageFees.minimumStorageReservation = minimumStorageReservation
+            emit MinimumStorageReservationChanged(minimumStorageReservation)
+        }
+
+        access(contract) init(){}
+    }
+
+    /// calculateAccountCapacity returns the storage capacity of an account
+    ///
+    /// Returns megabytes
+    /// If the account has no default balance it is counted as a balance of 0.0 FLOW
+    pub fun calculateAccountCapacity(_ accountAddress: Address): UFix64 {
+        var balance = 0.0
+        if let balanceRef = getAccount(accountAddress)
+            .getCapability<&FlowToken.Vault{FungibleToken.Balance}>(/public/flowTokenBalance)!
+            .borrow() {
+                balance = balanceRef.balance
+        }
+
+        return self.accountBalanceToAccountStorageCapacity(balance)
+    }
+
+    /// calculateAccountsCapacity returns the storage capacity of a batch of accounts
+    pub fun calculateAccountsCapacity(_ accountAddresses: [Address]): [UFix64] {
+        let capacities: [UFix64] = []
+        for accountAddress in accountAddresses {
+            let capacity = self.calculateAccountCapacity(accountAddress)
+            capacities.append(capacity)
+        }
+        return capacities
+    }
+
+    // getAccountsCapacityForTransactionStorageCheck returns the storage capacity of a batch of accounts
+    // This is used to check if a transaction will fail because of any account being over the storage capacity
+    // The payer is an exception as its storage capacity is derived from its balance minus the maximum possible transaction fees 
+    // (transaction fees if the execution effort is at the execution efort limit, a.k.a.: computation limit, a.k.a.: gas limit)
+    pub fun getAccountsCapacityForTransactionStorageCheck(accountAddresses: [Address], payer: Address, maxTxFees: UFix64): [UFix64] {
+        let capacities: [UFix64] = []
+        for accountAddress in accountAddresses {
+            var balance = 0.0
+            if let balanceRef = getAccount(accountAddress)
+                .getCapability<&FlowToken.Vault{FungibleToken.Balance}>(/public/flowTokenBalance)!
+                .borrow() {
+                    if accountAddress == payer {
+                        // if the account is the payer, deduct the maximum possible transaction fees from the balance
+                        balance = balanceRef.balance.saturatingSubtract(maxTxFees)
+                    } else {
+                        balance = balanceRef.balance
+                    }
+            }
+
+            capacities.append(self.accountBalanceToAccountStorageCapacity(balance)) 
+        }
+        return capacities
+    }
+
+    // accountBalanceToAccountStorageCapacity returns the storage capacity
+    // an account would have with given the flow balance of the account.
+    pub fun accountBalanceToAccountStorageCapacity(_ balance: UFix64): UFix64 {
+        // get address token balance
+        if balance < self.minimumStorageReservation {
+            // if < then minimum return 0
+            return 0.0
+        }
+
+        // return balance multiplied with megabytes per flow 
+        return self.flowToStorageCapacity(balance)
+    }
+
+    // Amount in Flow tokens
+    // Returns megabytes
+    pub fun flowToStorageCapacity(_ amount: UFix64): UFix64 {
+        return amount.saturatingMultiply(FlowStorageFees.storageMegaBytesPerReservedFLOW)
+    }
+
+    // Amount in megabytes
+    // Returns Flow tokens
+    pub fun storageCapacityToFlow(_ amount: UFix64): UFix64 {
+        if FlowStorageFees.storageMegaBytesPerReservedFLOW == 0.0 as UFix64 {
+            return 0.0 as UFix64
+        }
+        // possible loss of precision
+        // putting the result back into `flowToStorageCapacity` might not yield the same result
+        return amount / FlowStorageFees.storageMegaBytesPerReservedFLOW
+    }
+
+    // converts storage used from UInt64 Bytes to UFix64 Megabytes.
+    pub fun convertUInt64StorageBytesToUFix64Megabytes(_ storage: UInt64): UFix64 {
+        // safe convert UInt64 to UFix64 (without overflow)
+        let f = UFix64(storage % 100000000 as UInt64) * 0.00000001 as UFix64 + UFix64(storage / 100000000 as UInt64)
+        // decimal point correction. Megabytes to bytes have a conversion of 10^-6 while UFix64 minimum value is 10^-8
+        let storageMb = f.saturatingMultiply(100.0)
+        return storageMb
+    }
+
+    /// Gets "available" balance of an account
+    ///
+    /// The available balance of an account is its default token balance minus what is reserved for storage.
+    /// If the account has no default balance it is counted as a balance of 0.0 FLOW
+    pub fun defaultTokenAvailableBalance(_ accountAddress: Address): UFix64 {
+        //get balance of account
+        let acct = getAccount(accountAddress)
+        var balance = 0.0
+        if let balanceRef = acct
+            .getCapability(/public/flowTokenBalance)
+            .borrow<&FlowToken.Vault{FungibleToken.Balance}>() {
+            balance = balanceRef.balance
+        }
+
+        // get how much should be reserved for storage
+        var reserved = self.defaultTokenReservedBalance(accountAddress)
+
+        return balance.saturatingSubtract(reserved)
+    }
+
+    /// Gets "reserved" balance of an account
+    ///
+    /// The reserved balance of an account is its storage used multiplied by the storage cost per flow token.
+    /// The reserved balance is at least the minimum storage reservation.
+    pub fun defaultTokenReservedBalance(_ accountAddress: Address): UFix64 {
+        let acct = getAccount(accountAddress)
+        var reserved = self.storageCapacityToFlow(self.convertUInt64StorageBytesToUFix64Megabytes(acct.storageUsed))
+        // at least self.minimumStorageReservation should be reserved
+        if reserved < self.minimumStorageReservation {
+            reserved = self.minimumStorageReservation
+        }
+
+        return reserved
+    }
+
+    init() {
+        self.storageMegaBytesPerReservedFLOW = 1.0 // 1 Mb per 1 Flow token
+        self.minimumStorageReservation = 0.0 // or 0 kb of minimum storage reservation
+
+        let admin <- create Administrator()
+        self.account.save(<-admin, to: /storage/storageFeesAdmin)
+    }
+}
+ 

package/contracts/FlowToken.cdc

@@ -0,0 +1,274 @@
+import "FungibleToken"
+import "MetadataViews"
+import "FungibleTokenMetadataViews"
+import "ViewResolver"
+
+pub contract FlowToken: FungibleToken, ViewResolver {
+
+    // Total supply of Flow tokens in existence
+    pub var totalSupply: UFix64
+
+    // Event that is emitted when the contract is created
+    pub event TokensInitialized(initialSupply: UFix64)
+
+    // Event that is emitted when tokens are withdrawn from a Vault
+    pub event TokensWithdrawn(amount: UFix64, from: Address?)
+
+    // Event that is emitted when tokens are deposited to a Vault
+    pub event TokensDeposited(amount: UFix64, to: Address?)
+
+    // Event that is emitted when new tokens are minted
+    pub event TokensMinted(amount: UFix64)
+
+    // Event that is emitted when tokens are destroyed
+    pub event TokensBurned(amount: UFix64)
+
+    // Event that is emitted when a new minter resource is created
+    pub event MinterCreated(allowedAmount: UFix64)
+
+    // Event that is emitted when a new burner resource is created
+    pub event BurnerCreated()
+
+    // Vault
+    //
+    // 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.
+    //
+    pub resource Vault: FungibleToken.Provider, FungibleToken.Receiver, FungibleToken.Balance, MetadataViews.Resolver {
+
+        // holds the balance of a users tokens
+        pub var balance: UFix64
+
+        // initialize the balance at resource creation time
+        init(balance: UFix64) {
+            self.balance = balance
+        }
+
+        // withdraw
+        //
+        // Function that takes an integer 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.
+        //
+        pub fun withdraw(amount: UFix64): @FungibleToken.Vault {
+            self.balance = self.balance - amount
+            emit TokensWithdrawn(amount: amount, from: self.owner?.address)
+            return <-create Vault(balance: amount)
+        }
+
+        // deposit
+        //
+        // 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.
+        pub fun deposit(from: @FungibleToken.Vault) {
+            let vault <- from as! @FlowToken.Vault
+            self.balance = self.balance + vault.balance
+            emit TokensDeposited(amount: vault.balance, to: self.owner?.address)
+            vault.balance = 0.0
+            destroy vault
+        }
+
+        destroy() {
+            if self.balance > 0.0 {
+                FlowToken.totalSupply = FlowToken.totalSupply - self.balance
+            }
+        }
+
+        /// Get all the Metadata Views implemented by FlowToken
+        ///
+        /// @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 FlowToken.getViews()
+        }
+
+        /// Get a Metadata View from FlowToken
+        ///
+        /// @param view: The Type of the desired view.
+        /// @return A structure representing the requested view.
+        ///
+        pub fun resolveView(_ view: Type): AnyStruct? {
+            return FlowToken.resolveView(view)
+        }
+    }
+
+    // createEmptyVault
+    //
+    // 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.
+    //
+    pub fun createEmptyVault(): @FungibleToken.Vault {
+        return <-create Vault(balance: 0.0)
+    }
+
+    pub fun getViews(): [Type] {
+        return [Type<FungibleTokenMetadataViews.FTView>(),
+                Type<FungibleTokenMetadataViews.FTDisplay>(),
+                Type<FungibleTokenMetadataViews.FTVaultData>()]
+    }
+
+    /// Get a Metadata View from FlowToken
+    ///
+    /// @param view: The Type of the desired view.
+    /// @return A structure representing the requested view.
+    ///
+    pub fun resolveView(_ view: Type): AnyStruct? {
+        switch view {
+            case Type<FungibleTokenMetadataViews.FTView>():
+                return FungibleTokenMetadataViews.FTView(
+                    ftDisplay: self.resolveView(Type<FungibleTokenMetadataViews.FTDisplay>()) as! FungibleTokenMetadataViews.FTDisplay?,
+                    ftVaultData: self.resolveView(Type<FungibleTokenMetadataViews.FTVaultData>()) as! FungibleTokenMetadataViews.FTVaultData?
+                )
+            case Type<FungibleTokenMetadataViews.FTDisplay>():
+                let media = MetadataViews.Media(
+                        file: MetadataViews.HTTPFile(
+                        url: "https://assets.website-files.com/5f6294c0c7a8cdd643b1c820/5f6294c0c7a8cda55cb1c936_Flow_Wordmark.svg"
+                    ),
+                    mediaType: "image/svg+xml"
+                )
+                let medias = MetadataViews.Medias([media])
+                return FungibleTokenMetadataViews.FTDisplay(
+                    name: "FLOW Network Token",
+                    symbol: "FLOW",
+                    description: "FLOW is the protocol token that is required for transaction fees, storage fees, staking, and many applications built on the Flow Blockchain",
+                    externalURL: MetadataViews.ExternalURL("https://flow.com"),
+                    logos: medias,
+                    socials: {
+                        "twitter": MetadataViews.ExternalURL("https://twitter.com/flow_blockchain")
+                    }
+                )
+            case Type<FungibleTokenMetadataViews.FTVaultData>():
+                return FungibleTokenMetadataViews.FTVaultData(
+                    storagePath: /storage/flowTokenVault,
+                    receiverPath: /public/flowTokenReceiver,
+                    metadataPath: /public/flowTokenBalance,
+                    providerPath: /private/flowTokenVault,
+                    receiverLinkedType: Type<&FlowToken.Vault{FungibleToken.Receiver, FungibleToken.Balance, MetadataViews.Resolver}>(),
+                    metadataLinkedType: Type<&FlowToken.Vault{FungibleToken.Balance, MetadataViews.Resolver}>(),
+                    providerLinkedType: Type<&FlowToken.Vault{FungibleToken.Provider}>(),
+                    createEmptyVaultFunction: (fun (): @FungibleToken.Vault {
+                        return <-FlowToken.createEmptyVault()
+                    })
+                )
+        }
+        return nil
+    }
+
+    pub resource Administrator {
+        // createNewMinter
+        //
+        // Function that creates and returns a new minter resource
+        //
+        pub fun createNewMinter(allowedAmount: UFix64): @Minter {
+            emit MinterCreated(allowedAmount: allowedAmount)
+            return <-create Minter(allowedAmount: allowedAmount)
+        }
+
+        // createNewBurner
+        //
+        // Function that creates and returns a new burner resource
+        //
+        pub fun createNewBurner(): @Burner {
+            emit BurnerCreated()
+            return <-create Burner()
+        }
+    }
+
+    // Minter
+    //
+    // Resource object that token admin accounts can hold to mint new tokens.
+    //
+    pub resource Minter {
+
+        // the amount of tokens that the minter is allowed to mint
+        pub var allowedAmount: UFix64
+
+        // mintTokens
+        //
+        // Function that mints new tokens, adds them to the total supply,
+        // and returns them to the calling context.
+        //
+        pub fun mintTokens(amount: UFix64): @FlowToken.Vault {
+            pre {
+                amount > UFix64(0): "Amount minted must be greater than zero"
+                amount <= self.allowedAmount: "Amount minted must be less than the allowed amount"
+            }
+            FlowToken.totalSupply = FlowToken.totalSupply + amount
+            self.allowedAmount = self.allowedAmount - amount
+            emit TokensMinted(amount: amount)
+            return <-create Vault(balance: amount)
+        }
+
+        init(allowedAmount: UFix64) {
+            self.allowedAmount = allowedAmount
+        }
+    }
+
+    // Burner
+    //
+    // Resource object that token admin accounts can hold to burn tokens.
+    //
+    pub resource Burner {
+
+        // burnTokens
+        //
+        // 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.
+        //
+        pub fun burnTokens(from: @FungibleToken.Vault) {
+            let vault <- from as! @FlowToken.Vault
+            let amount = vault.balance
+            destroy vault
+            emit TokensBurned(amount: amount)
+        }
+    }
+
+    init(adminAccount: AuthAccount) {
+        self.totalSupply = 0.0
+
+        // Create the Vault with the total supply of tokens and save it in storage
+        //
+        let vault <- create Vault(balance: self.totalSupply)
+        adminAccount.save(<-vault, to: /storage/flowTokenVault)
+
+        // Create a public capability to the stored Vault that only exposes
+        // the `deposit` method through the `Receiver` interface
+        //
+        adminAccount.link<&FlowToken.Vault{FungibleToken.Receiver, FungibleToken.Balance, MetadataViews.Resolver}>(
+            /public/flowTokenReceiver,
+            target: /storage/flowTokenVault
+        )
+
+        // Create a public capability to the stored Vault that only exposes
+        // the `balance` field through the `Balance` interface
+        //
+        adminAccount.link<&FlowToken.Vault{FungibleToken.Balance, MetadataViews.Resolver}>(
+            /public/flowTokenBalance,
+            target: /storage/flowTokenVault
+        )
+
+        let admin <- create Administrator()
+        adminAccount.save(<-admin, to: /storage/flowTokenAdmin)
+
+        // Emit an event that shows that the contract was initialized
+        emit TokensInitialized(initialSupply: self.totalSupply)
+    }
+}