@flowtyio/flow-contracts 0.0.9 → 0.0.11

package/README.md

@@ -40,17 +40,17 @@ Currently, the list includes:
 | NonFungibleToken | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 |
 | MetadataViews | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 |
 | ViewResolver | 0x1d7e57aa55817448 | 0x631e88ae7f1d7c20 |
-| HybridCusody | 0x294e44e1ec6993c6 | N/A |
-| CapabilityFactory | 0x294e44e1ec6993c6 | N/A |
-| CapabilityFilter | 0x294e44e1ec6993c6 | N/A |
-| CapabilityDelegator | 0x294e44e1ec6993c6 | N/A |
-| FTAllFactory | 0x294e44e1ec6993c6 | N/A |
-| FTBalanceFactory | 0x294e44e1ec6993c6 | N/A |
-| FTProviderFactory | 0x294e44e1ec6993c6 | N/A |
-| FTReceiverFactory | 0x294e44e1ec6993c6 | N/A |
-| NFTCollectionPublicFactory | 0x294e44e1ec6993c6 | N/A |
-| NFTProviderAndCollectionPublicFactory | 0x294e44e1ec6993c6 | N/A |
-| NFTProviderFactory | 0x294e44e1ec6993c6 | N/A |
+| HybridCusody | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| CapabilityFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| CapabilityFilter | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| CapabilityDelegator | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| FTAllFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| FTBalanceFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| FTProviderFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| FTReceiverFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| NFTCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| NFTProviderAndCollectionPublicFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
+| NFTProviderFactory | 0x294e44e1ec6993c6 | 0xd8a7e05a7ac670c0 |
 
 
 ## Using a contract

package/contracts/hybrid-custody/CapabilityDelegator.cdc

@@ -0,0 +1,174 @@
+/// CapabilityDelegator is a contract used to share Capabiltities to other accounts. It is used by the
+/// HybridCustody contract to allow more flexible sharing of Capabilities when an app wants to share things
+/// that aren't the NFT-standard interface types.
+/// 
+/// Inside of CapabilityDelegator is a resource called `Delegator` which maintains a mapping of public and private
+/// Capabilities. They cannot and should not be mixed. A public `Delegator` is able to be borrowed by anyone, whereas a
+/// private `Delegator` can only be borrowed from the child account when you have access to the full `ChildAccount` 
+/// resource.
+///
+pub contract CapabilityDelegator {
+
+    /* --- Canonical Paths --- */
+    //
+    pub let StoragePath: StoragePath
+    pub let PrivatePath: PrivatePath
+    pub let PublicPath: PublicPath
+    
+    /* --- Events --- */
+    //
+    pub event DelegatorCreated(id: UInt64)
+    pub event DelegatorUpdated(id: UInt64, capabilityType: Type, isPublic: Bool, active: Bool)
+
+    /// Private interface for Capability retrieval
+    ///
+    pub resource interface GetterPrivate {
+        pub fun getPrivateCapability(_ type: Type): Capability? {
+            post {
+                result == nil || type.isSubtype(of: result.getType()): "incorrect returned capability type"
+            }
+        }
+        pub fun findFirstPrivateType(_ type: Type): Type?
+        pub fun getAllPrivate(): [Capability]
+    }
+
+    /// Exposes public Capability retrieval
+    ///
+    pub resource interface GetterPublic {
+        pub fun getPublicCapability(_ type: Type): Capability? {
+            post {
+                result == nil || type.isSubtype(of: result.getType()): "incorrect returned capability type "
+            }
+        }
+
+        pub fun findFirstPublicType(_ type: Type): Type?
+        pub fun getAllPublic(): [Capability]
+    }
+
+    /// This Delegator is used to store Capabilities, partitioned by public and private access with corresponding
+    /// GetterPublic and GetterPrivate conformances.AccountCapabilityController
+    ///
+    pub resource Delegator: GetterPublic, GetterPrivate {
+        access(self) let privateCapabilities: {Type: Capability}
+        access(self) let publicCapabilities: {Type: Capability}
+
+        // ------ Begin Getter methods
+        //
+        /// Returns the public Capability of the given Type if it exists
+        ///
+        pub fun getPublicCapability(_ type: Type): Capability? {
+            return self.publicCapabilities[type]
+        }
+
+        /// Returns the private Capability of the given Type if it exists
+        ///
+        ///
+        /// @param type: Type of the Capability to retrieve
+        /// @return Capability of the given Type if it exists, nil otherwise
+        ///
+        pub fun getPrivateCapability(_ type: Type): Capability? {
+            return self.privateCapabilities[type]
+        }
+
+        /// Returns all public Capabilities
+        ///
+        /// @return List of all public Capabilities
+        ///
+        pub fun getAllPublic(): [Capability] {
+            return self.publicCapabilities.values
+        }
+
+        /// Returns all private Capabilities
+        ///
+        /// @return List of all private Capabilities
+        ///
+        pub fun getAllPrivate(): [Capability] {
+            return self.privateCapabilities.values
+        }
+
+        /// Returns the first public Type that is a subtype of the given Type
+        ///
+        /// @param type: Type to check for subtypes
+        /// @return First public Type that is a subtype of the given Type, nil otherwise
+        ///
+        pub fun findFirstPublicType(_ type: Type): Type? {
+            for t in self.publicCapabilities.keys {
+                if t.isSubtype(of: type) {
+                    return t
+                }
+            }
+
+            return nil
+        }
+
+        /// Returns the first private Type that is a subtype of the given Type
+        ///
+        /// @param type: Type to check for subtypes
+        /// @return First private Type that is a subtype of the given Type, nil otherwise
+        ///
+        pub fun findFirstPrivateType(_ type: Type): Type? {
+            for t in self.privateCapabilities.keys {
+                if t.isSubtype(of: type) {
+                    return t
+                }
+            }
+
+            return nil
+        }
+        // ------- End Getter methods
+
+        /// Adds a Capability to the Delegator
+        ///
+        /// @param cap: Capability to add
+        /// @param isPublic: Whether the Capability should be public or private
+        ///
+        pub fun addCapability(cap: Capability, isPublic: Bool) {
+            pre {
+                cap.check<&AnyResource>(): "Invalid Capability provided"
+            }
+            if isPublic {
+                self.publicCapabilities.insert(key: cap.getType(), cap)
+            } else {
+                self.privateCapabilities.insert(key: cap.getType(), cap)
+            }
+            emit DelegatorUpdated(id: self.uuid, capabilityType: cap.getType(), isPublic: isPublic, active: true)
+        }
+
+        /// Removes a Capability from the Delegator
+        ///
+        /// @param cap: Capability to remove
+        ///
+        pub fun removeCapability(cap: Capability) {
+            if let removedPublic = self.publicCapabilities.remove(key: cap.getType()) {
+                emit DelegatorUpdated(id: self.uuid, capabilityType: cap.getType(), isPublic: true, active: false)
+            }
+            
+            if let removedPrivate = self.privateCapabilities.remove(key: cap.getType()) {
+                emit DelegatorUpdated(id: self.uuid, capabilityType: cap.getType(), isPublic: false, active: false)
+            }
+        }
+
+        init() {
+            self.privateCapabilities = {}
+            self.publicCapabilities = {}
+        }
+    }
+
+    /// Creates a new Delegator and returns it
+    /// 
+    /// @return Newly created Delegator
+    ///
+    pub fun createDelegator(): @Delegator {
+        let delegator <- create Delegator()
+        emit DelegatorCreated(id: delegator.uuid)
+        return <- delegator
+    }
+    
+    init() {
+        let identifier = "CapabilityDelegator_".concat(self.account.address.toString())
+        self.StoragePath = StoragePath(identifier: identifier)!
+        self.PrivatePath = PrivatePath(identifier: identifier)!
+        self.PublicPath = PublicPath(identifier: identifier)!
+    }
+}
+ 

package/contracts/hybrid-custody/CapabilityFactory.cdc

@@ -0,0 +1,105 @@
+/// # Capability Factory
+///
+/// This contract defines a Factory interface and a Manager resource to contain Factory implementations, as well as a
+/// Getter interface for retrieval of contained Factories.
+/// 
+/// A Factory is defines a method getCapability() which defines the retrieval pattern of a Capability from a given
+/// account at the specified path. This pattern arose out of a need to retrieve arbitrary & castable Capabilities from
+/// an account under the static typing constraints inherent to Cadence.
+///
+/// The Manager resource is a container for Factories, and implements the Getter interface.
+///
+/// **Note:** It's generally an anti-pattern to pass around AuthAccount references; however, the need for castable
+/// Capabilities is critical to the use case of Hybrid Custody. It's advised to use Factories sparingly and only for
+/// cases where Capabilities must be castable by the caller.
+///
+pub contract CapabilityFactory {
+    
+    pub let StoragePath: StoragePath
+    pub let PrivatePath: PrivatePath
+    pub let PublicPath: PublicPath
+    
+    /// Factory structures a common interface for Capability retrieval from a given account at a specified path
+    ///
+    pub struct interface Factory {
+        pub fun getCapability(acct: &AuthAccount, path: CapabilityPath): Capability
+    }
+
+    /// Getter defines an interface for retrieval of a Factory if contained within the implementing resource
+    ///
+    pub resource interface Getter {
+        pub fun getSupportedTypes(): [Type]
+        pub fun getFactory(_ t: Type): {CapabilityFactory.Factory}?
+    }
+
+    /// Manager is a resource that contains Factories and implements the Getter interface for retrieval of contained
+    /// Factories
+    ///
+    pub resource Manager: Getter {
+        /// Mapping of Factories indexed on Type of Capability they retrieve
+        pub let factories: {Type: {CapabilityFactory.Factory}}
+
+        /// Retrieves a list of Types supported by contained Factories
+        ///
+        /// @return List of Types supported by the Manager
+        ///
+        pub fun getSupportedTypes(): [Type] {
+            return self.factories.keys
+        }
+
+        /// Retrieves a Factory from the Manager, returning it or nil if it doesn't exist
+        ///
+        /// @param t: Type the Factory is indexed on
+        ///
+        pub fun getFactory(_ t: Type): {CapabilityFactory.Factory}? {
+            return self.factories[t]
+        }
+
+        /// Adds a Factory to the Manager, conditioned on the Factory not already existing
+        ///
+        /// @param t: Type of Capability the Factory retrieves
+        /// @param f: Factory to add
+        ///
+        pub fun addFactory(_ t: Type, _ f: {CapabilityFactory.Factory}) {
+            pre {
+                !self.factories.containsKey(t): "Factory of given type already exists"
+            }
+            self.factories[t] = f
+        }
+
+        /// Updates a Factory in the Manager, adding if it didn't already exist
+        ///
+        /// @param t: Type of Capability the Factory retrieves
+        /// @param f: Factory to replace existing Factory
+        ///
+        pub fun updateFactory(_ t: Type, _ f: {CapabilityFactory.Factory}) {
+            self.factories[t] = f
+        }
+
+        /// Removes a Factory from the Manager, returning it or nil if it didn't exist
+        ///
+        /// @param t: Type the Factory is indexed on
+        ///
+        pub fun removeFactory(_ t: Type): {CapabilityFactory.Factory}? {
+            return self.factories.remove(key: t)
+        }
+
+        init () {
+            self.factories = {}
+        }
+    }
+
+    /// Creates a Manager resource
+    ///
+    /// @return Manager resource
+    pub fun createFactoryManager(): @Manager {
+        return <- create Manager()
+    }
+
+    init() {
+        let identifier = "CapabilityFactory_".concat(self.account.address.toString())
+        self.StoragePath = StoragePath(identifier: identifier)!
+        self.PrivatePath = PrivatePath(identifier: identifier)!
+        self.PublicPath = PublicPath(identifier: identifier)!
+    }
+}

package/contracts/hybrid-custody/CapabilityFilter.cdc

@@ -0,0 +1,199 @@
+/// CapabilityFilter defines `Filter`, an interface to sit on top of a ChildAccount's capabilities. Requested
+/// capabilities will only return if the filter's `allowed` method returns true.
+///
+/// Along with the `Filter` interface are three implementations:
+/// - `DenylistFilter`  - A filter which contains a mapping of denied Types
+/// - `AllowlistFilter` - A filter which contains a mapping of allowed Types
+/// - `AllowAllFilter`  - A passthrough, all requested capabilities are allowed
+/// 
+pub contract CapabilityFilter {
+    
+    /* --- Canonical Paths --- */
+    //
+    pub let StoragePath: StoragePath
+    pub let PublicPath: PublicPath
+    pub let PrivatePath: PrivatePath
+
+    /* --- Events --- */
+    //
+    pub event FilterUpdated(id: UInt64, filterType: Type, type: Type, active: Bool)
+
+    /// `Filter` is a simple interface with methods to determine if a Capability is allowed and retrieve details about
+    /// the Filter itself
+    ///
+    pub resource interface Filter {
+        pub fun allowed(cap: Capability): Bool
+        pub fun getDetails(): AnyStruct
+    }
+
+    /// `DenylistFilter` is a `Filter` which contains a mapping of denied Types
+    ///
+    pub resource DenylistFilter: Filter {
+
+        /// Represents the underlying types which should not ever be returned by a RestrictedChildAccount. The filter
+        /// will borrow a requested capability, and make sure that the type it gets back is not in the list of denied
+        /// types
+        access(self) let deniedTypes: {Type: Bool}
+
+        /// Adds a type to the mapping of denied types with a value of true
+        /// 
+        /// @param type: The type to add to the denied types mapping
+        ///
+        pub fun addType(_ type: Type) {
+            self.deniedTypes.insert(key: type, true)
+            emit FilterUpdated(id: self.uuid, filterType: self.getType(), type: type, active: true)
+        }
+
+        /// Removes a type from the mapping of denied types
+        ///
+        /// @param type: The type to remove from the denied types mapping
+        ///
+        pub fun removeType(_ type: Type) {
+            if let removed = self.deniedTypes.remove(key: type) {
+                emit FilterUpdated(id: self.uuid, filterType: self.getType(), type: type, active: false)
+            }
+        }
+
+        /// Determines if a requested capability is allowed by this `Filter`
+        ///
+        /// @param cap: The capability to check
+        /// @return: true if the capability is allowed, false otherwise
+        ///
+        pub fun allowed(cap: Capability): Bool {
+            if let item = cap.borrow<&AnyResource>() {
+                return !self.deniedTypes.containsKey(item.getType())
+            }
+
+            return false
+        }
+
+        /// Returns details about this filter
+        ///
+        /// @return A struct containing details about this filter including this Filter's Type indexed on the `type`
+        ///         key as well as types denied indexed on the `deniedTypes` key
+        ///
+        pub fun getDetails(): AnyStruct {
+            return {
+                "type": self.getType(),
+                "deniedTypes": self.deniedTypes.keys
+            }
+        }
+
+        init() {
+            self.deniedTypes = {}
+        }
+    }
+
+    /// `AllowlistFilter` is a `Filter` which contains a mapping of allowed Types
+    ///
+    pub resource AllowlistFilter: Filter {
+        // allowedTypes
+        // Represents the set of underlying types which are allowed to be 
+        // returned by a RestrictedChildAccount. The filter will borrow
+        // a requested capability, and make sure that the type it gets back is
+        // in the list of allowed types
+        access(self) let allowedTypes: {Type: Bool}
+
+        /// Adds a type to the mapping of allowed types with a value of true
+        /// 
+        /// @param type: The type to add to the allowed types mapping
+        ///
+        pub fun addType(_ type: Type) {
+            self.allowedTypes.insert(key: type, true)
+            emit FilterUpdated(id: self.uuid, filterType: self.getType(), type: type, active: true)
+        }
+
+        /// Removes a type from the mapping of allowed types
+        ///
+        /// @param type: The type to remove from the denied types mapping
+        ///
+        pub fun removeType(_ type: Type) {
+            if let removed = self.allowedTypes.remove(key: type) {
+                emit FilterUpdated(id: self.uuid, filterType: self.getType(), type: type, active: false)
+            }
+        }
+        
+        /// Determines if a requested capability is allowed by this `Filter`
+        ///
+        /// @param cap: The capability to check
+        /// @return: true if the capability is allowed, false otherwise
+        ///
+        pub fun allowed(cap: Capability): Bool {
+            if let item = cap.borrow<&AnyResource>() {
+                return self.allowedTypes.containsKey(item.getType())
+            }
+
+            return false
+        }
+
+        /// Returns details about this filter
+        ///
+        /// @return A struct containing details about this filter including this Filter's Type indexed on the `type`
+        ///         key as well as types allowed indexed on the `allowedTypes` key
+        ///
+        pub fun getDetails(): AnyStruct {
+            return {
+                "type": self.getType(),
+                "allowedTypes": self.allowedTypes.keys
+            }
+        }
+
+        init() {
+            self.allowedTypes = {}
+        }
+    }
+
+    /// AllowAllFilter is a passthrough, all requested capabilities are allowed
+    ///
+    pub resource AllowAllFilter: Filter {
+        /// Determines if a requested capability is allowed by this `Filter`
+        ///
+        /// @param cap: The capability to check
+        /// @return: true since this filter is a passthrough
+        ///
+        pub fun allowed(cap: Capability): Bool {
+            return true
+        }
+        
+        /// Returns details about this filter
+        ///
+        /// @return A struct containing details about this filter including this Filter's Type indexed on the `type`
+        ///         key
+        ///
+        pub fun getDetails(): AnyStruct {
+            return {
+                "type": self.getType()
+            }
+        }
+    }
+
+    /// Creates a new `Filter` of the given type
+    ///
+    /// @param t: The type of `Filter` to create
+    /// @return: A new instance of the given `Filter` type
+    ///
+    pub fun create(_ t: Type): @AnyResource{Filter} {
+        post {
+            result.getType() == t
+        }
+
+        switch t {
+            case Type<@AllowAllFilter>():
+                return <- create AllowAllFilter()
+            case Type<@AllowlistFilter>():
+                return <- create AllowlistFilter()
+            case Type<@DenylistFilter>():
+                return <- create DenylistFilter()
+        }
+
+        panic("unsupported type requested: ".concat(t.identifier))
+    }
+
+    init() {
+        let identifier = "CapabilityFilter_".concat(self.account.address.toString())
+        
+        self.StoragePath = StoragePath(identifier: identifier)!
+        self.PublicPath = PublicPath(identifier: identifier)!
+        self.PrivatePath = PrivatePath(identifier: identifier)!
+    }
+}