@dpa-oss/dpa 1.0.0

package/contracts/DPA.sol

@@ -0,0 +1,740 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "erc721a/contracts/ERC721A.sol";
+import "@openzeppelin/contracts/access/Ownable.sol";
+import "@openzeppelin/contracts/utils/Pausable.sol";
+import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
+import "./shared/Types.sol";
+import "./shared/Errors.sol";
+import "./shared/IDPA.sol";
+import "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+/**
+ * @title DPA (Digital Public Asset)
+ * @dev Abstract contract for creating digital public assets with ERC721A
+ *      Features:
+ *      - Orchestrator-only minting (changeable by owner)
+ *      - Token content storage as generic bytes (decoded by implementers)
+ *      - Batch minting support
+ *      - Protocol-enforced revision linked-list for full traceability
+ *      - On-chain events for all operations
+ */
+abstract contract DPA is ERC721A, Ownable, Pausable, ReentrancyGuard {
+    // ============ State Variables ============
+
+    /// @notice The orchestrator address (only this address can mint/revise)
+    address public orchestrator;
+
+    /// @dev Token ID -> Token URI
+    mapping(uint256 => string) private _tokenURIs;
+
+    /// @dev Token ID -> Token content (encoded bytes, decoded by implementers)
+    mapping(uint256 => bytes) private _tokenContents;
+
+    /// @dev Token ID -> Revision record
+    mapping(uint256 => Types.RevisionRecord) private _revisions;
+
+    /// @dev Token ID -> Child token ID (single child for linear chain)
+    mapping(uint256 => uint256) private _childToken;
+
+    /// @dev Token ID -> name hash -> linked DPA contract address
+    mapping(uint256 => mapping(bytes32 => address)) private _linkedDPAs;
+
+    /// @dev Token ID -> array of link name hashes (for enumeration)
+    mapping(uint256 => bytes32[]) private _linkedDPANames;
+
+    /// @dev Counter for total unique digital public assets (origin tokens only)
+    uint256 private _totalAssets;
+
+    // ============ Events ============
+
+    /// @notice Emitted when a new token is minted
+    event TokenMinted(uint256 indexed tokenId, address indexed to, string uri);
+
+    /// @notice Emitted when tokens are batch minted
+    event BatchMinted(
+        uint256 indexed startTokenId,
+        uint256 quantity,
+        address indexed to
+    );
+
+    /// @notice Emitted when a token is revised (full reason string for off-chain indexing)
+    event TokenRevised(
+        uint256 indexed newTokenId,
+        uint256 indexed parentTokenId,
+        uint256 indexed originTokenId,
+        string reason
+    );
+
+    /// @notice Emitted when orchestrator is changed
+    event OrchestratorUpdated(
+        address indexed previousOrchestrator,
+        address indexed newOrchestrator
+    );
+
+    /// @notice Emitted when a DPA contract is linked to a token
+    event DPALinked(
+        uint256 indexed tokenId,
+        bytes32 indexed nameHash,
+        address indexed dpaContract,
+        string name
+    );
+
+    /// @notice Emitted when a DPA contract is unlinked from a token
+    event DPAUnlinked(
+        uint256 indexed tokenId,
+        bytes32 indexed nameHash,
+        address indexed dpaContract
+    );
+
+    // ============ Modifiers ============
+
+    /// @dev Restricts function access to orchestrator only
+    modifier onlyOrchestrator() {
+        if (msg.sender != orchestrator) {
+            revert Errors.NotOrchestrator();
+        }
+        _;
+    }
+
+    /// @dev Restricts function to only operate on latest version tokens
+    modifier onlyLatestVersion(uint256 tokenId) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        if (_childToken[tokenId] != 0) {
+            revert Errors.NotLatestVersion();
+        }
+        _;
+    }
+
+    // ============ Constructor ============
+
+    /**
+     * @param name_ Token collection name
+     * @param symbol_ Token collection symbol
+     * @param orchestrator_ Initial orchestrator address
+     */
+    constructor(
+        string memory name_,
+        string memory symbol_,
+        address orchestrator_
+    ) ERC721A(name_, symbol_) Ownable(msg.sender) {
+        if (orchestrator_ == address(0)) {
+            revert Errors.ZeroAddress();
+        }
+        orchestrator = orchestrator_;
+    }
+
+    // ============ Admin Functions ============
+
+    /**
+     * @notice Updates the orchestrator address
+     * @param newOrchestrator New orchestrator address
+     */
+    function setOrchestrator(address newOrchestrator) external onlyOwner {
+        if (newOrchestrator == address(0)) {
+            revert Errors.ZeroAddress();
+        }
+        address previous = orchestrator;
+        orchestrator = newOrchestrator;
+        emit OrchestratorUpdated(previous, newOrchestrator);
+    }
+
+    /**
+     * @notice Pauses all minting and revision operations
+     */
+    function pause() external onlyOwner {
+        _pause();
+    }
+
+    /**
+     * @notice Unpauses all minting and revision operations
+     */
+    function unpause() external onlyOwner {
+        _unpause();
+    }
+
+    // ============ Minting Functions ============
+
+    /**
+     * @notice Mints a single token with URI and content
+     * @param to Recipient address
+     * @param uri Token URI (metadata location)
+     * @param content Encoded content data (decoded by derived contract)
+     * @return tokenId The minted token ID
+     */
+    function mint(
+        address to,
+        string calldata uri,
+        bytes calldata content
+    )
+        external
+        onlyOrchestrator
+        whenNotPaused
+        nonReentrant
+        returns (uint256 tokenId)
+    {
+        tokenId = _nextTokenId();
+
+        // Validate content through derived contract
+        _validateContent(content);
+
+        // Mint the token
+        _mint(to, 1);
+
+        // Store URI and content
+        _tokenURIs[tokenId] = uri;
+        _tokenContents[tokenId] = content;
+
+        // Create initial revision record (no parent, version 1)
+        _revisions[tokenId] = Types.RevisionRecord({
+            previousTokenId: 0,
+            originTokenId: tokenId, // Self-reference for origin
+            version: 1, // Origin is version 1
+            reasonHash: bytes32(0), // No reason for initial creation
+            timestamp: block.timestamp,
+            actor: msg.sender
+        });
+
+        // Increment total unique assets counter
+        _totalAssets++;
+
+        emit TokenMinted(tokenId, to, uri);
+    }
+
+    /**
+     * @notice Mints a single token with explicit owner specification
+     * @param to Recipient address
+     * @param owner_ Token owner for record
+     * @param uri Token URI
+     * @param content Encoded content data
+     * @return tokenId The minted token ID
+     */
+    function mintWithOwner(
+        address to,
+        address owner_,
+        string calldata uri,
+        bytes calldata content
+    )
+        external
+        onlyOrchestrator
+        whenNotPaused
+        nonReentrant
+        returns (uint256 tokenId)
+    {
+        tokenId = _nextTokenId();
+
+        _validateContent(content);
+        _mint(to, 1);
+
+        _tokenURIs[tokenId] = uri;
+        _tokenContents[tokenId] = content;
+
+        _revisions[tokenId] = Types.RevisionRecord({
+            previousTokenId: 0,
+            originTokenId: tokenId,
+            version: 1, // Origin is version 1
+            reasonHash: bytes32(0),
+            timestamp: block.timestamp,
+            actor: owner_ // Use explicit owner as actor
+        });
+
+        // Increment total unique assets counter
+        _totalAssets++;
+
+        emit TokenMinted(tokenId, to, uri);
+    }
+
+    /**
+     * @notice Batch mints tokens with URIs and contents
+     * @param to Recipient address (same for all tokens in batch)
+     * @param uris Array of token URIs
+     * @param contents Array of encoded content data
+     * @return startTokenId The first token ID in the batch
+     */
+    function batchMint(
+        address to,
+        string[] calldata uris,
+        bytes[] calldata contents
+    )
+        external
+        onlyOrchestrator
+        whenNotPaused
+        nonReentrant
+        returns (uint256 startTokenId)
+    {
+        uint256 quantity = uris.length;
+
+        if (quantity != contents.length) {
+            revert Errors.ArrayLengthMismatch();
+        }
+        if (quantity == 0) {
+            revert Errors.BatchMintFailed();
+        }
+
+        startTokenId = _nextTokenId();
+
+        // Validate all content first
+        for (uint256 i = 0; i < quantity; i++) {
+            _validateContent(contents[i]);
+        }
+
+        // Batch mint all tokens
+        _mint(to, quantity);
+
+        // Store URIs, contents, and create revision records
+        for (uint256 i = 0; i < quantity; i++) {
+            uint256 tokenId = startTokenId + i;
+            _tokenURIs[tokenId] = uris[i];
+            _tokenContents[tokenId] = contents[i];
+
+            _revisions[tokenId] = Types.RevisionRecord({
+                previousTokenId: 0,
+                originTokenId: tokenId,
+                version: 1, // Origin is version 1
+                reasonHash: bytes32(0),
+                timestamp: block.timestamp,
+                actor: msg.sender
+            });
+
+            emit TokenMinted(tokenId, to, uris[i]);
+        }
+
+        // Increment total unique assets counter by batch size
+        _totalAssets += quantity;
+
+        emit BatchMinted(startTokenId, quantity, to);
+    }
+
+    // ============ Revision Functions ============
+
+    /**
+     * @notice Creates a new revision of an existing token (protocol-enforced)
+     * @param parentTokenId The token being revised (must be latest version)
+     * @param uri New token URI
+     * @param content New encoded content
+     * @param reason Human-readable reason (stored as hash, emitted in full)
+     * @return newTokenId The newly minted revision token
+     */
+    function revise(
+        uint256 parentTokenId,
+        string calldata uri,
+        bytes calldata content,
+        string calldata reason
+    )
+        external
+        onlyOrchestrator
+        whenNotPaused
+        nonReentrant
+        returns (uint256 newTokenId)
+    {
+        newTokenId = _revise(parentTokenId, uri, content, reason);
+    }
+
+    /**
+     * @dev Internal revision function - NOT virtual (protocol-enforced, cannot be overridden)
+     */
+    function _revise(
+        uint256 parentTokenId,
+        string calldata uri,
+        bytes calldata content,
+        string calldata reason
+    ) internal onlyLatestVersion(parentTokenId) returns (uint256 newTokenId) {
+        // Note: _exists check is now in onlyLatestVersion modifier
+
+        _validateContent(content);
+
+        newTokenId = _nextTokenId();
+
+        // Mint new revision token to same owner as parent
+        address parentOwner = ownerOf(parentTokenId);
+        _mint(parentOwner, 1);
+
+        // Store new token data
+        _tokenURIs[newTokenId] = uri;
+        _tokenContents[newTokenId] = content;
+
+        // Find origin token (root of chain)
+        uint256 originId = _revisions[parentTokenId].originTokenId;
+        if (originId == 0) {
+            originId = parentTokenId;
+        }
+
+        // Get parent version and increment
+        uint256 newVersion = _revisions[parentTokenId].version + 1;
+
+        // Create revision record with links (reason stored as hash for gas efficiency)
+        _revisions[newTokenId] = Types.RevisionRecord({
+            previousTokenId: parentTokenId,
+            originTokenId: originId,
+            version: newVersion,
+            reasonHash: keccak256(bytes(reason)),
+            timestamp: block.timestamp,
+            actor: msg.sender
+        });
+
+        // Update parent's child (single child for linear chain)
+        _childToken[parentTokenId] = newTokenId;
+
+        // Emit full reason for off-chain indexing
+        emit TokenRevised(newTokenId, parentTokenId, originId, reason);
+    }
+
+    // ============ Query Functions ============
+
+    /**
+     * @notice Returns the token URI
+     * @param tokenId Token to query
+     */
+    function tokenURI(
+        uint256 tokenId
+    ) public view virtual override returns (string memory) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _tokenURIs[tokenId];
+    }
+
+    /**
+     * @notice Returns the raw encoded content for a token
+     * @param tokenId Token to query
+     */
+    function tokenContent(
+        uint256 tokenId
+    ) external view returns (bytes memory) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _tokenContents[tokenId];
+    }
+
+    /**
+     * @notice Returns the revision record for a token
+     * @param tokenId Token to query
+     */
+    function getRevisionRecord(
+        uint256 tokenId
+    ) external view returns (Types.RevisionRecord memory) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _revisions[tokenId];
+    }
+
+    /**
+     * @notice Returns the full revision chain from origin to the given token
+     * @param tokenId Token to query (any token in the chain)
+     * @return chain Array of token IDs from origin to this token
+     */
+    function getRevisionChain(
+        uint256 tokenId
+    ) external view returns (uint256[] memory chain) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+
+        // First, count the chain length
+        uint256 length = 1;
+        uint256 current = tokenId;
+        while (_revisions[current].previousTokenId != 0) {
+            current = _revisions[current].previousTokenId;
+            length++;
+        }
+
+        // Build the chain array (origin first)
+        chain = new uint256[](length);
+        current = tokenId;
+        for (uint256 i = length; i > 0; i--) {
+            chain[i - 1] = current;
+            current = _revisions[current].previousTokenId;
+        }
+    }
+
+    /**
+     * @notice Returns the latest version in a revision chain
+     * @param originTokenId The origin token of the chain
+     * @return latestTokenId The leaf token (latest version)
+     */
+    function getLatestVersion(
+        uint256 originTokenId
+    ) external view returns (uint256 latestTokenId) {
+        if (!_exists(originTokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+
+        latestTokenId = originTokenId;
+        while (_childToken[latestTokenId] != 0) {
+            latestTokenId = _childToken[latestTokenId];
+        }
+    }
+
+    /**
+     * @notice Returns the child token of a given token (0 if none)
+     * @param tokenId Token to query
+     * @return childTokenId The child token ID (0 if latest version)
+     */
+    function getChildToken(
+        uint256 tokenId
+    ) external view returns (uint256 childTokenId) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _childToken[tokenId];
+    }
+
+    /**
+     * @notice Returns the total count of unique digital public assets
+     * @dev Only counts origin tokens (new DPAs), not revisions
+     * @return total The total number of unique DPAs
+     */
+    function getTotalAssets() external view returns (uint256 total) {
+        return _totalAssets;
+    }
+
+    /**
+     * @notice Checks if a token is the latest version in its chain
+     * @param tokenId Token to check
+     * @return isLatest True if the token has no child
+     */
+    function isLatestVersion(
+        uint256 tokenId
+    ) public view returns (bool isLatest) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _childToken[tokenId] == 0;
+    }
+
+    /**
+     * @notice Returns the origin token ID for any token in a revision chain
+     * @param tokenId Token to query (can be any token in the chain)
+     * @return originTokenId The root/origin token of the chain
+     */
+    function getOriginToken(
+        uint256 tokenId
+    ) external view returns (uint256 originTokenId) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        originTokenId = _revisions[tokenId].originTokenId;
+        if (originTokenId == 0) {
+            originTokenId = tokenId;
+        }
+    }
+
+    /**
+     * @notice Returns the version number of a token
+     * @param tokenId Token to query
+     * @return version The version number (1 for origin, increments on each revision)
+     */
+    function getVersion(
+        uint256 tokenId
+    ) external view returns (uint256 version) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _revisions[tokenId].version;
+    }
+
+    // ============ Linked DPA Functions ============
+
+    /**
+     * @notice Links an external DPA contract to a token with a unique name
+     * @param tokenId Token to add the link to
+     * @param name Unique name for this link (per token, cannot be empty)
+     * @param dpaContract Address of the DPA contract to link (must be a contract, not self)
+     */
+    function linkDPA(
+        uint256 tokenId,
+        string calldata name,
+        address dpaContract
+    ) external onlyOrchestrator whenNotPaused nonReentrant {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        if (dpaContract == address(0)) {
+            revert Errors.ZeroAddress();
+        }
+
+        // Security: Validate name is not empty
+        if (bytes(name).length == 0) {
+            revert Errors.EmptyLinkName();
+        }
+
+        // Security: Cannot link to self
+        if (dpaContract == address(this)) {
+            revert Errors.SelfLink();
+        }
+
+        // Security: Must be a contract, not an EOA
+        if (dpaContract.code.length == 0) {
+            revert Errors.NotAContract();
+        }
+
+        // Security: Must implement IDPA interface (ERC-165 check)
+        try
+            IERC165(dpaContract).supportsInterface(type(IDPA).interfaceId)
+        returns (bool supported) {
+            if (!supported) {
+                revert Errors.NotADPAContract();
+            }
+        } catch {
+            revert Errors.NotADPAContract();
+        }
+
+        bytes32 nameHash = keccak256(bytes(name));
+
+        // Check if name already exists for this token
+        if (_linkedDPAs[tokenId][nameHash] != address(0)) {
+            revert Errors.DuplicateLinkName();
+        }
+
+        // Store the link
+        _linkedDPAs[tokenId][nameHash] = dpaContract;
+        _linkedDPANames[tokenId].push(nameHash);
+
+        emit DPALinked(tokenId, nameHash, dpaContract, name);
+    }
+
+    /**
+     * @notice Removes a linked DPA contract by name
+     * @param tokenId Token to remove the link from
+     * @param name Name of the link to remove
+     */
+    function unlinkDPA(
+        uint256 tokenId,
+        string calldata name
+    ) external onlyOrchestrator whenNotPaused nonReentrant {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+
+        bytes32 nameHash = keccak256(bytes(name));
+        address dpaContract = _linkedDPAs[tokenId][nameHash];
+
+        if (dpaContract == address(0)) {
+            revert Errors.LinkNotFound();
+        }
+
+        // Remove from mapping
+        delete _linkedDPAs[tokenId][nameHash];
+
+        // Remove from names array (swap and pop for gas efficiency)
+        bytes32[] storage names = _linkedDPANames[tokenId];
+        for (uint256 i = 0; i < names.length; i++) {
+            if (names[i] == nameHash) {
+                names[i] = names[names.length - 1];
+                names.pop();
+                break;
+            }
+        }
+
+        emit DPAUnlinked(tokenId, nameHash, dpaContract);
+    }
+
+    /**
+     * @notice Returns the linked DPA contract address by name
+     * @param tokenId Token to query
+     * @param name Name of the link
+     * @return dpaContract The linked DPA contract address (zero if not found)
+     */
+    function getLinkedDPA(
+        uint256 tokenId,
+        string calldata name
+    ) external view returns (address dpaContract) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        bytes32 nameHash = keccak256(bytes(name));
+        return _linkedDPAs[tokenId][nameHash];
+    }
+
+    /**
+     * @notice Returns all link name hashes for a token
+     * @param tokenId Token to query
+     * @return nameHashes Array of name hashes
+     */
+    function getLinkedDPANameHashes(
+        uint256 tokenId
+    ) external view returns (bytes32[] memory nameHashes) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _linkedDPANames[tokenId];
+    }
+
+    /**
+     * @notice Returns the number of linked DPAs for a token
+     * @param tokenId Token to query
+     * @return count The number of linked DPAs
+     */
+    function getLinkedDPACount(
+        uint256 tokenId
+    ) external view returns (uint256 count) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _linkedDPANames[tokenId].length;
+    }
+
+    /**
+     * @notice Checks if a token has any linked DPAs
+     * @param tokenId Token to check
+     * @return hasLinks True if the token has linked DPAs
+     */
+    function hasLinkedDPAs(
+        uint256 tokenId
+    ) external view returns (bool hasLinks) {
+        if (!_exists(tokenId)) {
+            revert Errors.InvalidTokenId();
+        }
+        return _linkedDPANames[tokenId].length > 0;
+    }
+
+    // ============ Internal Functions ============
+
+    /**
+     * @dev Validates encoded content - override in derived contracts
+     * @param content The encoded content to validate
+     */
+    function _validateContent(bytes calldata content) internal view virtual {
+        // Default: no validation. Override for specific validation logic.
+    }
+
+    /**
+     * @dev Override to start token IDs at 1 instead of 0
+     */
+    function _startTokenId() internal view virtual override returns (uint256) {
+        return 1;
+    }
+
+    /**
+     * @dev Override to prevent burning - DPA tokens are immutable public records
+     */
+    function _beforeTokenTransfers(
+        address from,
+        address to,
+        uint256 startTokenId,
+        uint256 quantity
+    ) internal virtual override {
+        super._beforeTokenTransfers(from, to, startTokenId, quantity);
+
+        // Prevent burning (to == address(0) and from != address(0))
+        if (to == address(0) && from != address(0)) {
+            revert Errors.BurnDisabled();
+        }
+    }
+
+    /**
+     * @dev Override to support ERC-165 interface detection for IDPA
+     */
+    function supportsInterface(
+        bytes4 interfaceId
+    ) public view virtual override returns (bool) {
+        return
+            interfaceId == type(IDPA).interfaceId ||
+            super.supportsInterface(interfaceId);
+    }
+}