Documentation

/**
 * @notice Mint a new BVGS NFT and deposit ETH.
 * @param to The address that will receive the newly minted BVGS NFT.
 * @param bvgsPublicKey The public key used for off-chain signature verification.
 * @param referenceId An external reference ID for off-chain tracking of this deposit.
 * 
 * Requirements:
 * - `to` must not be the zero address.
 * - `bvgsPublicKey` must not be the zero address.
 * - `msg.value` > 0 to deposit ETH.
 */
function bagETH(
    address to,
    address bvgsPublicKey,
    bytes32 referenceId
) external payable nonReentrant {
    if (to == address(0))            revert ZeroAddress();
    if (bvgsPublicKey == address(0)) revert ZeroKey();

    uint256 tokenId = _nextId++; 

    if (to.code.length == 0) {       
        _mint(to, tokenId);
    } else {                          
        _safeMint(to, tokenId);
    }

    emit Locked(tokenId);

    initialize(tokenId, bvgsPublicKey);
    _depositETH(tokenId, msg.value);

    emit Bagged(tokenId, referenceId);
}

/**
 * @notice Always returns true for existing BVGS NFTs (soul‐bound).
 * @param tokenId The ID of the BVGS NFT.
 * @return Always true.
 * @dev Reverts if token does not exist.
 */
function locked(uint256 tokenId) external view override returns (bool) {
    if (!_exists(tokenId)) revert NonexistentToken();
    return true;
}

/// Disable any transfer—soul‐bound enforcement.
function _transfer(address, address, uint256) internal pure override {
    revert TransfersDisabled();
}

function supportsInterface(bytes4 interfaceId)
    public view override(ERC721)
    returns (bool)
{
    if (interfaceId == 0xb45a3c0e) return true; // IERC5192
    return super.supportsInterface(interfaceId);
}

/**
 * @notice Returns the metadata URI for a BVGS NFT.
 * @param tokenId The ID of the token to query.
 * @return The custom URI if set; otherwise the default URI.
 * @dev Reverts if neither custom nor default URI is available.
 */
function tokenURI(uint256 tokenId)
    public view override(ERC721)
    returns (string memory)
{
    if (!_exists(tokenId)) revert NonexistentToken();
    string memory custom = _tokenMetadataURIs[tokenId];
    if (bytes(custom).length > 0) return custom;
    if (bytes(_defaultMetadataURI).length > 0) return _defaultMetadataURI;
    revert NoURI();
}

/*
* @notice Deposit ETH into a BVGS NFT.
* @param tokenId    The ID of the BVGS NFT.
* @param referenceId External reference ID for off-chain tracking.
*
* Requirements:
* - `tokenId` must exist and caller must be its owner.
* - `msg.value` must be > 0.
*/
function depositETH(uint256 tokenId, bytes32 referenceId)
    external payable nonReentrant
{
    _requireOwnsBag(tokenId);
    if (msg.value == 0) revert ZeroAmount();

    _depositETH(tokenId, msg.value);
    emit Deposited(tokenId, referenceId);
}

/// @notice Deposit ERC-20 tokens into a bag.
/// @param tokenId      The ID of the BVGS NFT.
/// @param tokenAddress The ERC-20 token contract address.
/// @param amount       The amount of tokens to deposit.
/// @param referenceId  External reference ID for off-chain tracking.
///
/// Requirements:
/// - `tokenId` must exist and caller must be its owner.
/// - `tokenAddress` must not be the zero address.
/// - `amount` must be greater than zero.
function depositERC20(
    uint256 tokenId,
    address tokenAddress,
    uint256 amount,
    bytes32 referenceId
) external nonReentrant {
    _requireOwnsBag(tokenId);
    if (tokenAddress == address(0)) revert ZeroAddress();
    if (amount == 0)           revert ZeroAmount();
    _depositERC20(tokenId, tokenAddress, amount, referenceId);
}

/// @notice Batch-deposit ETH, multiple ERC-20s, and multiple ERC-721s in one call.
/// @param tokenId         The ID of the BVGS NFT.
/// @param amountETH       The ETH amount to deposit.
/// @param tokenAddresses  The list of ERC-20 token addresses.
/// @param tokenAmounts    The corresponding ERC-20 token amounts.
/// @param nftContracts    The list of ERC-721 contract addresses.
/// @param nftTokenIds     The corresponding ERC-721 token IDs.
/// @param referenceId     External reference ID for off-chain tracking.
///
/// Requirements:
/// - `tokenId` must exist and caller must be its owner.
/// - `tokenAddresses.length` must equal `tokenAmounts.length`.
/// - `nftContracts.length` must equal `nftTokenIds.length`.
/// - `msg.value` must equal `amountETH`.
function batchDeposit(
    uint256 tokenId,
    uint256 amountETH,
    address[] calldata tokenAddresses,
    uint256[] calldata tokenAmounts,
    address[] calldata nftContracts,
    uint256[] calldata nftTokenIds,
    bytes32 referenceId
) external payable nonReentrant {
    _requireOwnsBag(tokenId);
    if (msg.value != amountETH) revert ETHMismatch();
    _batchDeposit(tokenId, amountETH, tokenAddresses, tokenAmounts, nftContracts, nftTokenIds, referenceId);
}

function _depositETH(uint256 tokenId, uint256 amountETH) internal {
    if (amountETH == 0) return;
    _baggedETH[tokenId] += amountETH;
}

function _depositERC20(
    uint256 tokenId,
    address tokenAddress,
    uint256 amount
) internal {
    IERC20 t = IERC20(tokenAddress);

    // Register token if new
    if (!_erc20Known[tokenId][tokenAddress]) {
        _erc20TokenAddresses[tokenId].push(tokenAddress);
        _erc20Known[tokenId][tokenAddress] = true;
    }

    // Pull tokens
    uint256 beforeBal = t.balanceOf(address(this));
    t.safeTransferFrom(msg.sender, address(this), amount);
    uint256 afterBal  = t.balanceOf(address(this));

    // Book the delta
    // Ensures assets booked match assets received regardless of input
    uint256 delta = afterBal > beforeBal ? afterBal - beforeBal : 0;
    
    if (delta == 0) revert ZeroAmount();
    
    _erc20Balances[tokenId][tokenAddress] += delta;
}

/*
* @notice Withdraw ETH from a BVGS NFT, authorized via EIP-712 signature.
* @param tokenId         The ID of the BVGS NFT.
* @param messageHash     The EIP-712 digest that was signed.
* @param signature       The EIP-712 signature by the active BVGS key.
* @param amountETH       The amount of ETH to withdraw.
* @param recipient       The address receiving the ETH.
* @param referenceId     External reference ID for off-chain tracking.
* @param signatureExpiry UNIX timestamp after which the signature is invalid.
*
* Requirements:
* - `tokenId` must exist and caller must be its owner.
* - `recipient` must not be the zero address.
* - `block.timestamp` must be ≤ `signatureExpiry`.
* - BVGS NFT must have ≥ `amountETH` ETH
*/
function unbagETH(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    uint256 amountETH,
    address recipient,
    bytes32 referenceId,
    uint256 signatureExpiry
) external nonReentrant {
    _requireOwnsBag(tokenId);
    if (recipient == address(0)) revert ZeroAddress();
    if (block.timestamp > signatureExpiry)  revert SignatureExpired();

    // 1) Verify
    bytes memory data = abi.encode(tokenId, amountETH, recipient, referenceId, msg.sender, signatureExpiry);
    verifySignature(tokenId, messageHash, signature, address(0), OperationType.UNBAG_ETH, data);

    // 2) Effects
    uint256 currentBal = _baggedETH[tokenId];
    if (currentBal < amountETH) revert NoETHBagged();
    _baggedETH[tokenId] = currentBal - amountETH;

    // 3) Interaction
    (bool success, ) = payable(recipient).call{value: amountETH}("");
    if (!success) revert EthTransferFailed();

    emit Unbagged(tokenId, referenceId);
}

/*
* @notice Returns the full contents of a BVGS NFT: ETH, ERC-20 balances, and ERC-721s.
* @param tokenId The ID of the BVGS NFT.
* @return bagETH      The ETH amount held.
* @return erc20Tokens Array of (tokenAddress, balance) for each ERC-20.
* @return nfts        Array of BaggedNFT structs representing each ERC-721.
*
* Requirements:
* - `tokenId` must exist and caller must be its owner.
*/
struct BaggedERC20 { address tokenAddress; uint256 balance; }

function getFullBag(uint256 tokenId)
    external view
    returns (
        uint256 bagETH,
        BaggedERC20[] memory erc20Tokens,
        BaggedNFT[]  memory nftContracts
    )
{
    _requireExists(tokenId);
    if (_erc721.ownerOf(tokenId) != msg.sender) revert NotOwner();

    bagETH = _baggedETH[tokenId];

    // ERC-20s
    address[] storage tokenAddresses = _erc20TokenAddresses[tokenId];
    erc20Tokens = new BaggedERC20[](tokenAddresses.length);
    for (uint256 i; i < tokenAddresses.length; ) {
        erc20Tokens[i] = BaggedERC20({
            tokenAddress: tokenAddresses[i],
            balance: _erc20Balances[tokenId][tokenAddresses[i]]
        });
        unchecked { ++i; }
    }

    // ERC-721s
    // ... counts and populates nftContracts array ...
}

/**
 * @notice Verifies an EIP‑712 signature for a specific operation.
 * @param tokenId The ID of the BVGS NFT.
 * @param messageHash The EIP‑712 digest that was signed.
 * @param signature The BVGS NFT private key signature to verify.
 * @param newBvgsPublicKey The new BVGS NFT public key (if rotating the key).
 * @param opType The operation being authorized.
 * @param data Encoded parameters for the specific operation.
 *
 * Requirements:
 * - The EIP-712 message digest must match `messageHash`.
 * - The signature must be valid for the current, active BVGS NFT public key.
 * - On successful verification, the nonce increments.
 * - If `opType` is `ROTATE_KEY`, the BVGS NFT public key is updated to `newBvgsPublicKey`.
 */
function verifySignature(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    address newBvgsPublicKey,
    OperationType opType,
    bytes memory data
) internal {
    TokenAuth storage tokenAuth = _tokenAuth[tokenId];

    // Compute the hash of the operation data.
    bytes32 dataHash = keccak256(data);
    bytes32 structHash = keccak256(
        abi.encode(
            OPERATION_TYPEHASH,
            tokenId,
            tokenAuth.nonce,
            uint8(opType),
            dataHash
        )
    );
    bytes32 expectedHash = _hashTypedDataV4(structHash);

    if (messageHash != expectedHash) {
        revert InvalidMessageHash();
    }

    address signer = expectedHash.recover(signature);
    if (signer != tokenAuth.activeBvgsPublicKey) {
        revert InvalidSignature();
    }

    // Increment nonce after successful verification.
    tokenAuth.nonce++;

    // If rotating the key, update the active BVGS public key.
    if (opType == OperationType.ROTATE_KEY && newBvgsPublicKey != address(0)) {
        if (newBvgsPublicKey == address(0)) revert ZeroKey();
        tokenAuth.activeBvgsPublicKey = newBvgsPublicKey;
    }
}

/**
 * @notice Initializes the BVGS NFT data with a public key and nonce.
 * @dev Intended to be called once upon minting a new BVGS NFT.
 * @param tokenId The ID of the BVGS NFT being initialized.
 * @param bvgsPublicKey The public key that will sign operations for this BVGS NFT.
 */
function initialize(uint256 tokenId, address bvgsPublicKey) internal {
    if (_tokenAuth[tokenId].activeBvgsPublicKey != address(0)) {
        revert AlreadyInitialized();
    }   

    _tokenAuth[tokenId].activeBvgsPublicKey = bvgsPublicKey; 
    _tokenAuth[tokenId].nonce               = 1;            
}

/**
 * @notice Retrieves the current BVGS public key for the given BVGS NFT.
 * @param tokenId The ID of the BVGS NFT.
 * @return The currently active BVGS public key.
 *
 * Requirements:
 * - Caller must be the owner of `tokenId`.
 */
function getActiveBvgsPublicKeyForToken(uint256 tokenId)
    external
    view
    onlyTokenOwner(tokenId)
    returns (address)
{
    return _tokenAuth[tokenId].activeBvgsPublicKey;
}

/**
 * @notice Retrieves the current nonce for the given BVGS NFT.
 * @param tokenId The ID of the BVGS NFT.
 * @return The current nonce used for signature verification.
 *
 * Requirements:
 * - Caller must be the owner of `tokenId`.
 */
function getNonce(uint256 tokenId)
    external
    view
    onlyTokenOwner(tokenId)
    returns (uint256)
{
    return uint256(_tokenAuth[tokenId].nonce); 
}

// Example of EIP-712 domain and types
const domain = {
    name: "BVGS",
    version: "1",
    chainId: 1, // Ethereum mainnet
    verifyingContract: "0x123...789" // BVGS contract address
};

const types = {
    Operation: [
        { name: "tokenId", type: "uint256" },
        { name: "nonce", type: "uint256" },
        { name: "opType", type: "uint8" },
        { name: "dataHash", type: "bytes32" }
    ]
};

const message = {
    tokenId: 123,
    nonce: 42,
    opType: 1, // UNBAG_ETH (note: now at index 1)
    dataHash: "0x123...abc"
};

/*
* @notice Rotate the off-chain authorization key for a BVGS NFT.
* @param tokenId         The ID of the BVGS NFT.
* @param messageHash     The EIP-712 digest that was signed.
* @param signature       The EIP-712 signature by the active BVGS key.
* @param newPublicKey    The new authorized BVGS public key.
* @param referenceId     External reference ID for off-chain tracking.
* @param signatureExpiry UNIX timestamp after which the signature is invalid.
*
* Requirements:
* - `tokenId` must exist and caller must be its owner.
* - `block.timestamp` must be ≤ `signatureExpiry`.
*/
function rotateBvgsKey(
    uint256 tokenId,
    bytes32 messageHash,
    bytes memory signature,
    address newPublicKey,
    bytes32 referenceId,
    uint256 signatureExpiry
) external nonReentrant {
    _requireOwnsBag(tokenId);
    if (block.timestamp > signatureExpiry) revert SignatureExpired();

    bytes memory data = abi.encode(
        tokenId, newPublicKey, referenceId, msg.sender, signatureExpiry
    );
    verifySignature(
        tokenId, messageHash, signature,
        newPublicKey, OperationType.ROTATE_KEY, data
    );
    emit KeyRotated(tokenId, referenceId);
}