@artblocks/contracts 1.2.0 → 1.3.0

package/contracts/libs/v0.8.x/ImmutableStringArray.sol

@@ -0,0 +1,289 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+import {SSTORE2} from "./SSTORE2.sol"; // Import SSTORE2 library
+
+/**
+ * @title ImmutableStringArray
+ * @author Art Blocks Inc.
+ * @notice This library is optimized to store immutable arrays of strings much more efficiently than using native Solidity storage arrays.
+ * It uses a single SSTORE2 contract to store the length + packed offsets + packed string data.
+ * Allows overwriting the pointer to point to a new immutable array.
+ */
+library ImmutableStringArray {
+    /**
+     * @notice Struct to store the SSTORE2 pointer to the packed string array.
+     * @dev dataPointer is the SSTORE2 pointer to the packed string array.
+     */
+    struct StringArray {
+        address dataPointer; // SSTORE2 pointer storing length + packed offsets + packed string data
+    }
+
+    /**
+     * @notice Stores a packed immutable string array using a single SSTORE2 contract.
+     * Allows overwriting the pointer to point to a new immutable array.
+     * @param storageArray The storage reference to store the packed array.
+     * @param strings The array of strings to pack.
+     */
+    function store(
+        StringArray storage storageArray,
+        string[] memory strings
+    ) internal {
+        uint256 arrayLength = strings.length;
+        uint64[] memory offsets = new uint64[](arrayLength);
+
+        // compute total bytes length and offsets (ensuring no overflow)
+        uint256 totalStringBytesLength;
+        for (uint256 i = 0; i < arrayLength; i++) {
+            offsets[i] = uint64(totalStringBytesLength);
+            totalStringBytesLength += bytes(strings[i]).length;
+        }
+        // realistically will not overflow uint64, but check for security guarantees
+        // @dev no coverage on else (difficulty of triggering)
+        require(
+            totalStringBytesLength <= type(uint64).max,
+            "Offset exceeds uint64 limit"
+        );
+
+        // prepare the combined storage structure (length + packed offsets + packed strings)
+        // @dev 8 bytes for length, 8 bytes per offset, totalStringBytesLength bytes for strings
+        // over-allocate 32 bytes for memory safety
+        // note: shorten length by 32 bytes at end of function before returning
+        uint256 packedDataLength = 8 +
+            (arrayLength * 8) +
+            totalStringBytesLength;
+        bytes memory packedData = new bytes(packedDataLength + 0x20);
+        uint256 ptr;
+
+        // store the length of the strings array in the first 8 bytes of the packedData
+        assembly ("memory-safe") {
+            ptr := add(packedData, 0x20) // pointer to first byte of packedData
+            mstore(ptr, shl(192, arrayLength)) // left-align only 8 bytes in the 32-byte slot
+            ptr := add(ptr, 8) // move pointer forward by 8 bytes
+        }
+
+        // store offsets in packed `uint64` format
+        for (uint256 i = 0; i < arrayLength; i++) {
+            uint256 offset = offsets[i];
+            assembly ("memory-safe") {
+                mstore(ptr, shl(192, offset))
+                // move pointer ahead 8 bytes for uint64
+                ptr := add(ptr, 8)
+            }
+        }
+
+        // pack the strings efficiently, using assembly to copy 32 bytes at a time
+        for (uint i = 0; i < arrayLength; i++) {
+            bytes memory currentString = bytes(strings[i]);
+            uint currentLength = currentString.length;
+            uint currentPtr;
+
+            assembly ("memory-safe") {
+                currentPtr := add(currentString, 0x20) // start of current string's data
+            }
+
+            // copy the full 32-byte chunks
+            uint chunks = currentLength / 32;
+            uint remainder = currentLength % 32;
+            // store the full 32 byte chunks
+            for (uint j = 0; j < chunks; j++) {
+                assembly ("memory-safe") {
+                    let chunk := mload(currentPtr) // load 32 bytes of the current string
+                    mstore(ptr, chunk) // store the 32 bytes into the result
+                    ptr := add(ptr, 0x20) // move the result pointer forward by 32 bytes
+                    currentPtr := add(currentPtr, 0x20) // move the current string pointer forward by 32 bytes
+                }
+            }
+            // store any partial chunks
+            if (remainder > 0) {
+                bytes32 chunk;
+                assembly ("memory-safe") {
+                    chunk := mload(currentPtr) // load full 32-byte word
+                    // safe to write past end of final array - 32 bytes of buffer at end of array
+                    mstore(ptr, chunk) // store the final chunk's remaining bytes
+                    ptr := add(ptr, remainder) // move the result pointer forward by the remainder length for next iteration
+                }
+            }
+        }
+
+        // remove the buffer from the packedData bytes array length
+        assembly ("memory-safe") {
+            ptr := packedData
+            mstore(ptr, packedDataLength)
+        }
+
+        // Store all packed data in a SSTORE2 contract, store result in storage
+        storageArray.dataPointer = SSTORE2.write(packedData);
+    }
+
+    /**
+     * @notice Retrieves the total number of stored strings from SSTORE2.
+     * @param storageArray The storage reference containing packed strings.
+     * @return count The count of stored strings.
+     */
+    function length(
+        StringArray storage storageArray
+    ) internal view returns (uint256 count) {
+        // @dev this could be more efficient by only reading the first 8 bytes of the SSTORE2 contract
+        // but prefer to keep simple
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+
+        assembly ("memory-safe") {
+            count := shr(192, mload(add(allData, 32)))
+        }
+    }
+
+    /**
+     * @notice Retrieves a single string from storage by index.
+     * @param storageArray The storage reference containing packed strings.
+     * @param index The index of the string to retrieve.
+     * @return result The retrieved string.
+     */
+    function get(
+        StringArray storage storageArray,
+        uint256 index
+    ) internal view returns (string memory result) {
+        // edge case - unassigned dataPointer
+        if (storageArray.dataPointer == address(0)) {
+            revert("Index out of bounds");
+        }
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+        uint256 offsetsStart;
+        uint64 start;
+        uint64 end;
+        // load the total length of the strings array from the first 8 bytes of the SSTORE2 contract
+        uint256 arrayLength;
+        assembly ("memory-safe") {
+            arrayLength := shr(192, mload(add(allData, 32)))
+        }
+
+        require(index < arrayLength, "Index out of bounds");
+        if (index + 1 == arrayLength) {
+            uint256 allDataLength = allData.length;
+            assembly ("memory-safe") {
+                offsetsStart := add(allData, 40) // skipping first 8 bytes (length)
+                start := shr(192, mload(add(offsetsStart, mul(index, 8)))) // load offsets[index] as uint64
+                end := sub(
+                    allDataLength,
+                    add(8, mul(arrayLength, 8)) // subtract 8 bytes for overall array length, and 8*length for the offsets section
+                )
+            }
+        } else {
+            assembly ("memory-safe") {
+                offsetsStart := add(allData, 40) // skipping first 8 bytes (length)
+                start := shr(192, mload(add(offsetsStart, mul(index, 8)))) // load offsets[index] as uint64
+                end := shr(192, mload(add(offsetsStart, mul(add(index, 1), 8)))) // load offsets[index + 1]
+            }
+        }
+
+        uint256 strLength = end - start;
+        // over-allocate 32 bytes for memory safety
+        bytes memory strBytes = new bytes(strLength + 32);
+        uint256 ptr;
+        assembly ("memory-safe") {
+            ptr := add(strBytes, 0x20) // pointer to first byte of strBytes
+        }
+
+        // efficiently copy 32 bytes at a time from allData to strBytes
+        for (uint256 i = 0; i < strLength; i += 32) {
+            // offset = 32 bytes for length + 8 bytes for overall array length + 8 bytes per offset * length of array + start of string + i
+            uint256 offset = 32 + 8 + (arrayLength * 8) + start + i;
+            assembly ("memory-safe") {
+                let chunk := mload(add(allData, offset)) // load 32 bytes of the current string
+                mstore(ptr, chunk) // store the 32 bytes into the result (buffer keeps this memory safe)
+                ptr := add(ptr, 0x20) // move the result pointer forward by 32 bytes
+            }
+        }
+
+        // remove the buffer length from the strBytes bytes array length
+        assembly ("memory-safe") {
+            ptr := strBytes
+            mstore(ptr, strLength)
+        }
+        result = string(strBytes);
+    }
+
+    /**
+     * @notice Retrieves all stored strings in a single batch call.
+     * @param storageArray The storage reference containing packed strings.
+     * @return results An array of all stored strings.
+     */
+    function getAll(
+        StringArray storage storageArray
+    ) internal view returns (string[] memory results) {
+        // edge case - unassigned dataPointer
+        if (storageArray.dataPointer == address(0)) {
+            return new string[](0);
+        }
+        // load the packed data from the SSTORE2 contract
+        bytes memory allData = SSTORE2.read(storageArray.dataPointer);
+        // load the total length of the strings array from the first 8 bytes of the SSTORE2 contract
+        uint256 arrayLength;
+        assembly ("memory-safe") {
+            arrayLength := shr(192, mload(add(allData, 32)))
+        }
+
+        // for each string in the array, populate results
+        results = new string[](arrayLength);
+
+        for (uint256 index = 0; index < arrayLength; index++) {
+            // @dev start and end are calculated for each index for code simplicity/code re-use from get() function
+            uint256 offsetsStart;
+            uint64 start;
+            uint64 end;
+
+            if (index + 1 == arrayLength) {
+                uint256 allDataLength = allData.length;
+                assembly ("memory-safe") {
+                    offsetsStart := add(allData, 40) // Skipping first 8 bytes (length)
+                    start := shr(192, mload(add(offsetsStart, mul(index, 8)))) // Load offsets[index] as uint64
+                    end := sub(
+                        allDataLength,
+                        add(8, mul(arrayLength, 8)) // subtract 8 bytes for overall array length, and 8*length for the offsets section
+                    )
+                }
+            } else {
+                assembly ("memory-safe") {
+                    offsetsStart := add(allData, 40) // Skipping first 8 bytes (length)
+                    start := shr(192, mload(add(offsetsStart, mul(index, 8)))) // Load offsets[index] as uint64
+                    end := shr(
+                        192,
+                        mload(add(offsetsStart, mul(add(index, 1), 8)))
+                    ) // Load offsets[index + 1]
+                }
+            }
+
+            uint256 strLength = end - start;
+            // over-allocate 32 bytes for memory safety
+            bytes memory strBytes = new bytes(strLength + 32);
+            uint256 ptr;
+            assembly ("memory-safe") {
+                ptr := add(strBytes, 0x20) // pointer to first byte of strBytes
+            }
+
+            // efficiently copy 32 bytes at a time from allData to strBytes
+            for (uint256 i = 0; i < strLength; i += 32) {
+                // offset = 32 bytes for length + 8 bytes for overall array length + 8 bytes per offset * length of array + start of string + i
+                uint256 offset = 32 + 8 + (arrayLength * 8) + start + i;
+                assembly ("memory-safe") {
+                    let chunk := mload(add(allData, offset)) // Load 32 bytes of the current string
+                    mstore(ptr, chunk) // Store the 32 bytes into the result (buffer keeps this memory safe)
+                    ptr := add(ptr, 0x20) // Move the result pointer forward by 32 bytes
+                }
+            }
+
+            // remove the buffer length from the strBytes bytes array length
+            assembly ("memory-safe") {
+                ptr := strBytes
+                mstore(ptr, strLength)
+            }
+
+            // store the string in the results array
+            results[index] = string(strBytes);
+        }
+
+        // results is returned by reference, so no need for explicit return
+    }
+}

package/contracts/libs/v0.8.x/JsonStatic.sol

@@ -0,0 +1,373 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+import {Base64} from "@openzeppelin-5.0/contracts/utils/Base64.sol";
+import {Strings} from "@openzeppelin-5.0/contracts/utils/Strings.sol";
+
+pragma solidity ^0.8.22;
+
+/**
+ * @title Art Blocks Json Library
+ * @author Art Blocks Inc.
+ * @notice UNAUDITED
+ * A library for helping write static JSON metadata for Art Blocks projects.
+ * The library writes JSON data to a string within solidity, while remaining O(n) in gas and memory complexity,
+ * where n is the number of elements in an array or key:value pairs in an object. The library is O(m^2)
+ * in gas and memory complexity, where m is the depth of nested objects or arrays.
+ * When used in memory, the library only supports arrays and objects of fixed, pre-allocated size,
+ * in order to avoid dynamic memory allocation.
+ * The library supports an optional flag to write input string values as base64 encoded strings, in
+ * order to avoid the need for escaping characters in JSON strings.
+ * Keys are assumed to be valid key names in JSON.
+ * The library supports writing JSON objects, arrays, strings, uints, booleans, and null values.
+ * The library does not support writing floating point numbers.
+ */
+library JsonStatic {
+    using Strings for uint256;
+    using JsonStatic for JsonStatic.Json;
+
+    enum JsonType {
+        OBJECT,
+        ARRAY,
+        ELEMENT_STRING,
+        ELEMENT_UINT,
+        ELEMENT_BOOLEAN,
+        ELEMENT_NULL
+    }
+
+    enum StringEncodingFlag {
+        NONE,
+        BASE64
+    }
+
+    struct Json {
+        JsonType jsonType;
+        string[] objectKeys; // array of keys if type is OBJECT
+        Json[] values; // array of values if type is OBJECT, or array values if type is ARRAY
+        StringEncodingFlag stringEncodingFlag;
+        string elementValueString; // value if type is ELEMENT_STRING
+        uint256 elementValueUintOrBool; // value if type is ELEMENT_UINT, 0/1 if type is ELEMENT_BOOLEAN
+        // implied null if type is ELEMENT_NULL
+    }
+
+    /**
+     * Convenience function to create a new values array.
+     * @param length the length of the values array.
+     * @return the new values array.
+     */
+    function newValuesArray(
+        uint256 length
+    ) internal pure returns (Json[] memory) {
+        return new Json[](length);
+    }
+
+    /**
+     * Convenience function to create a new keys array.
+     * @param length the length of the keys array.
+     * @return the new keys array.
+     */
+    function newKeysArray(
+        uint256 length
+    ) internal pure returns (string[] memory) {
+        return new string[](length);
+    }
+
+    /**
+     * Convenience function to create a new object element.
+     * @param keys the keys of the object element.
+     * @param values the values of the object element.
+     * @return the new object element.
+     */
+    function newObjectElement(
+        string[] memory keys,
+        Json[] memory values
+    ) internal pure returns (Json memory) {
+        return
+            Json({
+                jsonType: JsonType.OBJECT, // type
+                objectKeys: keys, // input
+                values: values, // input
+                stringEncodingFlag: StringEncodingFlag.NONE, // default
+                elementValueString: "", // default
+                elementValueUintOrBool: 0 // default
+            });
+    }
+
+    /**
+     * Convenience function to create a new array element.
+     * @param values the values of the array element.
+     * @return the new array element.
+     */
+    function newArrayElement(
+        Json[] memory values
+    ) internal pure returns (Json memory) {
+        return
+            Json({
+                jsonType: JsonType.ARRAY, // type
+                objectKeys: new string[](0), // default
+                values: values, // input
+                stringEncodingFlag: StringEncodingFlag.NONE, // default
+                elementValueString: "", // default
+                elementValueUintOrBool: 0 // default
+            });
+    }
+
+    /**
+     * Convenience function to create a new string element.
+     * If base64 encoding is set as the encoding flag, the passed value will be encoded on WRITE and
+     * should NOT already be encoded. Passing an already encoded value will result in double encoding.
+     * @param value the string value of the element.
+     * @param stringEncodingFlag the string encoding flag for the element.
+     * @return the new string element.
+     */
+    function newStringElement(
+        string memory value,
+        StringEncodingFlag stringEncodingFlag
+    ) internal pure returns (Json memory) {
+        return
+            Json({
+                jsonType: JsonType.ELEMENT_STRING, // type
+                objectKeys: new string[](0), // default
+                values: new Json[](0), // default
+                stringEncodingFlag: stringEncodingFlag, // input
+                elementValueString: value, // input
+                elementValueUintOrBool: 0 // default
+            });
+    }
+
+    /**
+     * Convenience function to create a new uint element.
+     * @param value the uint value of the element.
+     * @return the new uint element.
+     */
+    function newUintElement(uint256 value) internal pure returns (Json memory) {
+        return
+            Json({
+                jsonType: JsonType.ELEMENT_UINT, // type
+                objectKeys: new string[](0), // default
+                values: new Json[](0), // default
+                stringEncodingFlag: StringEncodingFlag.NONE, // default
+                elementValueString: "", // default
+                elementValueUintOrBool: value // input
+            });
+    }
+
+    /**
+     * Convenience function to create a new boolean element.
+     * @param value the boolean value of the element.
+     * @return the new boolean element.
+     */
+    function newBooleanElement(bool value) internal pure returns (Json memory) {
+        return
+            Json({
+                jsonType: JsonType.ELEMENT_BOOLEAN, // type
+                objectKeys: new string[](0), // default
+                values: new Json[](0), // default
+                stringEncodingFlag: StringEncodingFlag.NONE, // default
+                elementValueString: "", // default
+                elementValueUintOrBool: value ? 1 : 0 // input
+            });
+    }
+
+    /**
+     * @notice writes a json struct to a string
+     * @param json the json struct to write
+     * @return the json string
+     */
+    function write(Json memory json) internal pure returns (string memory) {
+        if (json.jsonType == JsonType.OBJECT) {
+            return _writeObject(json);
+        } else if (json.jsonType == JsonType.ARRAY) {
+            return _writeArray(json);
+        } else if (json.jsonType == JsonType.ELEMENT_STRING) {
+            return
+                _writeString(json.elementValueString, json.stringEncodingFlag);
+        } else if (json.jsonType == JsonType.ELEMENT_UINT) {
+            return _writeUint(json.elementValueUintOrBool);
+        } else if (json.jsonType == JsonType.ELEMENT_BOOLEAN) {
+            return _writeBoolean(json.elementValueUintOrBool);
+        } else {
+            return _writeNull();
+        }
+    }
+
+    /**
+     * @notice writes a json struct of type JsonType.OBJECT to a string
+     * @param json the json struct of type JsonType.OBJECT to write
+     * @return the json string
+     */
+    function _writeObject(
+        Json memory json
+    ) private pure returns (string memory) {
+        // pre-allocate string array to avoid dynamic memory allocation
+        uint256 keysLength = json.objectKeys.length;
+        string[] memory valueStrings = new string[](keysLength);
+        for (uint256 i = 0; i < keysLength; i++) {
+            // only trailing comma if not last child, per JSON spec
+            string memory trailingChar = i < keysLength - 1 ? "," : "";
+            valueStrings[i] = string.concat(
+                '"',
+                json.objectKeys[i], // keys assumed to be valid JSON keys
+                '":',
+                json.values[i].write(),
+                trailingChar
+            );
+        }
+        // concat all valueStrings and return
+        return string.concat("{", _concatenateStrings(valueStrings), "}");
+    }
+
+    /**
+     * @notice writes a json struct of type JsonType.ARRAY to a string
+     * @param json the json struct of type JsonType.ARRAY to write
+     * @return the json string
+     */
+    function _writeArray(
+        Json memory json
+    ) private pure returns (string memory) {
+        // pre-allocate string array to avoid dynamic memory allocation
+        uint256 valuesLength = json.values.length;
+        string[] memory valueStrings = new string[](valuesLength);
+        for (uint256 i = 0; i < valuesLength; i++) {
+            // only trailing comma if not last child, per JSON spec
+            string memory trailingChar = i < valuesLength - 1 ? "," : "";
+            valueStrings[i] = string.concat(
+                json.values[i].write(),
+                trailingChar
+            );
+        }
+        // concat all valueStrings and return
+        return string.concat("[", _concatenateStrings(valueStrings), "]");
+    }
+
+    /**
+     * @notice writes a string value to a valid json string.
+     * If the string encoding flag is set to BASE64, the written value will be base64 encoded.
+     * @param value the string value to write
+     * @param stringEncodingFlag the string encoding flag for the value
+     * @return the json string
+     */
+    function _writeString(
+        string memory value,
+        StringEncodingFlag stringEncodingFlag
+    ) private pure returns (string memory) {
+        if (stringEncodingFlag == StringEncodingFlag.BASE64) {
+            return _writeBase64(value);
+        } else {
+            return _writePlainString(value);
+        }
+    }
+
+    /**
+     * @notice writes a string value to a valid json string
+     * @param value the string value to write
+     * @return the json string
+     */
+    function _writePlainString(
+        string memory value
+    ) private pure returns (string memory) {
+        return string.concat('"', value, '"');
+    }
+
+    /**
+     * @notice writes a base64 encoded string value to a valid json string
+     * @param value the string value to write
+     * @return the json string
+     */
+    function _writeBase64(
+        string memory value
+    ) private pure returns (string memory) {
+        return string.concat('"', Base64.encode(bytes(value)), '"');
+    }
+
+    /**
+     * @notice writes a uint value to a valid json string
+     * @param value the uint value to write
+     * @return the json string
+     */
+    function _writeUint(uint256 value) private pure returns (string memory) {
+        // @dev no quotes around numbers
+        return value.toString();
+    }
+
+    /**
+     * @notice writes a boolean value to a valid json string.
+     * If the value is equal to zero, it is written as false, otherwise it is written as true.
+     * @dev Booleans are written as true or false without quotes.
+     * @param value the value to write
+     * @return the json string
+     */
+    function _writeBoolean(uint256 value) private pure returns (string memory) {
+        // @dev no quotes around booleans
+        return (value > 0) ? "true" : "false";
+    }
+
+    /**
+     * @notice writes a null value to a valid json string
+     * @return the json string
+     */
+    function _writeNull() private pure returns (string memory) {
+        return "null";
+    }
+
+    /**
+     * @notice Helper function to efficiently concatenate an array of strings.
+     * @dev portions of code generated with AI Assistance, modified and tested by human developers.
+     * @param strings The array of strings to concatenate.
+     * @return The concatenated string.
+     */
+    function _concatenateStrings(
+        string[] memory strings
+    ) private pure returns (string memory) {
+        uint totalLength = 0;
+
+        // Step 1: Calculate the total length of the result string
+        for (uint i = 0; i < strings.length; i++) {
+            totalLength += bytes(strings[i]).length;
+        }
+
+        // Step 2: Allocate memory for the resulting string
+        string memory result = new string(totalLength); // Allocate memory for the result, also defining its length
+        uint resultPtr;
+        assembly {
+            resultPtr := add(result, 0x20) // Point to the start of the string's data in memory
+        }
+
+        // Step 3: Copy each string into the result using assembly
+        for (uint i = 0; i < strings.length; i++) {
+            bytes memory currentString = bytes(strings[i]);
+            uint currentLength = currentString.length;
+            uint currentPtr;
+
+            assembly {
+                currentPtr := add(currentString, 0x20) // Start of current string's data
+            }
+
+            // Copy the full 32-byte chunks
+            uint chunks = currentLength / 32;
+            uint remainder = currentLength % 32;
+
+            for (uint j = 0; j < chunks; j++) {
+                assembly {
+                    let chunk := mload(currentPtr) // Load 32 bytes of the current string
+                    mstore(resultPtr, chunk) // Store the 32 bytes into the result
+                    resultPtr := add(resultPtr, 0x20) // Move the result pointer forward by 32 bytes
+                    currentPtr := add(currentPtr, 0x20) // Move the current string pointer forward by 32 bytes
+                }
+            }
+
+            // Handle remaining bytes (less than 32)
+            if (remainder > 0) {
+                assembly {
+                    let chunk := mload(currentPtr) // Load 32 bytes
+                    let mask := sub(shl(mul(8, sub(0x20, remainder)), 1), 1) // Create mask for the remainder
+                    let lastChunk := and(chunk, not(mask)) // Mask out the excess bits
+                    mstore(resultPtr, lastChunk) // Store the remaining bytes into the result
+                    resultPtr := add(resultPtr, remainder) // Move the result pointer forward by the remainder length
+                }
+            }
+        }
+
+        return result;
+    }
+}