@flowtyio/flow-contracts 0.0.18 → 0.1.0-beta.2

package/contracts/NonFungibleToken.cdc

@@ -4,11 +4,11 @@
 
 ## `NonFungibleToken` contract interface
 
-The interface that all Non-Fungible Token contracts could conform to.
+The interface that all Non-Fungible Token contracts should conform to.
 If a user wants to deploy a new NFT contract, their contract would need
 to implement the NonFungibleToken interface.
 
-Their contract would have to follow all the rules and naming
+Their contract must follow all the rules and naming
 that the interface specifies.
 
 ## `NFT` resource
@@ -41,162 +41,151 @@ Collection to complete the transfer.
 
 */
 
+import "ViewResolver"
+
 /// The main NFT contract interface. Other NFT contracts will
 /// import and implement this interface
 ///
-pub contract interface NonFungibleToken {
+access(all) contract NonFungibleToken {
+
+    /// An entitlement for allowing the withdrawal of tokens from a Vault
+    access(all) entitlement Withdrawable
 
-    /// The total number of tokens of this type in existence
-    pub var totalSupply: UInt64
+    /// An entitlement for allowing updates and update events for an NFT
+    access(all) entitlement Updatable
 
-    /// Event that emitted when the NFT contract is initialized
+    /// Event that contracts should emit when the metadata of an NFT is updated
+    /// It can only be emitted by calling the `emitNFTUpdated` function
+    /// with an `Updatable` entitled reference to the NFT that was updated
+    /// The entitlement prevents spammers from calling this from other users' collections
+    /// because only code within a collection or that has special entitled access
+    /// to the collections methods will be able to get the entitled reference
+    ///
+    /// The event makes it so that third-party indexers can monitor the events
+    /// and query the updated metadata from the owners' collections.
     ///
-    pub event ContractInitialized()
+    access(all) event Updated(id: UInt64, uuid: UInt64, owner: Address?, type: String)
+    access(all) view fun emitNFTUpdated(_ nftRef: auth(Updatable) &{NonFungibleToken.NFT})
+    {
+        emit Updated(id: nftRef.getID(), uuid: nftRef.uuid, owner: nftRef.owner?.address, type: nftRef.getType().identifier)
+    }
+
 
     /// Event that is emitted when a token is withdrawn,
     /// indicating the owner of the collection that it was withdrawn from.
     ///
     /// If the collection is not in an account's storage, `from` will be `nil`.
     ///
-    pub event Withdraw(id: UInt64, from: Address?)
+    access(all) event Withdraw(id: UInt64, uuid: UInt64, from: Address?, type: String)
 
     /// Event that emitted when a token is deposited to a collection.
     ///
     /// It indicates the owner of the collection that it was deposited to.
     ///
-    pub event Deposit(id: UInt64, to: Address?)
+    access(all) event Deposit(id: UInt64, uuid: UInt64, to: Address?, type: String)
 
-    /// Interface that the NFTs have to conform to
-    /// The metadata views methods are included here temporarily
-    /// because enforcing the metadata interfaces in the standard
-    /// would break many contracts in an upgrade. Those breaking changes
-    /// are being saved for the stable cadence milestone
+    /// Interface that the NFTs must conform to
     ///
-    pub resource interface INFT {
+    access(all) resource interface NFT: ViewResolver.Resolver {
         /// The unique ID that each NFT has
-        pub let id: UInt64
+        access(all) view fun getID(): UInt64
 
-        /// Function that returns all the Metadata Views implemented by a Non 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 []
-        }
+        // access(all) event ResourceDestroyed(uuid: UInt64 = self.uuid, type: self.getType().identifier)
 
-        /// Function that resolves a metadata view for this token.
+        /// Get a reference to an NFT that this NFT owns
+        /// Both arguments are optional to allow the NFT to choose
+        /// how it returns sub NFTs depending on what arguments are provided
+        /// For example, if `type` has a value, but `id` doesn't, the NFT
+        /// can choose which NFT of that type to return if there is a "default"
+        /// If both are `nil`, then NFTs that only store a single NFT can just return
+        /// that. This helps callers who aren't sure what they are looking for
         ///
-        /// @param view: The Type of the desired view.
-        /// @return A structure representing the requested view.
+        /// @param type: The Type of the desired NFT
+        /// @param id: The id of the NFT to borrow
         ///
-        pub fun resolveView(_ view: Type): AnyStruct? {
+        /// @return A structure representing the requested view.
+        access(all) fun getSubNFT(type: Type, id: UInt64) : &{NonFungibleToken.NFT}? {
             return nil
         }
     }
 
-    /// Requirement that all conforming NFT smart contracts have
-    /// to define a resource called NFT that conforms to INFT
-    ///
-    pub resource NFT: INFT {
-        pub let id: UInt64
-    }
-
     /// Interface to mediate withdraws from the Collection
     ///
-    pub resource interface Provider {
-        /// Removes an NFT from the resource implementing it and moves it to the caller
-        ///
-        /// @param withdrawID: The ID of the NFT that will be removed
-        /// @return The NFT resource removed from the implementing resource
-        ///
-        pub fun withdraw(withdrawID: UInt64): @NFT {
+    access(all) resource interface Provider {
+
+        // We emit withdraw events from the provider interface because conficting withdraw
+        // events aren't as confusing to event listeners as conflicting deposit events
+
+        /// withdraw removes an NFT from the collection and moves it to the caller
+        /// It does not specify whether the ID is UUID or not
+        access(Withdrawable) fun withdraw(withdrawID: UInt64): @{NFT} {
             post {
-                result.id == withdrawID: "The ID of the withdrawn token must be the same as the requested ID"
+                result.getID() == withdrawID: "The ID of the withdrawn token must be the same as the requested ID"
+                emit Withdraw(id: result.getID(), uuid: result.uuid, from: self.owner?.address, type: result.getType().identifier)
             }
         }
     }
 
     /// Interface to mediate deposits to the Collection
     ///
-    pub resource interface Receiver {
+    access(all) resource interface Receiver {
 
-        /// Adds an NFT to the resource implementing it
+        /// deposit takes an NFT as an argument and adds it to the Collection
         ///
-        /// @param token: The NFT resource that will be deposited
-        ///
-        pub fun deposit(token: @NFT)
-    }
+        access(all) fun deposit(token: @{NFT})
 
-    /// Interface that an account would commonly 
-    /// publish for their collection
-    ///
-    pub resource interface CollectionPublic {
-        pub fun deposit(token: @NFT)
-        pub fun getIDs(): [UInt64]
-        pub fun borrowNFT(id: UInt64): &NFT
-        /// Safe way to borrow a reference to an NFT that does not panic
-        ///
-        /// @param id: The ID of the NFT that want to be borrowed
-        /// @return An optional reference to the desired NFT, will be nil if the passed id does not exist
-        ///
-        pub fun borrowNFTSafe(id: UInt64): &NFT? {
-            post {
-                result == nil || result!.id == id: "The returned reference's ID does not match the requested ID"
-            }
-            return nil
-        }
+        /// getSupportedNFTTypes returns a list of NFT types that this receiver accepts
+        access(all) view fun getSupportedNFTTypes(): {Type: Bool}
+
+        /// Returns whether or not the given type is accepted by the collection
+        /// A collection that can accept any type should just return true by default
+        access(all) view fun isSupportedNFTType(type: Type): Bool
     }
 
     /// Requirement for the concrete resource type
     /// to be declared in the implementing contract
     ///
-    pub resource Collection: Provider, Receiver, CollectionPublic {
+    access(all) resource interface Collection: Provider, Receiver, ViewResolver.ResolverCollection {
 
-        /// Dictionary to hold the NFTs in the Collection
-        pub var ownedNFTs: @{UInt64: NFT}
+        /// Return the default storage path for the collection
+        access(all) view fun getDefaultStoragePath(): StoragePath?
 
-        /// Removes an NFT from the collection and moves it to the caller
-        ///
-        /// @param withdrawID: The ID of the NFT that will be withdrawn
-        /// @return The resource containing the desired NFT
-        ///
-        pub fun withdraw(withdrawID: UInt64): @NFT
+        /// Return the default public path for the collection
+        access(all) view fun getDefaultPublicPath(): PublicPath?
 
-        /// Takes a NFT and adds it to the collections dictionary
-        /// and adds the ID to the ID array
-        /// 
-        /// @param token: An NFT resource
-        ///
-        pub fun deposit(token: @NFT)
+        /// Normally we would require that the collection specify
+        /// a specific dictionary to store the NFTs, but this isn't necessary any more
+        /// as long as all the other functions are there
 
-        /// Returns an array of the IDs that are in the collection
-        ///
-        /// @return An array containing all the IDs on the collection
-        ///
-        pub fun getIDs(): [UInt64]
+        /// createEmptyCollection creates an empty Collection
+        /// and returns it to the caller so that they can own NFTs
+        access(all) fun createEmptyCollection(): @{Collection} {
+            post {
+                result.getLength() == 0: "The created collection must be empty!"
+            }
+        }
 
-        /// Returns a borrowed reference to an NFT in the collection
-        /// so that the caller can read data and call methods from it
-        ///
-        /// @param id: The ID of the NFT that want to be borrowed
-        /// @return A reference to the NFT
-        ///
-        pub fun borrowNFT(id: UInt64): &NFT {
+        /// deposit takes a NFT and adds it to the collections dictionary
+        /// and adds the ID to the id array
+        access(all) fun deposit(token: @{NonFungibleToken.NFT}) {
             pre {
-                self.ownedNFTs[id] != nil: "NFT does not exist in the collection!"
+                // We emit the deposit event in the `Collection` interface
+                // because the `Collection` interface is almost always the final destination
+                // of tokens and deposit emissions from custom receivers could be confusing
+                // and hard to reconcile to event listeners
+                emit Deposit(id: token.getID(), uuid: token.uuid, to: self.owner?.address, type: token.getType().identifier)
             }
         }
-    }
 
-    /// Creates an empty Collection and returns it to the caller so that they can own NFTs
-    ///
-    /// @return A new Collection resource
-    /// 
-    pub fun createEmptyCollection(): @Collection {
-        post {
-            result.getIDs().length == 0: "The created collection must be empty!"
+        /// Gets the amount of NFTs stored in the collection
+        access(all) view fun getLength(): Int
+
+        access(all) view fun borrowNFT(_ id: UInt64): &{NonFungibleToken.NFT}? {
+            post {
+                (result == nil) || (result?.getID() == id):
+                    "Cannot borrow NFT reference: The ID of the returned reference does not match the ID that was specified"
+            }
+            return nil
         }
     }
 }
- 

package/contracts/ViewResolver.cdc

@@ -1,15 +1,16 @@
-// Taken from the NFT Metadata standard, this contract exposes an interface to let 
+// Taken from the NFT Metadata standard, this contract exposes an interface to let
 // anyone borrow a contract and resolve views on it.
 //
 // This will allow you to obtain information about a contract without necessarily knowing anything about it.
 // All you need is its address and name and you're good to go!
-pub contract interface ViewResolver {
+access(all) contract interface ViewResolver {
+
     /// Function that returns all the Metadata Views implemented by the resolving contract
     ///
     /// @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] {
+    access(all) view fun getViews(): [Type] {
         return []
     }
 
@@ -18,8 +19,36 @@ pub contract interface ViewResolver {
     /// @param view: The Type of the desired view.
     /// @return A structure representing the requested view.
     ///
-    pub fun resolveView(_ view: Type): AnyStruct? {
+    access(all) fun resolveView(_ view: Type): AnyStruct? {
         return nil
     }
+
+    /// Provides access to a set of metadata views. A struct or
+    /// resource (e.g. an NFT) can implement this interface to provide access to
+    /// the views that it supports.
+    ///
+    access(all) resource interface Resolver {
+
+        /// Same as getViews above, but on a specific NFT instead of a contract
+        access(all) view fun getViews(): [Type] {
+            return []
+        }
+
+        /// Same as resolveView above, but on a specific NFT instead of a contract
+        access(all) fun resolveView(_ view: Type): AnyStruct? {
+            return nil
+        }
+    }
+
+    /// A group of view resolvers indexed by ID.
+    ///
+    access(all) resource interface ResolverCollection {
+        access(all) view fun borrowViewResolver(id: UInt64): &{Resolver}? {
+            return nil
+        }
+
+        access(all) view fun getIDs(): [UInt64] {
+            return []
+        }
+    }
 }
- 

package/contracts/lost-and-found/FeeEstimator.cdc

@@ -11,49 +11,41 @@ import "FlowToken"
 
     Consumers of this contract would then need to pop the resource out of the DepositEstimate resource to get it back
  */
-pub contract FeeEstimator {
-    pub resource DepositEstimate {
-        pub var item: @AnyResource?
-        pub var storageFee: UFix64
+access(all) contract FeeEstimator {
+    access(all) resource DepositEstimate {
+        access(all) var item: @AnyResource?
+        access(all) var storageFee: UFix64
 
         init(item: @AnyResource, storageFee: UFix64) {
             self.item <- item
             self.storageFee = storageFee
         }
 
-        pub fun withdraw(): @AnyResource {
-            let resource <- self.item <- nil
-            return <-resource!
-        }
-
-        destroy() {
-            pre {
-                self.item == nil: "cannot destroy with non-null item"
-            }
-
-            destroy self.item
+        access(all) fun withdraw(): @AnyResource {
+            let r <- self.item <- nil
+            return <-r!
         }
     }
 
-    pub fun hasStorageCapacity(_ addr: Address, _ storageFee: UFix64): Bool {
+    access(all) fun hasStorageCapacity(_ addr: Address, _ storageFee: UFix64): Bool {
         return FlowStorageFees.defaultTokenAvailableBalance(addr) > storageFee
     }
 
-    pub fun estimateDeposit(
+    access(all) fun estimateDeposit(
         item: @AnyResource,
     ): @DepositEstimate {
-        let storageUsedBefore = FeeEstimator.account.storageUsed
-        FeeEstimator.account.save(<-item, to: /storage/temp)
-        let storageUsedAfter = FeeEstimator.account.storageUsed
+        let storageUsedBefore = FeeEstimator.account.storage.used
+        FeeEstimator.account.storage.save(<-item, to: /storage/temp)
+        let storageUsedAfter = FeeEstimator.account.storage.used
 
         let storageDiff = storageUsedAfter - storageUsedBefore
         let storageFee = FeeEstimator.storageUsedToFlowAmount(storageDiff)
-        let loadedItem <- FeeEstimator.account.load<@AnyResource>(from: /storage/temp)!
+        let loadedItem <- FeeEstimator.account.storage.load<@AnyResource>(from: /storage/temp)!
         let estimate <- create DepositEstimate(item: <-loadedItem, storageFee: storageFee)
         return <- estimate
     }
 
-    pub fun storageUsedToFlowAmount(_ storageUsed: UInt64): UFix64 {
+    access(all) fun storageUsedToFlowAmount(_ storageUsed: UInt64): UFix64 {
         let storageMB = FlowStorageFees.convertUInt64StorageBytesToUFix64Megabytes(storageUsed)
         return FlowStorageFees.storageCapacityToFlow(storageMB)
     }