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

package/contracts/evm/IBridgePermissions.cdc

@@ -0,0 +1,19 @@
+/// This contract defines a simple interface which can be implemented by any resource to prevent it from being
+/// onboarded to the Flow-EVM bridge
+///
+/// NOTE: This is suggested only for cases where your asset (NFT/FT) incorporates non-standard logic that would
+///      break your project if not handles properly
+///      e.g. assets are reclaimed after a certain period of time, NFTs share IDs, etc.
+///
+access(all)
+contract interface IBridgePermissions {
+    /// Contract-level method enabling implementing contracts to identify whether they allow bridging for their
+    /// project's assets. Implementers may consider adding a hook which would later enable an update to this value
+    /// should either the project be updated or the bridge be updated to handle the asset's non-standard logic which 
+    /// would otherwise prevent them from supporting VM bridging at the outset.
+    ///
+    access(all)
+    view fun allowsBridging(): Bool {
+        return false
+    }
+}

package/contracts/evm/ICrossVM.cdc

@@ -0,0 +1,12 @@
+import "EVM"
+
+/// Contract interface denoting a cross-VM implementation, exposing methods to query EVM-associated addresses
+///
+access(all)
+contract interface ICrossVM {
+
+    /// Retrieves the corresponding EVM contract address, assuming a 1:1 relationship between VM implementations
+    ///
+    access(all)
+    view fun getEVMContractAddress(): EVM.EVMAddress
+}

package/contracts/evm/ICrossVMAsset.cdc

@@ -0,0 +1,19 @@
+import "EVM"
+
+import "ICrossVM"
+
+/// A simple contract interface for a Cadence contract that represents an asset bridged from Flow EVM such as an ERC20
+/// or ERC721 token.
+///
+access(all) contract interface ICrossVMAsset : ICrossVM {
+    /// Returns the name of the asset
+    access(all) view fun getName(): String
+    /// Returns the symbol of the asset
+    access(all) view fun getSymbol(): String
+
+    access(all) resource interface AssetInfo {
+        access(all) view fun getName(): String
+        access(all) view fun getSymbol(): String
+        access(all) view fun getEVMContractAddress(): EVM.EVMAddress        
+    }
+}

package/contracts/evm/Serialize.cdc

@@ -0,0 +1,141 @@
+import "ViewResolver"
+import "MetadataViews"
+import "NonFungibleToken"
+
+/// This contract is a utility for serializing primitive types, arrays, and common metadata mapping formats to JSON
+/// compatible strings. Also included are interfaces enabling custom serialization for structs and resources.
+///
+/// Special thanks to @austinkline for the idea and initial implementation.
+///
+access(all)
+contract Serialize {
+
+    /// Method that returns a serialized representation of the given value or nil if the value is not serializable
+    ///
+    access(all)
+    fun tryToJSONString(_ value: AnyStruct): String? {
+        // Recursively serialize array & return
+        if value.getType().isSubtype(of: Type<[AnyStruct]>()) {
+            return self.arrayToJSONString(value as! [AnyStruct])
+        }
+        // Recursively serialize map & return
+        if value.getType().isSubtype(of: Type<{String: AnyStruct}>()) {
+            return self.dictToJSONString(dict: value as! {String: AnyStruct}, excludedNames: nil)
+        }
+        // Handle primitive types & optionals
+        switch value.getType() {
+            case Type<Never?>():
+                return "\"nil\""
+            case Type<String>():
+                return "\"".concat(value as! String).concat("\"")
+            case Type<String?>():
+                return "\"".concat(value as? String ?? "nil").concat("\"")
+            case Type<Character>():
+                return "\"".concat((value as! Character).toString()).concat("\"")
+            case Type<Bool>():
+                return "\"".concat(value as! Bool ? "true" : "false").concat("\"")
+            case Type<Address>():
+                return "\"".concat((value as! Address).toString()).concat("\"")
+            case Type<Address?>():
+                return "\"".concat((value as? Address)?.toString() ?? "nil").concat("\"")
+            case Type<Int8>():
+                return "\"".concat((value as! Int8).toString()).concat("\"")
+            case Type<Int16>():
+                return "\"".concat((value as! Int16).toString()).concat("\"")
+            case Type<Int32>():
+                return "\"".concat((value as! Int32).toString()).concat("\"")
+            case Type<Int64>():
+                return "\"".concat((value as! Int64).toString()).concat("\"")
+            case Type<Int128>():
+                return "\"".concat((value as! Int128).toString()).concat("\"")
+            case Type<Int256>():
+                return "\"".concat((value as! Int256).toString()).concat("\"")
+            case Type<Int>():
+                return "\"".concat((value as! Int).toString()).concat("\"")
+            case Type<UInt8>():
+                return "\"".concat((value as! UInt8).toString()).concat("\"")
+            case Type<UInt16>():
+                return "\"".concat((value as! UInt16).toString()).concat("\"")
+            case Type<UInt32>():
+                return "\"".concat((value as! UInt32).toString()).concat("\"")
+            case Type<UInt64>():
+                return "\"".concat((value as! UInt64).toString()).concat("\"")
+            case Type<UInt128>():
+                return "\"".concat((value as! UInt128).toString()).concat("\"")
+            case Type<UInt256>():
+                return "\"".concat((value as! UInt256).toString()).concat("\"")
+            case Type<UInt>():
+                return "\"".concat((value as! UInt).toString()).concat("\"")
+            case Type<Word8>():
+                return "\"".concat((value as! Word8).toString()).concat("\"")
+            case Type<Word16>():
+                return "\"".concat((value as! Word16).toString()).concat("\"")
+            case Type<Word32>():
+                return "\"".concat((value as! Word32).toString()).concat("\"")
+            case Type<Word64>():
+                return "\"".concat((value as! Word64).toString()).concat("\"")
+            case Type<Word128>():
+                return "\"".concat((value as! Word128).toString()).concat("\"")
+            case Type<Word256>():
+                return "\"".concat((value as! Word256).toString()).concat("\"")
+            case Type<UFix64>():
+                return "\"".concat((value as! UFix64).toString()).concat("\"")
+            default:
+                return nil
+        }
+    }
+
+    /// Returns a serialized representation of the given array or nil if the value is not serializable
+    ///
+    access(all)
+    fun arrayToJSONString(_ arr: [AnyStruct]): String? {
+        var serializedArr = "["
+        let arrLength = arr.length
+        for i, element in arr {
+            let serializedElement = self.tryToJSONString(element)
+            if serializedElement == nil {
+                if i == arrLength - 1 && serializedArr.length > 1 && serializedArr[serializedArr.length - 2] == "," {
+                    // Remove trailing comma as this element could not be serialized
+                    serializedArr = serializedArr.slice(from: 0, upTo: serializedArr.length - 2)
+                }
+                continue
+            }
+            serializedArr = serializedArr.concat(serializedElement!)
+            // Add a comma if there are more elements to serialize
+            if i < arr.length - 1 {
+                serializedArr = serializedArr.concat(", ")
+            }
+        }
+        return serializedArr.concat("]")
+    }
+
+    /// Returns a serialized representation of the given String-indexed mapping or nil if the value is not serializable.
+    /// The interface here is largely the same as as the `MetadataViews.dictToTraits` method, though here
+    /// a JSON-compatible String is returned instead of a `Traits` array.
+    ///
+    access(all)
+    fun dictToJSONString(dict: {String: AnyStruct}, excludedNames: [String]?): String? {
+        if excludedNames != nil {
+            for k in excludedNames! {
+                dict.remove(key: k)
+            }
+        }
+        var serializedDict = "{"
+        let dictLength = dict.length
+        for i, key in dict.keys {
+            let serializedValue = self.tryToJSONString(dict[key]!)
+            if serializedValue == nil {
+                if i == dictLength - 1  && serializedDict.length > 1 && serializedDict[serializedDict.length - 2] == "," {
+                    // Remove trailing comma as this element could not be serialized
+                    serializedDict = serializedDict.slice(from: 0, upTo: serializedDict.length - 2)
+                }
+                continue
+            }
+            serializedDict = serializedDict.concat(self.tryToJSONString(key)!).concat(": ").concat(serializedValue!)
+            if i < dict.length - 1 {
+                serializedDict = serializedDict.concat(", ")
+            }
+        }
+        return serializedDict.concat("}")
+    }
+}

package/contracts/evm/SerializeMetadata.cdc

@@ -0,0 +1,221 @@
+import "ViewResolver"
+import "MetadataViews"
+import "NonFungibleToken"
+import "FungibleTokenMetadataViews"
+
+import "Serialize"
+
+/// This contract defines methods for serializing NFT metadata as a JSON compatible string, according to the common
+/// OpenSea metadata format. NFTs and metadata views can be serialized by reference via contract methods.
+///
+access(all) contract SerializeMetadata {
+
+    /// Serializes the metadata (as a JSON compatible String) for a given NFT according to formats expected by EVM
+    /// platforms like OpenSea. If you are a project owner seeking to expose custom traits on bridged NFTs and your
+    /// Trait.value is not natively serializable, you can implement a custom serialization method with the
+    /// `{SerializableStruct}` interface's `serialize` method.
+    ///
+    /// Reference: https://docs.opensea.io/docs/metadata-standards
+    ///
+    ///
+    /// @returns: A JSON compatible data URL string containing the serialized display & collection display views as:
+    ///     `data:application/json;utf8,{
+    ///         \"name\": \"<display.name>\",
+    ///         \"description\": \"<display.description>\",
+    ///         \"image\": \"<display.thumbnail.uri()>\",
+    ///         \"external_url\": \"<nftCollectionDisplay.externalURL.url>\",
+    ///         \"attributes\": [{\"trait_type\": \"<trait.name>\", \"value\": \"<trait.value>\"}, {...}]
+    ///     }`
+    access(all)
+    fun serializeNFTMetadataAsURI(_ nft: &{NonFungibleToken.NFT}): String {
+        // Serialize the display values from the NFT's Display & NFTCollectionDisplay views
+        let nftDisplay = nft.resolveView(Type<MetadataViews.Display>()) as! MetadataViews.Display?
+        let collectionDisplay = nft.resolveView(Type<MetadataViews.NFTCollectionDisplay>()) as! MetadataViews.NFTCollectionDisplay?
+        let display = self.serializeFromDisplays(nftDisplay: nftDisplay, collectionDisplay: collectionDisplay)
+
+        // Get the Traits view from the NFT, returning early if no traits are found
+        let traits = nft.resolveView(Type<MetadataViews.Traits>()) as! MetadataViews.Traits?
+        let attributes = self.serializeNFTTraitsAsAttributes(traits ?? MetadataViews.Traits([]))
+
+        // Return an empty string if nothing is serializable
+        if display == nil && attributes == nil {
+            return ""
+        }
+        // Init the data format prefix & concatenate the serialized display & attributes
+        var serializedMetadata = "data:application/json;utf8,{"
+        if display != nil {
+            serializedMetadata = serializedMetadata.concat(display!)
+        }
+        if display != nil && attributes != nil {
+            serializedMetadata = serializedMetadata.concat(", ")
+        }
+        if attributes != nil {
+            serializedMetadata = serializedMetadata.concat(attributes)
+        }
+        return serializedMetadata.concat("}")
+    }
+
+    /// Serializes the display & collection display views of a given NFT as a JSON compatible string. If nftDisplay is 
+    /// present, the value is returned as token-level metadata. If nftDisplay is nil and collectionDisplay is present,
+    /// the value is returned as contract-level metadata. If both values are nil, nil is returned.
+    ///
+    /// @param nftDisplay: The NFT's Display view from which values `name`, `description`, and `thumbnail` are serialized
+    /// @param collectionDisplay: The NFT's NFTCollectionDisplay view from which the `externalURL` is serialized
+    ///
+    /// @returns: A JSON compatible string containing the serialized display & collection display views as either:
+    ///         \"name\": \"<nftDisplay.name>\", \"description\": \"<nftDisplay.description>\", \"image\": \"<nftDisplay.thumbnail.uri()>\", \"external_url\": \"<collectionDisplay.externalURL.url>\",
+    ///         \"name\": \"<collectionDisplay.name>\", \"description\": \"<collectionDisplay.description>\", \"image\": \"<collectionDisplay.squareImage.file.uri()>\", \"external_link\": \"<collectionDisplay.externalURL.url>\",
+    ///
+    access(all)
+    fun serializeFromDisplays(nftDisplay: MetadataViews.Display?, collectionDisplay: MetadataViews.NFTCollectionDisplay?): String? {
+        // Return early if both values are nil
+        if nftDisplay == nil && collectionDisplay == nil {
+            return nil
+        }
+
+        // Initialize JSON fields
+        let name = "\"name\": "
+        let description = "\"description\": "
+        let image = "\"image\": "
+        let externalURL = "\"external_url\": "
+        let externalLink = "\"external_link\": "
+        var serializedResult = ""
+
+        // Append results from the token-level Display view to the serialized JSON compatible string
+        if nftDisplay != nil {
+            serializedResult = serializedResult
+                .concat(name).concat(Serialize.tryToJSONString(nftDisplay!.name)!).concat(", ")
+                .concat(description).concat(Serialize.tryToJSONString(nftDisplay!.description)!).concat(", ")
+                .concat(image).concat(Serialize.tryToJSONString(nftDisplay!.thumbnail.uri())!)
+            // Append the `externa_url` value from NFTCollectionDisplay view if present
+            if collectionDisplay != nil {
+                return serializedResult.concat(", ")
+                    .concat(externalURL).concat(Serialize.tryToJSONString(collectionDisplay!.externalURL.url)!)
+            }
+        }
+
+        if collectionDisplay == nil {
+            return serializedResult
+        }
+
+        // Without token-level view, serialize as contract-level metadata
+        return serializedResult
+            .concat(name).concat(Serialize.tryToJSONString(collectionDisplay!.name)!).concat(", ")
+            .concat(description).concat(Serialize.tryToJSONString(collectionDisplay!.description)!).concat(", ")
+            .concat(image).concat(Serialize.tryToJSONString(collectionDisplay!.squareImage.file.uri())!).concat(", ")
+            .concat(externalLink).concat(Serialize.tryToJSONString(collectionDisplay!.externalURL.url)!)
+    }
+
+    /// Serializes given Traits view as a JSON compatible string. If a given Trait is not serializable, it is skipped
+    /// and not included in the serialized result.
+    ///
+    /// @param traits: The Traits view to be serialized
+    ///
+    /// @returns: A JSON compatible string containing the serialized traits as:
+    ///     `\"attributes\": [{\"trait_type\": \"<trait.name>\", \"value\": \"<trait.value>\"}, {...}]`
+    ///
+    access(all)
+    fun serializeNFTTraitsAsAttributes(_ traits: MetadataViews.Traits): String {
+        // Serialize each trait as an attribute, building the serialized JSON compatible string
+        var serializedResult = "\"attributes\": ["
+        let traitsLength = traits.traits.length
+        for i, trait in traits.traits {
+            let value = Serialize.tryToJSONString(trait.value)
+            if value == nil {
+                // Remove trailing comma if last trait is not serializable
+                if i == traitsLength - 1 && serializedResult[serializedResult.length - 1] == "," {
+                    serializedResult = serializedResult.slice(from: 0, upTo: serializedResult.length - 1)    
+                }
+                continue
+            }
+            serializedResult = serializedResult.concat("{")
+                .concat("\"trait_type\": ").concat(Serialize.tryToJSONString(trait.name)!)
+                .concat(", \"value\": ").concat(value!)
+                .concat("}")
+            if i < traits!.traits.length - 1 {
+                serializedResult = serializedResult.concat(",")
+            }
+        }
+        return serializedResult.concat("]")
+    }
+
+    /// Serializes the FTDisplay view of a given fungible token as a JSON compatible data URL. The value is returned as 
+    /// contract-level metadata.
+    ///
+    /// @param ftDisplay: The tokens's FTDisplay view from which values `name`, `symbol`, `description`, and 
+    ///     `externaURL` are serialized
+    ///
+    /// @returns: A JSON compatible data URL string containing the serialized view as:
+    ///     `data:application/json;utf8,{
+    ///         \"name\": \"<ftDisplay.name>\",
+    ///         \"symbol\": \"<ftDisplay.symbol>\",
+    ///         \"description\": \"<ftDisplay.description>\",
+    ///         \"external_link\": \"<ftDisplay.externalURL.url>\",
+    ///     }`
+    access(all)
+    fun serializeFTDisplay(_ ftDisplay: FungibleTokenMetadataViews.FTDisplay): String {
+        let name = "\"name\": "
+        let symbol = "\"symbol\": "
+        let description = "\"description\": "
+        let externalLink = "\"external_link\": "
+
+        return "data:application/json;utf8,{"
+            .concat(name).concat(Serialize.tryToJSONString(ftDisplay.name)!).concat(", ")
+            .concat(symbol).concat(Serialize.tryToJSONString(ftDisplay.symbol)!).concat(", ")
+            .concat(description).concat(Serialize.tryToJSONString(ftDisplay.description)!).concat(", ")
+            .concat(externalLink).concat(Serialize.tryToJSONString(ftDisplay.externalURL.url)!)
+            .concat("}")
+    }
+
+    /// Derives a symbol for use as an ERC20 or ERC721 symbol from a given string, presumably a Cadence contract name.
+    /// Derivation is a process of slicing the first 4 characters of the string and converting them to uppercase.
+    ///
+    /// @param fromString: The string from which to derive a symbol
+    ///
+    /// @returns: A derived symbol for use as an ERC20 or ERC721 symbol based on the provided string, presumably a
+    ///    Cadence contract name
+    ///
+    access(all) view fun deriveSymbol(fromString: String): String {
+        let defaultLen = 4
+        let len = fromString.length < defaultLen ? fromString.length : defaultLen
+        return self.toUpperAlphaNumerical(fromString, upTo: len)
+    }
+
+    /// Returns the uppercase alphanumeric version of a given string. If upTo is nil or exceeds the length of the string,
+    /// the entire string is converted to uppercase.
+    ///
+    /// @param str: The string to convert to uppercase
+    /// @param upTo: The maximum number of characters to convert to uppercase
+    ///
+    /// @returns: The uppercase version of the given string
+    ///
+    access(all) view fun toUpperAlphaNumerical(_ str: String, upTo: Int?): String {
+        let len = upTo ?? str.length
+        var upper: String = ""
+        for char in str {
+            if upper.length == len {
+                break
+            }
+            let bytes = char.utf8
+            if bytes.length != 1 {
+                continue
+            }
+            let byte = bytes[0]
+            if byte >= 97 && byte <= 122 {
+                // Convert lower case to upper case
+                let upperChar = String.fromUTF8([byte - UInt8(32)])!
+                upper = upper.concat(upperChar)
+            } else if byte >= 65 && byte <= 90 {
+                // Keep upper case
+                upper = upper.concat(char.toString())
+            } else if byte >= 48 && byte <= 57 {
+                // Keep numbers
+                upper = upper.concat(String.fromCharacters([char]))
+            } else {
+                // Skip non-alphanumeric characters
+                continue
+            }
+        }
+        return upper
+    }
+}

package/contracts/example/ExampleNFT.cdc

@@ -164,7 +164,7 @@ access(all) contract ExampleNFT: ViewResolver {
 
         // dictionary of NFT conforming tokens
         // NFT is a resource type with an `UInt64` ID field
-        access(self) var ownedNFTs: @{UInt64: {NonFungibleToken.NFT}}
+        access(all) var ownedNFTs: @{UInt64: {NonFungibleToken.NFT}}
 
         init () {
             self.ownedNFTs <- {}
@@ -206,7 +206,7 @@ access(all) contract ExampleNFT: ViewResolver {
         }
 
         // withdraw removes an NFT from the collection and moves it to the caller
-        access(NonFungibleToken.Withdraw | NonFungibleToken.Owner) fun withdraw(withdrawID: UInt64): @{NonFungibleToken.NFT} {
+        access(NonFungibleToken.Withdraw) fun withdraw(withdrawID: UInt64): @{NonFungibleToken.NFT} {
             let token <- self.ownedNFTs.remove(key: withdrawID) ?? panic("missing NFT")
 
             emit Withdraw(id: token.id, from: self.owner?.address)