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

package/contracts/NonFungibleToken.cdc

@@ -2,20 +2,17 @@
 
 ## The Flow Non-Fungible Token standard
 
-## `NonFungibleToken` contract interface
+## `NonFungibleToken` contract
 
 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.
+If a user wants to deploy a new NFT contract, their contract should implement
+The types defined here
 
-Their contract must follow all the rules and naming
-that the interface specifies.
-
-## `NFT` resource
+## `NFT` resource interface
 
 The core resource type that represents an NFT in the smart contract.
 
-## `Collection` Resource
+## `Collection` Resource interface
 
 The resource that stores a user's NFT collection.
 It includes a few functions to allow the owner to easily
@@ -26,10 +23,8 @@ move tokens in and out of the collection.
 These interfaces declare functions with some pre and post conditions
 that require the Collection to follow certain naming and behavior standards.
 
-They are separate because it gives the user the ability to share a reference
-to their Collection that only exposes the fields and 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.
+They are separate because it gives developers the ability to define functions
+that can use any type that implements these interfaces
 
 By using resources and interfaces, users of NFT smart contracts can send
 and receive tokens peer-to-peer, without having to interact with a central ledger
@@ -43,16 +38,16 @@ Collection to complete the transfer.
 
 import "ViewResolver"
 
-/// The main NFT contract interface. Other NFT contracts will
-/// import and implement this interface
+/// The main NFT contract. Other NFT contracts will
+/// import and implement the interfaces defined in this contract
 ///
-access(all) contract NonFungibleToken {
+access(all) contract interface NonFungibleToken: ViewResolver {
 
     /// An entitlement for allowing the withdrawal of tokens from a Vault
-    access(all) entitlement Withdrawable
+    access(all) entitlement Withdraw
 
     /// An entitlement for allowing updates and update events for an NFT
-    access(all) entitlement Updatable
+    access(all) entitlement Update
 
     /// Event that contracts should emit when the metadata of an NFT is updated
     /// It can only be emitted by calling the `emitNFTUpdated` function
@@ -60,45 +55,67 @@ access(all) contract NonFungibleToken {
     /// 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.
     ///
-    access(all) event Updated(id: UInt64, uuid: UInt64, owner: Address?, type: String)
-    access(all) view fun emitNFTUpdated(_ nftRef: auth(Updatable) &{NonFungibleToken.NFT})
+    access(all) event Updated(type: String, id: UInt64, uuid: UInt64, owner: Address?)
+    access(all) view fun emitNFTUpdated(_ nftRef: auth(Update) &{NonFungibleToken.NFT})
     {
-        emit Updated(id: nftRef.getID(), uuid: nftRef.uuid, owner: nftRef.owner?.address, type: nftRef.getType().identifier)
+        emit Updated(type: nftRef.getType().identifier, id: nftRef.id, uuid: nftRef.uuid, owner: nftRef.owner?.address)
     }
 
 
     /// Event that is emitted when a token is withdrawn,
-    /// indicating the owner of the collection that it was withdrawn from.
+    /// indicating the type, id, uuid, the owner of the collection that it was withdrawn from,
+    /// and the UUID of the resource it was withdrawn from, usually a collection.
     ///
     /// If the collection is not in an account's storage, `from` will be `nil`.
     ///
-    access(all) event Withdraw(id: UInt64, uuid: UInt64, from: Address?, type: String)
+    access(all) event Withdrawn(type: String, id: UInt64, uuid: UInt64, from: Address?, providerUUID: UInt64)
 
     /// Event that emitted when a token is deposited to a collection.
+    /// Indicates the type, id, uuid, the owner of the collection that it was deposited to,
+    /// and the UUID of the collection it was deposited to
     ///
-    /// It indicates the owner of the collection that it was deposited to.
+    /// If the collection is not in an account's storage, `from`, will be `nil`.
     ///
-    access(all) event Deposit(id: UInt64, uuid: UInt64, to: Address?, type: String)
+    access(all) event Deposited(type: String, id: UInt64, uuid: UInt64, to: Address?, collectionUUID: UInt64)
 
     /// Interface that the NFTs must conform to
     ///
     access(all) resource interface NFT: ViewResolver.Resolver {
-        /// The unique ID that each NFT has
-        access(all) view fun getID(): UInt64
 
-        // access(all) event ResourceDestroyed(uuid: UInt64 = self.uuid, type: self.getType().identifier)
+        /// unique ID for the NFT
+        access(all) let id: UInt64
+
+        /// Event that is emitted automatically every time a resource is destroyed
+        /// The type information is included in the metadata event so it is not needed as an argument
+        access(all) event ResourceDestroyed(id: UInt64 = self.id, uuid: UInt64 = self.uuid)
+
+        /// createEmptyCollection creates an empty Collection that is able to store the NFT
+        /// and returns it to the caller so that they can own NFTs
+        /// @return A an empty collection that can store this NFT
+        access(all) fun createEmptyCollection(): @{Collection} {
+            post {
+                result.getLength() == 0: "The created collection must be empty!"
+                result.isSupportedNFTType(type: self.getType()): "The created collection must support this NFT type"
+            }
+        }
+
+        /// Gets all the NFTs that this NFT directly owns
+        /// @return A dictionary of all subNFTS keyed by type
+        access(all) view fun getAvailableSubNFTS(): {Type: UInt64} {
+            return {}
+        }
 
         /// 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
+        /// 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
+        /// that. This helps callers who aren't sure what they are looking for 
         ///
         /// @param type: The Type of the desired NFT
         /// @param id: The id of the NFT to borrow
@@ -109,7 +126,7 @@ access(all) contract NonFungibleToken {
         }
     }
 
-    /// Interface to mediate withdraws from the Collection
+    /// Interface to mediate withdrawals from a resource, usually a Collection
     ///
     access(all) resource interface Provider {
 
@@ -118,10 +135,11 @@ access(all) contract NonFungibleToken {
 
         /// 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} {
+        /// @param withdrawID: The id of the NFT to withdraw from the collection
+        access(Withdraw) fun withdraw(withdrawID: UInt64): @{NFT} {
             post {
-                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)
+                result.id == withdrawID: "The ID of the withdrawn token must be the same as the requested ID"
+                emit Withdrawn(type: result.getType().identifier, id: result.id, uuid: result.uuid, from: self.owner?.address, providerUUID: self.uuid)
             }
         }
     }
@@ -131,61 +149,93 @@ access(all) contract NonFungibleToken {
     access(all) resource interface Receiver {
 
         /// deposit takes an NFT as an argument and adds it to the Collection
-        ///
+        /// @param token: The NFT to deposit
         access(all) fun deposit(token: @{NFT})
 
         /// getSupportedNFTTypes returns a list of NFT types that this receiver accepts
+        /// @return A dictionary of types mapped to booleans indicating if this
+        ///         reciever supports it
         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
+        /// @param type: An NFT type
+        /// @return A boolean indicating if this receiver can recieve the desired NFT type
         access(all) view fun isSupportedNFTType(type: Type): Bool
     }
 
+    /// Kept for backwards-compatibility reasons
+    access(all) resource interface CollectionPublic {
+        access(all) fun deposit(token: @{NFT})
+        access(all) view fun getLength(): Int
+        access(all) view fun getIDs(): [UInt64]
+        access(all) fun forEachID(_ f: fun (UInt64): Bool): Void
+        access(all) view fun borrowNFT(_ id: UInt64): &{NFT}?
+    }
+
     /// Requirement for the concrete resource type
     /// to be declared in the implementing contract
     ///
-    access(all) resource interface Collection: Provider, Receiver, ViewResolver.ResolverCollection {
-
-        /// Return the default storage path for the collection
-        access(all) view fun getDefaultStoragePath(): StoragePath?
-
-        /// Return the default public path for the collection
-        access(all) view fun getDefaultPublicPath(): PublicPath?
+    access(all) resource interface Collection: Provider, Receiver, CollectionPublic, ViewResolver.ResolverCollection {
 
-        /// 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
+        access(all) var ownedNFTs: @{UInt64: {NonFungibleToken.NFT}}
 
-        /// 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!"
-            }
-        }
-
-        /// deposit takes a NFT and adds it to the collections dictionary
-        /// and adds the ID to the id array
+        /// deposit takes a NFT as an argument and stores it in the collection
+        /// @param token: The NFT to deposit into the collection
         access(all) fun deposit(token: @{NonFungibleToken.NFT}) {
             pre {
                 // 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)
+                emit Deposited(type: token.getType().identifier, id: token.id, uuid: token.uuid, to: self.owner?.address, collectionUUID: self.uuid)
             }
         }
 
         /// Gets the amount of NFTs stored in the collection
-        access(all) view fun getLength(): Int
+        /// @return An integer indicating the size of the collection
+        access(all) view fun getLength(): Int {
+            return self.ownedNFTs.length
+        }
 
+        /// Allows a given function to iterate through the list
+        /// of owned NFT IDs in a collection without first
+        /// having to load the entire list into memory
+        access(all) fun forEachID(_ f: fun (UInt64): Bool): Void {
+            self.ownedNFTs.forEachKey(f)
+        }
+
+        /// Borrows a reference to an NFT stored in the collection
+        /// If the NFT with the specified ID is not in the collection,
+        /// the function should return `nil` and not panic.
+        ///
+        /// @param id: The desired nft id in the collection to return a referece for.
+        /// @return An optional reference to the NFT
         access(all) view fun borrowNFT(_ id: UInt64): &{NonFungibleToken.NFT}? {
             post {
-                (result == nil) || (result?.getID() == id):
+                (result == nil) || (result?.id == id): 
                     "Cannot borrow NFT reference: The ID of the returned reference does not match the ID that was specified"
             }
-            return nil
+        }
+
+        /// createEmptyCollection creates an empty Collection of the same type
+        /// and returns it to the caller
+        /// @return A an empty collection of the same type
+        access(all) fun createEmptyCollection(): @{Collection} {
+            post {
+                result.getType() == self.getType(): "The created collection does not have the same type as this collection"
+                result.getLength() == 0: "The created collection must be empty!"
+            }
+        }
+    }
+
+    /// createEmptyCollection creates an empty Collection for the specified NFT type
+    /// and returns it to the caller so that they can own NFTs
+    /// @param nftType: The desired nft type to return a collection for.
+    /// @return An array of NFT Types that the implementing contract defines.
+    access(all) fun createEmptyCollection(nftType: Type): @{NonFungibleToken.Collection} {
+        post {
+            result.getIDs().length == 0: "The created collection must be empty!"
         }
     }
-}
+}

package/contracts/TokenForwarding.cdc

@@ -16,29 +16,37 @@ their tokens to.
 
 import "FungibleToken"
 
-pub contract TokenForwarding {
+access(all) contract TokenForwarding {
 
     // Event that is emitted when tokens are deposited to the target receiver
-    pub event ForwardedDeposit(amount: UFix64, from: Address?)
+    access(all) event ForwardedDeposit(amount: UFix64, from: Address?)
 
-    pub resource interface ForwarderPublic {
-        pub fun check(): Bool
-        pub fun safeBorrow(): &{FungibleToken.Receiver}?
+    access(all) resource interface ForwarderPublic {
+        access(all) fun check(): Bool
+        access(all) fun safeBorrow(): &{FungibleToken.Receiver}?
     }
 
-    pub resource Forwarder: FungibleToken.Receiver, ForwarderPublic {
+    access(all) resource Forwarder: FungibleToken.Receiver, ForwarderPublic {
 
         // This is where the deposited tokens will be sent.
         // The type indicates that it is a reference to a receiver
         //
         access(self) var recipient: Capability
 
+        access(all) view fun getSupportedVaultTypes(): {Type: Bool} {
+            return {}
+        }
+
+        access(all) view fun isSupportedVaultType(type: Type): Bool {
+            return true
+        }
+
         // deposit
         //
         // Function that takes a Vault object as an argument and forwards
         // it to the recipient's Vault using the stored reference
         //
-        pub fun deposit(from: @FungibleToken.Vault) {
+        access(all) fun deposit(from: @{FungibleToken.Vault}) {
             let receiverRef = self.recipient.borrow<&{FungibleToken.Receiver}>()!
 
             let balance = from.balance
@@ -48,17 +56,17 @@ pub contract TokenForwarding {
             emit ForwardedDeposit(amount: balance, from: self.owner?.address)
         }
 
-        pub fun check(): Bool {
+        access(all) fun check(): Bool {
             return self.recipient.check<&{FungibleToken.Receiver}>()
         }
 
-        pub fun safeBorrow(): &{FungibleToken.Receiver}? {
+        access(all) fun safeBorrow(): &{FungibleToken.Receiver}? {
             return self.recipient.borrow<&{FungibleToken.Receiver}>()
         }
 
         // changeRecipient changes the recipient of the forwarder to the provided recipient
         //
-        pub fun changeRecipient(_ newRecipient: Capability) {
+        access(all) fun changeRecipient(_ newRecipient: Capability) {
             pre {
                 newRecipient.borrow<&{FungibleToken.Receiver}>() != nil: "Could not borrow Receiver reference from the Capability"
             }
@@ -75,7 +83,7 @@ pub contract TokenForwarding {
 
     // createNewForwarder creates a new Forwarder reference with the provided recipient
     //
-    pub fun createNewForwarder(recipient: Capability): @Forwarder {
+    access(all) fun createNewForwarder(recipient: Capability): @Forwarder {
         return <-create Forwarder(recipient: recipient)
     }
 }

package/contracts/ViewResolver.cdc

@@ -1,43 +1,47 @@
-// 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!
 access(all) contract interface ViewResolver {
 
-    /// Function that returns all the Metadata Views implemented by the resolving contract
+    /// Function that returns all the Metadata Views implemented by the resolving contract.
+    /// Some contracts may have multiple resource types that support metadata views
+    /// so there there is an optional parameter for specify which resource type the caller
+    /// is looking for views for.
+    /// Some contract-level views may be type-agnostic. In that case, the contract
+    /// should return the same views regardless of what type is passed in.
     ///
+    /// @param resourceType: An optional resource type to return views for
     /// @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.
     ///
-    access(all) view fun getViews(): [Type] {
-        return []
-    }
+    access(all) view fun getContractViews(resourceType: Type?): [Type]
 
     /// Function that resolves a metadata view for this token.
+    /// Some contracts may have multiple resource types that support metadata views
+    /// so there there is an optional parameter for specify which resource type the caller
+    /// is looking for views for.
+    /// Some contract-level views may be type-agnostic. In that case, the contract
+    /// should return the same views regardless of what type is passed in.
     ///
+    /// @param resourceType: An optional resource type to return views for
     /// @param view: The Type of the desired view.
     /// @return A structure representing the requested view.
     ///
-    access(all) fun resolveView(_ view: Type): AnyStruct? {
-        return nil
-    }
+    access(all) fun resolveContractView(resourceType: Type?, viewType: Type): AnyStruct?
 
-    /// Provides access to a set of metadata views. A struct or
-    /// resource (e.g. an NFT) can implement this interface to provide access to
+    /// 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 []
-        }
+        access(all) view fun getViews(): [Type]
 
         /// Same as resolveView above, but on a specific NFT instead of a contract
-        access(all) fun resolveView(_ view: Type): AnyStruct? {
-            return nil
-        }
+        access(all) fun resolveView(_ view: Type): AnyStruct?
     }
 
     /// A group of view resolvers indexed by ID.