@flowtyio/flow-contracts 0.0.17 → 0.1.0-beta.1

package/contracts/FungibleToken.cdc

@@ -2,21 +2,18 @@
 
 # The Flow Fungible Token standard
 
-## `FungibleToken` contract interface
+## `FungibleToken` contract
 
-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.
+The Fungible Token standard is no longer an interface
+that all fungible token contracts would have to conform to.
 
-## `Vault` resource
+If a users wants to deploy a new token contract, their contract
+does not need to implement the FungibleToken interface, but their tokens
+do need to implement the interfaces defined in this contract.
 
-Each account that owns tokens would need to have an instance
-of the Vault resource stored in their account storage.
+## `Vault` resource interface
 
-The Vault resource has methods that the owner and other users can call.
+Each fungible token resource type needs to implement the `Vault` resource interface.
 
 ## `Provider`, `Receiver`, and `Balance` resource interfaces
 
@@ -32,32 +29,30 @@ 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 {
+import "ViewResolver"
 
-    /// 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
+/// FungibleToken
+///
+/// Fungible Token implementations are no longer required to implement the fungible token
+/// interface. We still have it as an interface here because there are some useful
+/// utility methods that many projects will still want to have on their contracts,
+/// but they are by no means required. all that is required is that the token
+/// implements the `Vault` interface
+access(all) contract FungibleToken {
 
-    /// The event that is emitted when the contract is created
-    pub event TokensInitialized(initialSupply: UFix64)
+    // An entitlement for allowing the withdrawal of tokens from a Vault
+    access(all) entitlement Withdrawable
 
     /// The event that is emitted when tokens are withdrawn from a Vault
-    pub event TokensWithdrawn(amount: UFix64, from: Address?)
+    access(all) event Withdraw(amount: UFix64, from: Address?, type: String)
 
-    /// The event that is emitted when tokens are deposited into a Vault
-    pub event TokensDeposited(amount: UFix64, to: Address?)
+    /// The event that is emitted when tokens are deposited to a Vault
+    access(all) event Deposit(amount: UFix64, to: Address?, type: String)
 
+    /// Provider
+    ///
     /// The interface that enforces the requirements for withdrawing
     /// tokens from the implementing type.
     ///
@@ -65,9 +60,9 @@ pub contract interface FungibleToken {
     /// because it leaves open the possibility of creating custom providers
     /// that do not necessarily need their own balance.
     ///
-    pub resource interface Provider {
+    access(all) resource interface Provider {
 
-        /// Subtracts tokens from the owner's Vault
+        /// withdraw 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
@@ -82,18 +77,18 @@ pub contract interface FungibleToken {
         /// 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 {
+        access(Withdrawable) fun withdraw(amount: UFix64): @{Vault} {
             post {
                 // `result` refers to the return value
-                result.balance == amount:
+                result.getBalance() == amount:
                     "Withdrawal amount must be the same as the balance of the withdrawn Vault"
+                emit Withdraw(amount: amount, from: self.owner?.address, type: self.getType().identifier)
             }
         }
     }
 
+    /// Receiver
+    ///
     /// The interface that enforces the requirements for depositing
     /// tokens into the implementing type.
     ///
@@ -102,30 +97,41 @@ pub contract interface FungibleToken {
     /// can do custom things with the tokens, like split them up and
     /// send them to different places.
     ///
-    pub resource interface Receiver {
+    access(all) 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
+        /// deposit takes a Vault and deposits it into the implementing resource type
         ///
-        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} {
+        access(all) fun deposit(from: @{Vault})
+
+        /// getSupportedVaultTypes optionally returns a list of vault types that this receiver accepts
+        access(all) view fun getSupportedVaultTypes(): {Type: Bool} {
+            pre { true: "dummy" }
+        }
+
+        /// Returns whether or not the given type is accepted by the Receiver
+        /// A vault that can accept any type should just return true by default
+        access(all) view fun isSupportedVaultType(type: Type): Bool {
+            pre { true: "dummy" }
+        }
+    }
+
+    /// Vault
+    ///
+    /// Ideally, this interface would also conform to Receiver, Balance, Transferor, Provider, and Resolver
+    /// but that is not supported yet
+    ///
+    access(all) resource interface Vault: Receiver, Provider, ViewResolver.Resolver {
+
+        //access(all) event ResourceDestroyed(balance: UFix64 = self.getBalance())
+
+        /// Get the balance of the vault
+        access(all) view fun getBalance(): UFix64
+
+        /// getSupportedVaultTypes optionally returns a list of vault types that this receiver accepts
+        access(all) view 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>()) {
+            // 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
@@ -133,105 +139,63 @@ pub contract interface FungibleToken {
                 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"
-            }
+        access(all) view fun isSupportedVaultType(type: Type): Bool {
+            return self.getSupportedVaultTypes()[type] ?? false
         }
 
-        /// 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 []
-        }
+        /// Returns the storage path where the vault should typically be stored
+        access(all) view fun getDefaultStoragePath(): StoragePath?
 
-        /// 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? {
+        /// Returns the public path where this vault should have a public capability
+        access(all) view fun getDefaultPublicPath(): PublicPath?
+
+        /// Returns the public path where this vault's Receiver should have a public capability
+        /// Publishing a Receiver Capability at a different path enables alternate Receiver implementations to be used
+        /// in the same canonical namespace as the underlying Vault.
+        access(all) view fun getDefaultReceiverPath(): PublicPath? {
             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
+        /// withdraw 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 {
+        access(Withdrawable) fun withdraw(amount: UFix64): @{Vault} {
             pre {
-                self.balance >= amount:
+                self.getBalance() >= 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"
+                self.getBalance() == before(self.getBalance()) - amount:
+                    "New Vault balance must be the difference of the previous balance and the withdrawn Vault balance"
             }
         }
 
-        /// Takes a Vault and deposits it into the implementing resource type
-        ///
-        /// @param from: The Vault resource containing the funds that will be deposited
+        /// deposit takes a Vault and adds its balance to the balance of this Vault
         ///
-        pub fun deposit(from: @Vault) {
+        access(all) fun deposit(from: @{FungibleToken.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()): 
+                from.isInstance(self.getType()):
                     "Cannot deposit an incompatible token type"
+                emit Deposit(amount: from.getBalance(), to: self.owner?.address, type: from.getType().identifier)
             }
             post {
-                self.balance == before(self.balance) + before(from.balance):
+                self.getBalance() == before(self.getBalance()) + before(from.getBalance()):
                     "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"
+        /// createEmptyVault allows any user to create a new Vault that has a zero balance
+        ///
+        access(all) fun createEmptyVault(): @{Vault} {
+            post {
+                result.getBalance() == 0.0: "The newly created Vault must have zero balance"
+            }
         }
     }
-}
+}

package/contracts/FungibleTokenMetadataViews.cdc

@@ -1,24 +1,26 @@
 import "FungibleToken"
 import "MetadataViews"
+import "ViewResolver"
 
 /// This contract implements the metadata standard proposed
 /// in FLIP-1087.
-/// 
-/// Ref: https://github.com/onflow/flow/blob/master/flips/20220811-fungible-tokens-metadata.md
-/// 
+///
+/// Ref: https://github.com/onflow/flips/blob/main/application/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.
 ///
-pub contract FungibleTokenMetadataViews {
-    /// FTView wraps FTDisplay and FTVaultData, and is used to give a complete 
-    /// picture of a Fungible Token. Most Fungible Token contracts should 
+access(all) contract FungibleTokenMetadataViews {
+
+    /// 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.
     ///
-    pub struct FTView {
-        pub let ftDisplay: FTDisplay?     
-        pub let ftVaultData: FTVaultData?
-        init(
+    access(all) struct FTView {
+        access(all) let ftDisplay: FTDisplay?
+        access(all) let ftVaultData: FTVaultData?
+        view init(
             ftDisplay: FTDisplay?,
             ftVaultData: FTVaultData?
         ) {
@@ -32,7 +34,7 @@ pub contract FungibleTokenMetadataViews {
     /// @param viewResolver: A reference to the resolver resource
     /// @return A FTView struct
     ///
-    pub fun getFTView(viewResolver: &{MetadataViews.Resolver}): FTView {
+    access(all) fun getFTView(viewResolver: &{ViewResolver.Resolver}): FTView {
         let maybeFTView = viewResolver.resolveView(Type<FTView>())
         if let ftView = maybeFTView {
             return ftView as! FTView
@@ -43,38 +45,38 @@ pub contract FungibleTokenMetadataViews {
         )
     }
 
-    /// View to expose the information needed to showcase this FT. 
-    /// This can be used by applications to give an overview and 
+    /// 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.
     ///
-    pub struct FTDisplay {
+    access(all) struct FTDisplay {
         /// The display name for this token.
         ///
         /// Example: "Flow"
         ///
-        pub let name: String
+        access(all) let name: String
 
         /// The abbreviated symbol for this token.
         ///
         /// Example: "FLOW"
-        pub let symbol: String
+        access(all) let symbol: String
 
         /// A description the provides an overview of this token.
         ///
         /// Example: "The FLOW token is the native currency of the Flow network."
-        pub let description: String
+        access(all) let description: String
 
         /// External link to a URL to view more information about the fungible token.
-        pub let externalURL: MetadataViews.ExternalURL
+        access(all) let externalURL: MetadataViews.ExternalURL
 
         /// One or more versions of the fungible token logo.
-        pub let logos: MetadataViews.Medias
+        access(all) let logos: MetadataViews.Medias
 
         /// Social links to reach the fungible token's social homepages.
         /// Possible keys may be "instagram", "twitter", "discord", etc.
-        pub let socials: {String: MetadataViews.ExternalURL}
+        access(all) let socials: {String: MetadataViews.ExternalURL}
 
-        init(
+        view init(
             name: String,
             symbol: String,
             description: String,
@@ -92,11 +94,11 @@ pub contract FungibleTokenMetadataViews {
     }
 
     /// Helper to get FTDisplay in a way that will return a typed optional.
-    /// 
+    ///
     /// @param viewResolver: A reference to the resolver resource
     /// @return An optional FTDisplay struct
     ///
-    pub fun getFTDisplay(_ viewResolver: &{MetadataViews.Resolver}): FTDisplay? {
+    access(all) fun getFTDisplay(_ viewResolver: &{ViewResolver.Resolver}): FTDisplay? {
         if let maybeDisplayView = viewResolver.resolveView(Type<FTDisplay>()) {
             if let displayView = maybeDisplayView as? FTDisplay {
                 return displayView
@@ -106,40 +108,40 @@ pub contract FungibleTokenMetadataViews {
     }
 
     /// 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 
+    /// This can be used by applications to setup a FT vault with proper
     /// storage and public capabilities.
     ///
-    pub struct FTVaultData {
+    access(all) struct FTVaultData {
         /// Path in storage where this FT vault is recommended to be stored.
-        pub let storagePath: StoragePath
+        access(all) let storagePath: StoragePath
 
         /// Public path which must be linked to expose the public receiver capability.
-        pub let receiverPath: PublicPath
+        access(all) let receiverPath: PublicPath
 
         /// Public path which must be linked to expose the balance and resolver public capabilities.
-        pub let metadataPath: PublicPath
+        access(all) let metadataPath: PublicPath
 
-        /// Private path which should be linked to expose the provider capability to withdraw funds 
+        /// Private path which should be linked to expose the provider capability to withdraw funds
         /// from the vault.
-        pub let providerPath: PrivatePath
+        access(all) let providerPath: PrivatePath
 
-        /// Type that should be linked at the `receiverPath`. This is a restricted type requiring 
+        /// Type that should be linked at the `receiverPath`. This is a restricted type requiring
         /// the `FungibleToken.Receiver` interface.
-        pub let receiverLinkedType: Type
+        access(all) let receiverLinkedType: Type
 
-        /// Type that should be linked at the `receiverPath`. This is a restricted type requiring 
-        /// the `FungibleToken.Balance` and `MetadataViews.Resolver` interfaces.
-        pub let metadataLinkedType: Type
+        /// Type that should be linked at the `receiverPath`. This is a restricted type requiring
+        /// the `ViewResolver.Resolver` interfaces.
+        access(all) let metadataLinkedType: Type
 
-        /// Type that should be linked at the aforementioned private path. This 
+        /// Type that should be linked at the aforementioned private path. This
         /// is normally a restricted type with at a minimum the `FungibleToken.Provider` interface.
-        pub let providerLinkedType: Type
+        access(all) let providerLinkedType: Type
 
         /// Function that allows creation of an empty FT vault that is intended
         /// to store the funds.
-        pub let createEmptyVault: ((): @FungibleToken.Vault)
+        access(all) let createEmptyVault: fun(): @{FungibleToken.Vault}
 
-        init(
+        view init(
             storagePath: StoragePath,
             receiverPath: PublicPath,
             metadataPath: PublicPath,
@@ -147,11 +149,11 @@ pub contract FungibleTokenMetadataViews {
             receiverLinkedType: Type,
             metadataLinkedType: Type,
             providerLinkedType: Type,
-            createEmptyVaultFunction: ((): @FungibleToken.Vault)
+            createEmptyVaultFunction: fun(): @{FungibleToken.Vault}
         ) {
             pre {
                 receiverLinkedType.isSubtype(of: Type<&{FungibleToken.Receiver}>()): "Receiver public type must include FungibleToken.Receiver."
-                metadataLinkedType.isSubtype(of: Type<&{FungibleToken.Balance, MetadataViews.Resolver}>()): "Metadata public type must include FungibleToken.Balance and MetadataViews.Resolver interfaces."
+                metadataLinkedType.isSubtype(of: Type<&{ViewResolver.Resolver}>()): "Metadata public type must include ViewResolver.Resolver interfaces."
                 providerLinkedType.isSubtype(of: Type<&{FungibleToken.Provider}>()): "Provider type must include FungibleToken.Provider interface."
             }
             self.storagePath = storagePath
@@ -170,7 +172,7 @@ pub contract FungibleTokenMetadataViews {
     /// @param viewResolver: A reference to the resolver resource
     /// @return A optional FTVaultData struct
     ///
-    pub fun getFTVaultData(_ viewResolver: &{MetadataViews.Resolver}): FTVaultData? {
+    access(all) fun getFTVaultData(_ viewResolver: &{ViewResolver.Resolver}): FTVaultData? {
         if let view = viewResolver.resolveView(Type<FTVaultData>()) {
             if let v = view as? FTVaultData {
                 return v
@@ -179,5 +181,12 @@ pub contract FungibleTokenMetadataViews {
         return nil
     }
 
+    /// View to expose the total supply of the Vault's token
+    access(all) struct TotalSupply {
+        access(all) let supply: UFix64
+
+        view init(totalSupply: UFix64) {
+            self.supply = totalSupply
+        }
+    }
 }
-