@flowtyio/flow-contracts 0.1.0-beta.9 → 0.1.1

package/README.md

@@ -49,7 +49,7 @@ Currently, the list includes:
 | FTProviderFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | FTReceiverFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | NFTCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
-| NFTProviderAndCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| NFTProviderAndCollectionFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | NFTProviderFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 | NFTCatalog | 0x49a7cda3a1eecc29 | 0x324c34e1c517e4db |
 | NFTCatalogAdmin | 0x49a7cda3a1eecc29 | 0x324c34e1c517e4db |

package/contracts/FungibleTokenSwitchboard.cdc

@@ -0,0 +1,360 @@
+import "FungibleToken"
+
+/// The contract that allows an account to receive payments in multiple fungible
+/// tokens using a single `{FungibleToken.Receiver}` capability.
+/// This capability should ideally be stored at the 
+/// `FungibleTokenSwitchboard.ReceiverPublicPath = /public/GenericFTReceiver`
+/// but it can be stored anywhere.
+/// 
+access(all) contract FungibleTokenSwitchboard {
+  
+    // Storage and Public Paths
+    access(all) let StoragePath: StoragePath
+    access(all) let PublicPath: PublicPath
+    access(all) let ReceiverPublicPath: PublicPath
+
+    access(all) entitlement Owner
+
+    /// The event that is emitted when a new vault capability is added to a
+    /// switchboard resource.
+    /// 
+    access(all) event VaultCapabilityAdded(type: Type, switchboardOwner: Address?, 
+                                    capabilityOwner: Address?)
+
+    /// The event that is emitted when a vault capability is removed from a 
+    /// switchboard resource.
+    /// 
+    access(all) event VaultCapabilityRemoved(type: Type,  switchboardOwner: Address?, 
+                                        capabilityOwner: Address?)
+
+    /// The event that is emitted when a deposit can not be completed.
+    /// 
+    access(all) event NotCompletedDeposit(type: Type, amount: UFix64, 
+                                    switchboardOwner: Address?)
+
+    /// The interface that enforces the method to allow anyone to check on the
+    /// available capabilities of a switchboard resource and also exposes the 
+    /// deposit methods to deposit funds on it.
+    /// 
+    access(all) resource interface SwitchboardPublic {
+        access(all) view fun getVaultTypesWithAddress(): {Type: Address}
+        access(all) view fun getSupportedVaultTypes(): {Type: Bool}
+        access(all) view fun isSupportedVaultType(type: Type): Bool
+        access(all) fun deposit(from: @{FungibleToken.Vault})
+        access(all) fun safeDeposit(from: @{FungibleToken.Vault}): @{FungibleToken.Vault}?
+        access(all) view fun safeBorrowByType(type: Type): &{FungibleToken.Receiver}?
+    }
+
+    /// The resource that stores the multiple fungible token receiver 
+    /// capabilities, allowing the owner to add and remove them and anyone to 
+    /// deposit any fungible token among the available types.
+    /// 
+    access(all) resource Switchboard: FungibleToken.Receiver, SwitchboardPublic {
+       
+        /// Dictionary holding the fungible token receiver capabilities, 
+        /// indexed by the fungible token vault type.
+        /// 
+        access(contract) var receiverCapabilities: {Type: Capability<&{FungibleToken.Receiver}>}
+
+        /// Adds a new fungible token receiver capability to the switchboard 
+        /// resource.
+        /// 
+        /// @param capability: The capability to expose a certain fungible
+        /// token vault deposit function through `{FungibleToken.Receiver}` that
+        /// will be added to the switchboard.
+        /// 
+        access(Owner) fun addNewVault(capability: Capability<&{FungibleToken.Receiver}>) {
+            // Borrow a reference to the vault pointed to by the capability we 
+            // want to store inside the switchboard
+            let vaultRef = capability.borrow() 
+                        ?? panic ("Cannot borrow reference to vault from capability")
+            // Check if there is a previous capability for this token, if not
+            if (self.receiverCapabilities[vaultRef.getType()] == nil) {
+                // use the vault reference type as key for storing the 
+                // capability and then
+                self.receiverCapabilities[vaultRef.getType()] = capability
+                // emit the event that indicates that a new capability has been 
+                // added
+                emit VaultCapabilityAdded(type: vaultRef.getType(),
+                                               switchboardOwner: self.owner?.address, 
+                                                 capabilityOwner: capability.address)
+            } else {
+                // If there was already a capability for that token, panic
+                panic("There is already a vault in the Switchboard for this token")
+            }
+        }
+
+        /// Adds a number of new fungible token receiver capabilities by using
+        /// the paths where they are stored.
+        ///                    
+        /// @param paths: The paths where the public capabilities are stored.
+        /// @param address: The address of the owner of the capabilities.
+        /// 
+        access(Owner) fun addNewVaultsByPath(paths: [PublicPath], address: Address) {
+            // Get the account where the public capabilities are stored
+            let owner = getAccount(address)
+            // For each path, get the saved capability and store it 
+            // into the switchboard's receiver capabilities dictionary
+            for path in paths {
+                let capability = owner.capabilities.get<&{FungibleToken.Receiver}>(path)
+                // Borrow a reference to the vault pointed to by the capability
+                // we want to store inside the switchboard
+                // If the vault was borrowed successfully...
+                if let vaultRef = capability.borrow() {
+                    // ...and if there is no previous capability added for that token
+                    if (self.receiverCapabilities[vaultRef!.getType()] == nil) {
+                        // Use the vault reference type as key for storing the
+                        // capability
+                        self.receiverCapabilities[vaultRef!.getType()] = capability
+                        // and emit the event that indicates that a new
+                        // capability has been added
+                        emit VaultCapabilityAdded(type: vaultRef.getType(),
+                            switchboardOwner: self.owner?.address,
+                            capabilityOwner: address,
+                        )
+                    }
+                }
+            }
+        }
+
+        /// Adds a new fungible token receiver capability to the switchboard 
+        /// resource specifying which `Type` of `@{FungibleToken.Vault}` can be 
+        /// deposited to it. Use it to include in your switchboard "wrapper"
+        /// receivers such as a `@TokenForwarding.Forwarder`. It can also be
+        /// used to overwrite the type attached to a certain capability without 
+        /// having to remove that capability first.
+        ///
+        /// @param capability: The capability to expose a certain fungible
+        /// token vault deposit function through `{FungibleToken.Receiver}` that
+        /// will be added to the switchboard.
+        ///
+        /// @param type: The type of fungible token that can be deposited to that
+        /// capability, rather than the `Type` from the reference borrowed from
+        /// said capability
+        /// 
+        access(Owner) fun addNewVaultWrapper(capability: Capability<&{FungibleToken.Receiver}>, 
+                                                                        type: Type) {
+            // Check if the capability is working
+            assert(capability.check(), message: "The passed capability is not valid")
+            // Use the type parameter as key for the capability
+            self.receiverCapabilities[type] = capability
+            // emit the event that indicates that a new capability has been 
+            // added
+            emit VaultCapabilityAdded(
+                type: type,
+                switchboardOwner: self.owner?.address,
+                capabilityOwner: capability.address,
+            )
+        }
+
+        /// Adds zero or more new fungible token receiver capabilities to the  
+        /// switchboard resource specifying which `Type`s of `@{FungibleToken.Vault}`s  
+        /// can be deposited to it. Use it to include in your switchboard "wrapper"
+        /// receivers such as a `@TokenForwarding.Forwarder`. It can also be
+        /// used to overwrite the types attached to certain capabilities without 
+        /// having to remove those capabilities first.
+        ///                    
+        /// @param paths: The paths where the public capabilities are stored.
+        /// @param types: The types of the fungible token to be deposited on each path.
+        /// @param address: The address of the owner of the capabilities.
+        /// 
+        access(Owner) fun addNewVaultWrappersByPath(paths: [PublicPath], types: [Type], 
+                                                                  address: Address) {
+            // Get the account where the public capabilities are stored
+            let owner = getAccount(address)
+            // For each path, get the saved capability and store it 
+            // into the switchboard's receiver capabilities dictionary
+            for i, path in paths {
+                let capability = owner.capabilities.get<&{FungibleToken.Receiver}>(path)
+                // Borrow a reference to the vault pointed to by the capability
+                // we want to store inside the switchboard
+                // If the vault was borrowed successfully...
+                if let vaultRef = capability.borrow() {
+                    // Use the vault reference type as key for storing the capability
+                    self.receiverCapabilities[types[i]] = capability
+                    // and emit the event that indicates that a new capability has been added
+                    emit VaultCapabilityAdded(
+                        type: types[i],
+                        switchboardOwner: self.owner?.address,
+                        capabilityOwner: address,
+                    )
+                }
+            }
+        }
+
+        /// Removes a fungible token receiver capability from the switchboard
+        /// resource.
+        /// 
+        /// @param capability: The capability to a fungible token vault to be
+        /// removed from the switchboard.
+        /// 
+        access(Owner) fun removeVault(capability: Capability<&{FungibleToken.Receiver}>) {
+            // Borrow a reference to the vault pointed to by the capability we 
+            // want to remove from the switchboard
+            let vaultRef = capability.borrow()
+                        ?? panic ("Cannot borrow reference to vault from capability")
+            // Use the vault reference to find the capability to remove
+            self.receiverCapabilities.remove(key: vaultRef.getType())
+            // Emit the event that indicates that a new capability has been 
+            // removed
+            emit VaultCapabilityRemoved(
+                type: vaultRef.getType(),
+                switchboardOwner: self.owner?.address,
+                capabilityOwner: capability.address,
+            )
+        }
+        
+        /// Takes a fungible token vault and routes it to the proper fungible 
+        /// token receiver capability for depositing it.
+        /// 
+        /// @param from: The deposited fungible token vault resource.
+        /// 
+        access(all) fun deposit(from: @{FungibleToken.Vault}) {
+            // Get the capability from the ones stored at the switchboard
+            let depositedVaultCapability = self.receiverCapabilities[from.getType()]
+                ?? panic ("The deposited vault is not available on this switchboard")
+
+            // Borrow the reference to the desired vault
+            let vaultRef = depositedVaultCapability.borrow()
+                ?? panic ("Can not borrow a reference to the the vault")
+
+            vaultRef.deposit(from: <-from)
+        }
+
+        /// Takes a fungible token vault and tries to route it to the proper
+        /// fungible token receiver capability for depositing the funds, 
+        /// avoiding panicking if the vault is not available.
+        ///             
+        /// @param vaultType: The type of the ft vault that wants to be 
+        /// deposited.
+        /// 
+        /// @return The deposited fungible token vault resource, without the
+        /// funds if the deposit was successful, or still containing the funds
+        /// if the reference to the needed vault was not found.
+        /// 
+        access(all) fun safeDeposit(from: @{FungibleToken.Vault}): @{FungibleToken.Vault}? {
+            // Try to get the proper vault capability from the switchboard
+            // If the desired vault is present on the switchboard...
+            if let depositedVaultCapability = self.receiverCapabilities[from.getType()] {
+                // We try to borrow a reference to the vault from the capability
+                // If we can borrow a reference to the vault...
+                if let vaultRef = depositedVaultCapability.borrow() {
+                    // We deposit the funds on said vault
+                    vaultRef.deposit(from: <-from.withdraw(amount: from.balance))
+                }
+            }
+            // if deposit failed for some reason
+            if from.balance > 0.0 {
+                emit NotCompletedDeposit(
+                    type: from.getType(),
+                    amount: from.balance,
+                    switchboardOwner: self.owner?.address,
+                )
+                return <-from
+            }
+            destroy from 
+            return nil
+        }
+
+        /// Checks that the capability tied to a type is valid
+        ///
+        /// @param vaultType: The type of the ft vault whose capability needs to be checked
+        ///
+        /// @return a boolean marking the capability for a type as valid or not
+        access(all) view fun checkReceiverByType(type: Type): Bool {
+            if self.receiverCapabilities[type] == nil {
+                return false
+            }
+
+            return self.receiverCapabilities[type]!.check()
+        }
+
+        /// Gets the receiver assigned to a provided vault type.
+        /// This is necessary because without it, it is not possible to look under the hood and see if a capability
+        /// is of an expected type or not. This helps guard against infinitely chained TokenForwarding or other invalid 
+        /// malicious kinds of updates that could prevent listings from being made that are valid on storefronts.
+        ///
+        /// @param vaultType: The type of the ft vault whose capability needs to be checked
+        ///
+        /// @return an optional receiver capability for consumers of the switchboard to check/validate on their own
+        access(all) view fun safeBorrowByType(type: Type): &{FungibleToken.Receiver}? {
+            if !self.checkReceiverByType(type: type) {
+                return nil
+            }
+
+            return self.receiverCapabilities[type]!.borrow()
+        }
+
+        /// A getter function to know which tokens a certain switchboard 
+        /// resource is prepared to receive along with the address where
+        /// those tokens will be deposited.
+        ///
+        /// @return A dictionary mapping the `{FungibleToken.Receiver}` 
+        /// type to the receiver owner's address 
+        ///
+        access(all) view fun getVaultTypesWithAddress(): {Type: Address} {
+            let effectiveTypesWithAddress: {Type: Address} = {}
+            // Check if each capability is live
+            for vaultType in self.receiverCapabilities.keys {
+                if self.receiverCapabilities[vaultType]!.check() {
+                    // and attach it to the owner's address
+                    effectiveTypesWithAddress[vaultType] = self.receiverCapabilities[vaultType]!.address
+                }
+            }
+            return effectiveTypesWithAddress
+        }
+
+        /// A getter function that returns the token types supported by this resource,
+        /// which can be deposited using the 'deposit' function.
+        ///
+        /// @return Dictionary of FT types that can be deposited.
+        access(all) view fun getSupportedVaultTypes(): {Type: Bool} { 
+            let supportedVaults: {Type: Bool} = {}
+            for receiverType in self.receiverCapabilities.keys {
+                if self.receiverCapabilities[receiverType]!.check() {
+                    if receiverType.isSubtype(of: Type<@{FungibleToken.Vault}>()) {
+                        supportedVaults[receiverType] = true
+                    }
+                    if receiverType.isSubtype(of: Type<@{FungibleToken.Receiver}>()) {
+                        let receiverRef = self.receiverCapabilities[receiverType]!.borrow()!
+                        let subReceiverSupportedTypes = receiverRef.getSupportedVaultTypes()
+                        for subReceiverType in subReceiverSupportedTypes.keys {                          
+                            if subReceiverType.isSubtype(of: Type<@{FungibleToken.Vault}>()) {
+                                supportedVaults[subReceiverType] = true
+                            }
+                        }
+                    }
+                }
+            }
+            return supportedVaults
+        }
+
+        /// 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 {
+            let supportedVaults = self.getSupportedVaultTypes()
+            if let supported = supportedVaults[type] {
+                return supported
+            } else { return false }
+        }
+
+        init() {
+            // Initialize the capabilities dictionary
+            self.receiverCapabilities = {}
+        }
+
+    }
+
+    /// Function that allows to create a new blank switchboard. A user must call
+    /// this function and store the returned resource in their storage.
+    ///
+    access(all) fun createSwitchboard(): @Switchboard {
+        return <-create Switchboard()
+    }
+
+    init() {
+        self.StoragePath = /storage/fungibleTokenSwitchboard
+        self.PublicPath = /public/fungibleTokenSwitchboardPublic
+        self.ReceiverPublicPath = /public/GenericFTReceiver
+    }
+}

package/contracts/MetadataViews.cdc

@@ -126,8 +126,32 @@ access(all) contract MetadataViews {
         }
     }
 
-    /// View to represent a file with an correspoiding mediaType.
-    ///
+    /// A struct to represent a generic URI. May be used to represent the URI of
+    /// the NFT where the type of URI is not able to be determined (i.e. HTTP,
+    /// IPFS, etc.)
+    ///
+    access(all) struct URI: File {
+        /// The base URI prefix, if any. Not needed for all URIs, but helpful
+        /// for some use cases For example, updating a whole NFT collection's
+        /// image host easily
+        ///
+        access(all) let baseURI: String?
+        /// The URI string value
+        /// NOTE: this is set on init as a concatenation of the baseURI and the
+        /// value if baseURI != nil
+        ///
+        access(self) let value: String
+
+        access(all) view fun uri(): String {
+            return self.value
+        }
+
+        init(baseURI: String?, value: String) {
+            self.baseURI = baseURI
+            self.value = baseURI != nil ? baseURI!.concat(value) : value
+        }
+    }
+
     access(all) struct Media {
 
         /// File for the media
@@ -185,7 +209,7 @@ access(all) contract MetadataViews {
     /// Helper to get License in a typesafe way
     ///
     /// @param viewResolver: A reference to the resolver resource
-    /// @return A optional License struct
+    /// @return An optional License struct
     ///
     access(all) fun getLicense(_ viewResolver: &{ViewResolver.Resolver}) : License? {
         if let view = viewResolver.resolveView(Type<License>()) {
@@ -212,7 +236,7 @@ access(all) contract MetadataViews {
     /// Helper to get ExternalURL in a typesafe way
     ///
     /// @param viewResolver: A reference to the resolver resource
-    /// @return A optional ExternalURL struct
+    /// @return An optional ExternalURL struct
     ///
     access(all) fun getExternalURL(_ viewResolver: &{ViewResolver.Resolver}) : ExternalURL? {
         if let view = viewResolver.resolveView(Type<ExternalURL>()) {
@@ -665,7 +689,7 @@ access(all) contract MetadataViews {
         // Square-sized image to represent this collection.
         access(all) let squareImage: MetadataViews.Media
 
-        // Banner-sized image for this collection, recommended to have a size near 1200x630.
+        // Banner-sized image for this collection, recommended to have a size near 1400x350.
         access(all) let bannerImage: MetadataViews.Media
 
         // Social links to reach this collection's social homepages.
@@ -703,4 +727,53 @@ access(all) contract MetadataViews {
         }
         return nil
     }
-}
+    /// This view may be used by Cadence-native projects to define their
+    /// contract- and token-level metadata according to EVM-compatible formats.
+    /// Several ERC standards (e.g. ERC20, ERC721, etc.) expose name and symbol
+    /// values to define assets as well as contract- & token-level metadata view
+    /// `tokenURI(uint256)` and `contractURI()` methods. This view enables
+    /// Cadence projects to define in their own contracts how they would like
+    /// their metadata to be defined when bridged to EVM.
+    ///
+    access(all) struct EVMBridgedMetadata {
+
+        /// The name of the asset
+        ///
+        access(all) let name: String
+
+        /// The symbol of the asset
+        ///
+        access(all) let symbol: String
+
+        /// The URI of the asset - this can either be contract-level or
+        /// token-level URI depending on where the metadata is resolved. It
+        /// is recommended to reference EVM metadata standards for how to best
+        /// prepare your view's formatted value.
+        ///
+        /// For example, while you may choose to take advantage of onchain
+        /// metadata, as is the case for most Cadence NFTs, you may also choose
+        /// to represent your asset's metadata in IPFS and assign this value as
+        /// an IPFSFile struct pointing to that IPFS file. Alternatively, you
+        /// may serialize your NFT's metadata and assign it as a JSON string
+        /// data URL representating the NFT's onchain metadata at the time this
+        /// view is resolved.
+        ///
+        access(all) let uri: {File}
+
+        init(name: String, symbol: String, uri: {File}) {
+            self.name = name
+            self.symbol = symbol
+            self.uri = uri
+        }
+    }
+
+    access(all) fun getEVMBridgedMetadata(_ viewResolver: &{ViewResolver.Resolver}) : EVMBridgedMetadata? {
+        if let view = viewResolver.resolveView(Type<EVMBridgedMetadata>()) {
+            if let v = view as? EVMBridgedMetadata {
+                return v
+            }
+        }
+        return nil
+    }
+
+}

package/contracts/NonFungibleToken.cdc

@@ -49,9 +49,6 @@ access(all) contract interface NonFungibleToken: ViewResolver {
     /// An entitlement for allowing updates and update events for an NFT
     access(all) entitlement Update
 
-    /// entitlement for owner that grants Withdraw and Update
-    access(all) entitlement Owner
-
     /// 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
@@ -63,7 +60,7 @@ access(all) contract interface NonFungibleToken: ViewResolver {
     /// and query the updated metadata from the owners' collections.
     ///
     access(all) event Updated(type: String, id: UInt64, uuid: UInt64, owner: Address?)
-    access(contract) view fun emitNFTUpdated(_ nftRef: auth(Update | Owner) &{NonFungibleToken.NFT})
+    access(all) view fun emitNFTUpdated(_ nftRef: auth(Update) &{NonFungibleToken.NFT})
     {
         emit Updated(type: nftRef.getType().identifier, id: nftRef.id, uuid: nftRef.uuid, owner: nftRef.owner?.address)
     }
@@ -85,9 +82,6 @@ access(all) contract interface NonFungibleToken: ViewResolver {
     ///
     access(all) event Deposited(type: String, id: UInt64, uuid: UInt64, to: Address?, collectionUUID: UInt64)
 
-    /// Included for backwards-compatibility
-    access(all) resource interface INFT: NFT {}
-
     /// Interface that the NFTs must conform to
     ///
     access(all) resource interface NFT: ViewResolver.Resolver {
@@ -105,6 +99,7 @@ access(all) contract interface NonFungibleToken: ViewResolver {
         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"
             }
         }
 
@@ -141,7 +136,7 @@ access(all) contract interface NonFungibleToken: ViewResolver {
         /// withdraw removes an NFT from the collection and moves it to the caller
         /// It does not specify whether the ID is UUID or not
         /// @param withdrawID: The id of the NFT to withdraw from the collection
-        access(Withdraw | Owner) fun withdraw(withdrawID: UInt64): @{NFT} {
+        access(Withdraw) fun withdraw(withdrawID: UInt64): @{NFT} {
             post {
                 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)
@@ -174,6 +169,7 @@ access(all) contract interface NonFungibleToken: ViewResolver {
         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}?
     }
 
@@ -182,6 +178,8 @@ access(all) contract interface NonFungibleToken: ViewResolver {
     ///
     access(all) resource interface Collection: Provider, Receiver, CollectionPublic, ViewResolver.ResolverCollection {
 
+        access(all) var ownedNFTs: @{UInt64: {NonFungibleToken.NFT}}
+
         /// 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}) {
@@ -196,7 +194,16 @@ access(all) contract interface NonFungibleToken: ViewResolver {
 
         /// Gets the amount of NFTs stored in the collection
         /// @return An integer indicating the size of the collection
-        access(all) view fun getLength(): Int
+        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,
@@ -231,4 +238,4 @@ access(all) contract interface NonFungibleToken: ViewResolver {
             result.getIDs().length == 0: "The created collection must be empty!"
         }
     }
-}
+}

package/contracts/capability-cache/CapabilityCache.cdc

@@ -0,0 +1,97 @@
+/*
+https://github.com/Flowtyio/capability-cache
+
+CapabilityCache helps manage capabilities which are issued but are not in public paths.
+Rather than looping through all capabilities under a storage path and finding one that 
+matches the Capability type you want, the cache can be used to retrieve them
+*/
+access(all) contract CapabilityCache {
+
+    access(all) let basePathIdentifier: String
+
+    access(all) event CapabilityAdded(owner: Address?, cacheUuid: UInt64, namespace: String, resourceType: Type, capabilityType: Type, capabilityID: UInt64)
+    access(all) event CapabilityRemoved(owner: Address?, cacheUuid: UInt64, namespace: String, resourceType: Type, capabilityType: Type, capabilityID: UInt64)
+
+    // Add to a namespace
+    access(all) entitlement Add
+
+    // Remove from a namespace
+    access(all) entitlement Delete
+
+    // Retrieve a cap from the namespace
+    access(all) entitlement Get
+
+    // Resource that manages capabilities for a provided namespace. Only one capability is permitted per type.
+    access(all) resource Cache {
+        // A dictionary of resourceType -> CapabilityType -> Capability
+        // For example, one might store a Capability<auth(NonFungibleToken.Withdraw) &{NonFungibleToken.Collection}> for the @TopShot.NFT resource.
+        // Note that the resource type is not necessarily the type that the borrowed capability is an instance of. This is because some resource definitions
+        // might be reused.
+        access(self) let caps: {Type: {Type: Capability}}
+
+        // who is this capability cache maintained by? e.g. flowty, dapper, find? 
+        access(all) let namespace: String
+
+        // Remove a capability, if it exists, 
+        access(Delete) fun removeCapabilityByType(resourceType: Type, capabilityType: Type): Capability? {
+            if let ref = &self.caps[resourceType] as auth(Mutate) &{Type: Capability}? {
+                let cap = ref.remove(key: capabilityType)
+                if cap != nil {
+                    emit CapabilityRemoved(owner: self.owner?.address, cacheUuid: self.uuid, namespace: self.namespace, resourceType: resourceType, capabilityType: capabilityType, capabilityID: cap!.id)
+                }
+            }
+
+            return nil
+        }
+
+        // Adds a capability to the cache. If there is already an entry for the given type,
+        // it will be returned
+        access(Add) fun addCapability(resourceType: Type, cap: Capability): Capability? {
+            pre {
+                cap.id != 0: "cannot add a capability with id 0"
+            }
+
+            let capType = cap.getType()
+            emit CapabilityAdded(owner: self.owner?.address, cacheUuid: self.uuid, namespace: self.namespace, resourceType: resourceType, capabilityType: capType, capabilityID: cap.id)
+            if let ref = &self.caps[resourceType] as auth(Mutate) &{Type: Capability}? {
+                return ref.insert(key: capType, cap)
+            }
+
+            self.caps[resourceType] = {
+                capType: cap
+            }
+
+            return nil
+        }
+
+        // Retrieve a capability key'd by a given type.
+        access(Get) fun getCapabilityByType(resourceType: Type, capabilityType: Type): Capability? {
+            if let tmp = self.caps[resourceType] {
+                return tmp[capabilityType]
+            }
+
+            return nil
+        }
+
+        init(namespace: String) {
+            self.caps = {}
+
+            self.namespace = namespace
+        }
+    }
+
+    // There is no uniform storage path for the Capability Cache. Instead, each platform which issues capabilities
+    // should manage their own cache, and can generate the storage path to store it in with this helper method
+    access(all) fun getPathForCache(_ namespace: String): StoragePath {
+        return StoragePath(identifier: self.basePathIdentifier.concat(namespace))
+            ?? panic("invalid namespace value")
+    }
+
+    access(all) fun createCache(namespace: String): @Cache {
+        return <- create Cache(namespace: namespace)
+    }
+
+    init() {
+        self.basePathIdentifier = "CapabilityCache_".concat(self.account.address.toString()).concat("_")
+    }
+}