@artblocks/contracts 1.3.2 → 1.4.0

package/contracts/engine/V3/transfer-hooks/AbstractTransferHook.sol

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+pragma solidity ^0.8.0;
+
+import {ITransferHook} from "../../../interfaces/v0.8.x/ITransferHook.sol";
+
+import {ERC165} from "@openzeppelin-5.0/contracts/utils/introspection/ERC165.sol";
+import {IERC165} from "@openzeppelin-5.0/contracts/interfaces/IERC165.sol";
+
+/**
+ * @title Abstract transfer hook
+ * @author Art Blocks Inc.
+ * @notice Inherit this to implement `ITransferHook` with ERC-165. Child
+ * contracts implement `_onTokenTransfer` instead of `onTokenTransfer`.
+ * ----------------------------------------------------------------------------
+ * This contract enforces that `coreContract` is the caller, so children may
+ * safely treat the `coreContract` argument as trusted-as-caller. It does NOT,
+ * and cannot, know which cores a given hook is willing to serve.
+ * ----------------------------------------------------------------------------
+ * WARNING: Children MUST still verify that `coreContract` is a core they
+ * expect. Without that check, any deployed contract can invoke this hook with
+ * arbitrary `tokenId`, `from`, `to`, and `operator` values by calling it from
+ * its own address.
+ */
+abstract contract AbstractTransferHook is ITransferHook, ERC165 {
+    /**
+     * @notice Thrown when `onTokenTransfer` is called by an address other than
+     * the `coreContract` it was passed.
+     * @param caller The address that called `onTokenTransfer`.
+     * @param coreContract The `coreContract` argument that was passed.
+     */
+    error TransferHookCallerNotCoreContract(
+        address caller,
+        address coreContract
+    );
+
+    /**
+     * @notice Execution logic to be executed after a token's ownership updates.
+     * @dev Called after the ERC-721 ownership write. On mint, called after the
+     * token hash seed is assigned. Reverting aborts the mint or transfer.
+     * @dev Intentionally not `virtual`: the caller check below is a security
+     * invariant of this base contract, and children override `_onTokenTransfer`
+     * so they cannot remove it by accident.
+     */
+    function onTokenTransfer(
+        address coreContract,
+        uint256 tokenId,
+        address from,
+        address to,
+        address operator
+    ) external {
+        // @dev a conforming core always passes its own address, so this only
+        // rejects callers that are spoofing another contract's identity
+        if (msg.sender != coreContract) {
+            revert TransferHookCallerNotCoreContract({
+                caller: msg.sender,
+                coreContract: coreContract
+            });
+        }
+        _onTokenTransfer({
+            coreContract: coreContract,
+            tokenId: tokenId,
+            from: from,
+            to: to,
+            operator: operator
+        });
+    }
+
+    /**
+     * @notice Hook implementation, called only after `coreContract` has been
+     * verified to be `msg.sender`.
+     * @dev Implementations MUST still verify that `coreContract` is a core
+     * this hook is intended to serve.
+     * @param coreContract The core contract that performed the ownership
+     * update. Guaranteed equal to `msg.sender`.
+     * @param tokenId The token whose ownership changed.
+     * @param from Previous owner. `address(0)` on mint.
+     * @param to New owner.
+     * @param operator Transfer operator, or the mint's initiating address.
+     */
+    function _onTokenTransfer(
+        address coreContract,
+        uint256 tokenId,
+        address from,
+        address to,
+        address operator
+    ) internal virtual;
+
+    /**
+     * @notice Indicates support for `ITransferHook` (`0x6344b0e2`), which V3
+     * cores require before a hook may be configured.
+     */
+    function supportsInterface(
+        bytes4 interfaceId
+    ) public view virtual override(ERC165, IERC165) returns (bool) {
+        return
+            interfaceId == type(ITransferHook).interfaceId ||
+            super.supportsInterface(interfaceId);
+    }
+}

package/contracts/engine/V3/transfer-hooks/OwnerHistoryTransferHook.sol

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+// Created By: Art Blocks Inc.
+
+// @dev fixed to specific solidity version for clarity and for more clear
+// source code verification purposes.
+pragma solidity 0.8.22;
+
+import {AbstractTransferHook} from "./AbstractTransferHook.sol";
+
+import {IOwnerHistoryTransferHook} from "../../../interfaces/v0.8.x/IOwnerHistoryTransferHook.sol";
+import {ITransferHook} from "../../../interfaces/v0.8.x/ITransferHook.sol";
+import {IGenArt721CoreContractV3_Engine} from "../../../interfaces/v0.8.x/IGenArt721CoreContractV3_Engine.sol";
+
+import {IERC165} from "@openzeppelin-5.0/contracts/interfaces/IERC165.sol";
+
+import {ABHelpers} from "../../../libs/v0.8.x/ABHelpers.sol";
+
+/**
+ * @title On-chain owner history transfer hook
+ * @author Art Blocks Inc.
+ * @notice Reference `ITransferHook` implementation. Records the full chain of
+ * owners a token has had, on chain and readable by other contracts — including
+ * by an artwork's own script through the on-chain generator.
+ * ----------------------------------------------------------------------------
+ * A single deployment serves every project, on every v3.3+ Engine core on the
+ * network, that configures this address as its transfer hook. There is no
+ * owner, no allowlist and nothing to configure: an artist points their project
+ * at this address with `configureProjectTransferHook`, and may make that
+ * permanent with `lockProjectTransferHook`.
+ * ----------------------------------------------------------------------------
+ * GAS. Recording ownership on chain is not free, and the artist is choosing
+ * this cost on behalf of everyone who will ever transfer one of their tokens.
+ * Measured against an otherwise identical project with no hook, on a v3.3
+ * Engine core:
+ *
+ * - a transfer costs about 48,400 gas more — 62,748 becomes 111,181, so
+ *   roughly a 77% increase. Most of it is unavoidable: ~22,000 for the new
+ *   storage slot holding the owner, and ~17,000 for the core's own reentrancy
+ *   flag, which any hook pays.
+ * - a mint costs about 88,800 gas more, because the first ownership change a
+ *   token sees writes both the anchor entry and the new owner.
+ *
+ * An owner is 20 bytes and a storage slot is 32, so ~22,000 gas per owner is
+ * the floor for holding this on chain; the packed timestamp rides along free.
+ * A project that only needs provenance for off-chain consumers should index
+ * the core's own `Transfer` events instead and configure no hook at all — this
+ * hook writes storage because it is meant to be read by other contracts,
+ * including an artwork's own script through the on-chain generator.
+ * ----------------------------------------------------------------------------
+ * COMPLETENESS. The chain is only complete from mint if this hook was
+ * configured before the token was minted. A hook configured mid-life starts at
+ * the owner it first observes; `isTrackedFromMint` reports which case a token
+ * is in. If a project's hook is later cleared, recording simply stops — the
+ * records already written stay readable.
+ * ----------------------------------------------------------------------------
+ * SAFETY. A reverting hook aborts the transfer that invoked it, so a hook that
+ * can revert can make a token permanently non-transferable. This one writes
+ * storage and cannot revert on a transfer of a project that has it configured:
+ * the only revert path is the configuration check below, which is true by
+ * construction whenever the core actually dispatches to this address.
+ */
+contract OwnerHistoryTransferHook is
+    AbstractTransferHook,
+    IOwnerHistoryTransferHook
+{
+    /**
+     * @notice Ownership chain per token, oldest first, keyed by core contract.
+     * @dev Keying by `coreContract` is what makes a single shared deployment
+     * safe: `AbstractTransferHook` guarantees `coreContract == msg.sender`, so
+     * a contract impersonating a core can only ever write beneath its own
+     * address, where nothing reads. The configuration check in
+     * `_onTokenTransfer` is a second, independent guard.
+     */
+    mapping(address coreContract => mapping(uint256 tokenId => OwnerRecord[]))
+        private _ownerHistory;
+
+    /**
+     * @notice Record an ownership change.
+     * @dev Called by the core after the ERC-721 ownership write, and on mint
+     * after the token hash seed is assigned, so a hook reading `tokenIdToHash`
+     * sees the final value.
+     * @param coreContract Core that performed the ownership update. Guaranteed
+     * by `AbstractTransferHook` to equal `msg.sender`.
+     * @param tokenId Token whose ownership changed.
+     * @param from Previous owner; `address(0)` on mint.
+     * @param to New owner.
+     */
+    function _onTokenTransfer(
+        address coreContract,
+        uint256 tokenId,
+        address from,
+        address to,
+        address /* operator */
+    ) internal override {
+        _onlyConfiguredForProject({
+            coreContract: coreContract,
+            projectId: ABHelpers.tokenIdToProjectId(tokenId)
+        });
+
+        // @dev ERC-721 permits `transferFrom(a, a, id)`. Ownership did not
+        // change, so recording it would put the same owner in the chain twice.
+        if (from == to) {
+            return;
+        }
+
+        OwnerRecord[] storage records = _ownerHistory[coreContract][tokenId];
+        if (records.length == 0) {
+            // Anchor the chain with the owner that preceded the first change
+            // this hook saw. That is `address(0)` when the hook was configured
+            // before the mint, which is what `isTrackedFromMint` reads.
+            _push({
+                records: records,
+                coreContract: coreContract,
+                tokenId: tokenId,
+                owner: from
+            });
+        }
+        _push({
+            records: records,
+            coreContract: coreContract,
+            tokenId: tokenId,
+            owner: to
+        });
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function ownerHistory(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (OwnerRecord[] memory records) {
+        return _ownerHistory[coreContract][tokenId];
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function ownerHistorySlice(
+        address coreContract,
+        uint256 tokenId,
+        uint256 start,
+        uint256 count
+    ) external view returns (OwnerRecord[] memory records) {
+        OwnerRecord[] storage stored = _ownerHistory[coreContract][tokenId];
+        uint256 length = stored.length;
+        if (start >= length) {
+            return new OwnerRecord[](0);
+        }
+        uint256 remaining = length - start;
+        uint256 resultLength = count < remaining ? count : remaining;
+        records = new OwnerRecord[](resultLength);
+        for (uint256 i = 0; i < resultLength; ) {
+            records[i] = stored[start + i];
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function ownerHistoryLength(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (uint256) {
+        return _ownerHistory[coreContract][tokenId].length;
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function previousOwners(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (address[] memory owners) {
+        OwnerRecord[] storage stored = _ownerHistory[coreContract][tokenId];
+        uint256 length = stored.length;
+        // @dev the anchor is `address(0)` for a token tracked from its mint,
+        // which is not an owner; for a token first seen mid-life it is the real
+        // owner at that moment, and belongs in the result
+        uint256 start = (length > 0 && stored[0].owner == address(0)) ? 1 : 0;
+        // @dev the final record is the current owner, not a previous one
+        if (length < start + 2) {
+            return new address[](0);
+        }
+        uint256 resultLength = length - start - 1;
+        owners = new address[](resultLength);
+        for (uint256 i = 0; i < resultLength; ) {
+            owners[i] = stored[start + i].owner;
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function lastRecordedOwner(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (address owner) {
+        OwnerRecord[] storage stored = _ownerHistory[coreContract][tokenId];
+        uint256 length = stored.length;
+        if (length == 0) {
+            return address(0);
+        }
+        return stored[length - 1].owner;
+    }
+
+    /**
+     * @inheritdoc IOwnerHistoryTransferHook
+     */
+    function isTrackedFromMint(
+        address coreContract,
+        uint256 tokenId
+    ) external view returns (bool) {
+        OwnerRecord[] storage stored = _ownerHistory[coreContract][tokenId];
+        // @dev the anchor record holds the owner before the first observed
+        // change, which is `address(0)` only for a mint
+        return stored.length > 0 && stored[0].owner == address(0);
+    }
+
+    /**
+     * @notice Append one record and emit it.
+     */
+    function _push(
+        OwnerRecord[] storage records,
+        address coreContract,
+        uint256 tokenId,
+        address owner
+    ) private {
+        // @dev uint96 seconds is not a practical bound; no cast check needed
+        uint96 timestamp = uint96(block.timestamp);
+        records.push(OwnerRecord({owner: owner, timestamp: timestamp}));
+        emit OwnerRecorded({
+            coreContract: coreContract,
+            tokenId: tokenId,
+            owner: owner,
+            index: records.length - 1,
+            timestamp: timestamp
+        });
+    }
+
+    /**
+     * @notice Revert unless `coreContract` has this hook configured for
+     * `projectId`.
+     * @dev This is the `ITransferHook` requirement that an implementation
+     * verify which cores it serves, answered without any configuration of its
+     * own: the set of cores this hook serves is exactly the set that points at
+     * it. A contract impersonating a core could answer this call dishonestly,
+     * which is why it is a second guard rather than the only one — the storage
+     * keyed by `coreContract` already confines such a caller to its own
+     * namespace.
+     */
+    function _onlyConfiguredForProject(
+        address coreContract,
+        uint256 projectId
+    ) private view {
+        (address configuredHook, ) = IGenArt721CoreContractV3_Engine(
+            coreContract
+        ).projectTransferHookConfig(projectId);
+        if (configuredHook != address(this)) {
+            revert HookNotConfiguredForProject({
+                coreContract: coreContract,
+                projectId: projectId,
+                configuredHook: configuredHook
+            });
+        }
+    }
+
+    /**
+     * @notice Indicates support for `ITransferHook`, which v3.3 cores require
+     * before a hook may be configured.
+     */
+    function supportsInterface(
+        bytes4 interfaceId
+    )
+        public
+        view
+        virtual
+        override(AbstractTransferHook, IERC165)
+        returns (bool)
+    {
+        return
+            interfaceId == type(IOwnerHistoryTransferHook).interfaceId ||
+            super.supportsInterface(interfaceId);
+    }
+}

package/contracts/generator/GenArt721GeneratorV0.sol

@@ -821,17 +821,16 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
         HTMLTag memory htmlTag
     ) internal view {
         // Get script count and preferred CDN for the dependency.
-        (
-            ,
-            ,
-            string memory preferredCDN,
-            ,
-            ,
-            ,
-            ,
-            ,
-            uint24 scriptCount
-        ) = dependencyRegistry.getDependencyDetails(dependencyNameAndVersion);
+        string memory preferredCDN;
+        uint24 scriptCount;
+        // @dev block scope to limit stack usage
+        {
+            IDependencyRegistryV0.DependencyDetails
+                memory dependencyDetails = dependencyRegistry
+                    .getDependencyDetailsV2(dependencyNameAndVersion);
+            preferredCDN = dependencyDetails.preferredCDN;
+            scriptCount = dependencyDetails.scriptCount;
+        }
 
         // If no scripts on-chain, load the script from the preferred CDN.
         if (scriptCount == 0) {
@@ -873,6 +872,21 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
             .getDependencyNameAndVersionForProject(coreContract, projectId)
             .stringToBytes32();
 
+        // @dev All rendering directives are prescribed by the dependency registry, so that
+        // supporting a new kind of dependency is an admin configuration change rather than a
+        // contract upgrade.
+        IDependencyRegistryV0.DependencyDetails
+            memory dependencyDetails = dependencyRegistry
+                .getDependencyDetailsV2(dependencyNameAndVersion);
+
+        // @dev A raw HTML dependency stores a complete HTML document as its project script
+        // rather than a JavaScript program. Such a document must be injected verbatim -
+        // wrapping it in a script tag both breaks HTML parsing (the document's own
+        // "</script>" terminates the wrapper early) and is semantically wrong, since markup
+        // inside a script tag is never rendered.
+        bool isRawHtmlDep = dependencyDetails.projectScriptTagType ==
+            IDependencyRegistryV0.ProjectScriptTagType.RawHtml;
+
         // Create head tags
         // pre-fetch data to properly allocate memory for HTML tags
         (
@@ -885,14 +899,18 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
         // @dev memoize length for efficiency
         uint256 dependencyRegistryAssetNamesAndVersionsLength = dependencyRegistryAssetNameAndVersions
                 .length;
-        // @dev length is 2 (style, tokenData) + number of external asset dependencies
+        // @dev length is 3 (style, tokenData, import map) + number of external asset dependencies
         HTMLTag[] memory headTags = new HTMLTag[](
-            2 + dependencyRegistryAssetNamesAndVersionsLength
+            3 + dependencyRegistryAssetNamesAndVersionsLength
         );
-        headTags[0].tagOpen = "<style>";
-        headTags[0]
-            .tagContent = "html{height:100%}body{min-height:100%;margin:0;padding:0}canvas{padding:0;margin:auto;display:block;position:absolute;top:0;bottom:0;left:0;right:0}";
-        headTags[0].tagClose = "</style>";
+        // @dev The default style reset is omitted for raw HTML documents, which supply
+        // their own document-level styling. This matches Art Blocks' hosted generator.
+        if (!isRawHtmlDep) {
+            headTags[0].tagOpen = "<style>";
+            headTags[0]
+                .tagContent = "html{height:100%}body{min-height:100%;margin:0;padding:0}canvas{padding:0;margin:auto;display:block;position:absolute;top:0;bottom:0;left:0;right:0}";
+            headTags[0].tagClose = "</style>";
+        }
 
         // @dev decode any base64 encoded flex data in the browser while parsing the json
         headTags[1].tagContent = abi.encodePacked(
@@ -901,6 +919,17 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
             '`, (key, value) => key === "data" && value !== null ? value.startsWith("#web3call#") ? Object.entries(JSON.parse(atob(value.slice(10)))).reduce((acc, [k, v]) => ((acc[atob(k)] = atob(v)), acc), {}) : atob(value) : value);'
         );
         headTags[1].tagType = HTMLTagType.script;
+
+        // @dev An ES module dependency cannot be loaded with a plain script tag, and project
+        // scripts import it by bare specifier (e.g. `import * as THREE from "three"`). An
+        // import map maps that specifier to the dependency's URL, and must appear in the head
+        // before any module is loaded.
+        _populateImportMapHtmlTag({
+            dependencyNameAndVersion: dependencyNameAndVersion,
+            dependencyDetails: dependencyDetails,
+            htmlTag: headTags[2]
+        });
+
         for (
             uint256 i = 0;
             i < dependencyRegistryAssetNamesAndVersionsLength;
@@ -914,7 +943,7 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
             // populate head tags with dependency registry scripts
             _populateDependencyScriptHtmlTag(
                 dependencyRegistryAssetNameAndVersions[i],
-                headTags[2 + i]
+                headTags[3 + i]
             );
         }
 
@@ -922,7 +951,15 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
         HTMLTag[] memory bodyTags = new HTMLTag[](4);
 
         // Dependency script tag
-        _populateDependencyScriptHtmlTag(dependencyNameAndVersion, bodyTags[0]);
+        // @dev A module dependency is reached through the import map emitted in the head, so
+        // emitting a script tag for it here would load the module as a classic script and
+        // raise a syntax error on its `export` statements.
+        if (!dependencyDetails.loadAsModule) {
+            _populateDependencyScriptHtmlTag(
+                dependencyNameAndVersion,
+                bodyTags[0]
+            );
+        }
 
         // @dev We expect all of our dependencies to be added gzip'd and base64 encoded
         // so we need to include this so we can gunzip them in the browser.
@@ -935,22 +972,18 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
         );
 
         HTMLTag memory canvasTag = _createCanvasTagIfNeeded(
-            dependencyNameAndVersion
+            dependencyNameAndVersion,
+            dependencyDetails.canvasTagType
         );
 
-        bool isProcessingDep = dependencyNameAndVersion ==
-            bytes32("processing-js@1.4.6");
-
         bytes memory projectScript = _getProjectScriptBytes(
             coreContract,
             projectId
         );
 
         HTMLTag memory projectScriptTag = HTMLTag({
-            tagOpen: isProcessingDep
-                ? bytes("<script type='application/processing'>")
-                : bytes("<script>"),
-            tagClose: bytes("</script>"),
+            tagOpen: _getProjectScriptTagOpen(dependencyDetails),
+            tagClose: isRawHtmlDep ? bytes("") : bytes("</script>"),
             tagType: HTMLTagType.useTagOpenAndClose,
             name: "",
             contractAddress: address(0),
@@ -958,12 +991,15 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
             tagContent: projectScript
         });
 
-        if (isProcessingDep) {
+        if (
+            dependencyDetails.canvasTagType ==
+            IDependencyRegistryV0.CanvasTagType.CanvasAfterProjectScript
+        ) {
             bodyTags[2] = projectScriptTag;
             bodyTags[3] = canvasTag;
         } else {
-            bodyTags[3] = projectScriptTag;
             bodyTags[2] = canvasTag;
+            bodyTags[3] = projectScriptTag;
         }
 
         HTMLRequest memory htmlRequest;
@@ -1021,8 +1057,10 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
             return true;
         }
         // query and return result of dependency registry for on-chain status
-        (, , , , , , , availableOnChain, ) = dependencyRegistry
-            .getDependencyDetails(dependencyNameAndVersion);
+        return
+            dependencyRegistry
+                .getDependencyDetailsV2(dependencyNameAndVersion)
+                .availableOnChain;
     }
 
     /**
@@ -1067,13 +1105,13 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
     }
 
     /**
-     * @dev Helper function to get a canvas tag or an empty tag depending on the dependency name.
-     * @return The canvas tag or an empty tag.
+     * @dev Helper function to extract the dependency name preceding the "@" separator.
+     * @param dependencyNameAndVersion Dependency identifier of the form "name@version".
+     * @return The dependency name, e.g. "three" for "three@0.167.0".
      */
-    function _createCanvasTagIfNeeded(
+    function _getDependencyName(
         bytes32 dependencyNameAndVersion
-    ) internal pure returns (HTMLTag memory) {
-        // Extract dependency name before @ symbol
+    ) internal pure returns (bytes memory) {
         uint atSignIndex;
         for (uint i = 0; i < dependencyNameAndVersion.length; i++) {
             if (dependencyNameAndVersion[i] == "@") {
@@ -1086,22 +1124,82 @@ contract GenArt721GeneratorV0 is Initializable, IGenArt721GeneratorV0 {
         for (uint i = 0; i < atSignIndex; i++) {
             nameBeforeAt[i] = dependencyNameAndVersion[i];
         }
-        string memory depNameStr = string(nameBeforeAt);
+        return nameBeforeAt;
+    }
 
-        // Check if dependency needs canvas
-        bytes32 nameHash = keccak256(nameBeforeAt);
-        if (
-            nameHash == keccak256(bytes("js")) ||
-            nameHash == keccak256(bytes("babylon")) ||
-            nameHash == keccak256(bytes("tone")) ||
-            nameHash == keccak256(bytes("zdog")) ||
-            nameHash == keccak256(bytes("processing-js"))
-        ) {
+    /**
+     * @dev Helper function to build the opening tag wrapping a project's script.
+     * @param dependencyDetails Details of the project's dependency, prescribing how the
+     * project script must be injected.
+     * @return The opening tag, or an empty value when the script is raw HTML.
+     */
+    function _getProjectScriptTagOpen(
+        IDependencyRegistryV0.DependencyDetails memory dependencyDetails
+    ) internal pure returns (bytes memory) {
+        IDependencyRegistryV0.ProjectScriptTagType tagType = dependencyDetails
+            .projectScriptTagType;
+        if (tagType == IDependencyRegistryV0.ProjectScriptTagType.RawHtml) {
+            return bytes("");
+        }
+        if (tagType == IDependencyRegistryV0.ProjectScriptTagType.Module) {
+            return bytes('<script type="module">');
+        }
+        if (tagType == IDependencyRegistryV0.ProjectScriptTagType.SpecialType) {
+            return
+                abi.encodePacked(
+                    "<script type='",
+                    dependencyDetails.projectScriptSpecialType,
+                    "'>"
+                );
+        }
+        return bytes("<script>");
+    }
+
+    /**
+     * @dev Helper function to populate an import map tag, which maps a module dependency's
+     * bare specifier (its name) to the URL the module is served from. Left empty for
+     * dependencies that are not loaded as modules.
+     * @param dependencyNameAndVersion Dependency identifier of the form "name@version".
+     * @param dependencyDetails Details of the dependency.
+     * @param htmlTag The HTMLTag to populate.
+     */
+    function _populateImportMapHtmlTag(
+        bytes32 dependencyNameAndVersion,
+        IDependencyRegistryV0.DependencyDetails memory dependencyDetails,
+        HTMLTag memory htmlTag
+    ) internal pure {
+        if (!dependencyDetails.loadAsModule) {
+            return;
+        }
+
+        htmlTag.tagType = HTMLTagType.useTagOpenAndClose;
+        htmlTag.tagOpen = abi.encodePacked(
+            '<script type="importmap">{"imports":{"',
+            _getDependencyName(dependencyNameAndVersion),
+            '":"',
+            dependencyDetails.preferredCDN,
+            '"}}'
+        );
+        htmlTag.tagClose = bytes("</script>");
+    }
+
+    /**
+     * @dev Helper function to get a canvas tag or an empty tag, per the dependency's
+     * registry-prescribed canvas requirement.
+     * @param dependencyNameAndVersion Dependency identifier, used to name the canvas element.
+     * @param canvasTagType Whether a canvas is required.
+     * @return The canvas tag or an empty tag.
+     */
+    function _createCanvasTagIfNeeded(
+        bytes32 dependencyNameAndVersion,
+        IDependencyRegistryV0.CanvasTagType canvasTagType
+    ) internal pure returns (HTMLTag memory) {
+        if (canvasTagType != IDependencyRegistryV0.CanvasTagType.NoCanvasTag) {
             return
                 HTMLTag({
                     tagOpen: abi.encodePacked(
                         "<canvas id='",
-                        depNameStr,
+                        _getDependencyName(dependencyNameAndVersion),
                         "-canvas'>"
                     ),
                     tagClose: bytes("</canvas>"),

package/contracts/helpers/ERC1967ProxyImport.sol

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.22;
+
+// Ensures hardhat compiles ERC1967Proxy into artifacts for deployment scripts.
+import {ERC1967Proxy} from "@openzeppelin-5.0/contracts/proxy/ERC1967/ERC1967Proxy.sol";