Add 1155 randomly assigned extension. Fixes #17

Author: jwahdatehagh

.changeset/salty-colts-arrive.md

@@ -0,0 +1,5 @@
+---
+"@1001-digital/erc721-extensions": patch
+---
+
+Add 1155 randomly assigned extension (fixes #17)

README.md

@@ -1,6 +1,6 @@
 # ERC721 Contract Extensions
 
-A set of composable extensions for the [OpenZeppelin](https://openzeppelin.com/) ERC721 base contracts.
+A set of composable extensions for the [OpenZeppelin](https://openzeppelin.com/) ERC721 and ERC1155 base contracts.
 
 > **v0.1.0 Breaking Change**: This version targets OpenZeppelin 5.x and Solidity ^0.8.20. It is not backward compatible with OZ 4.x consumers. All `require` strings have been replaced with custom errors, `Counters` has been removed, and `_mint`/`_transfer` overrides have been replaced with the OZ 5.x `_update` hook.
 
@@ -351,6 +351,30 @@ contract ExpandableCollection is WithAdditionalMints {
 
 After the initial collection is live, the owner can call `addToken(cid)`, `addTokens(cid, count)`, `mintAdditionalToken(cid, to)`, or `mintAdditionalTokens(cid, count, to)` to increase supply and point metadata to the updated IPFS directory.
 
+### `RandomlyAssigned1155.sol`
+
+Randomly assign ERC1155 token IDs from a set of token types, each with its own supply. On each mint, a token type is selected at random weighted by its remaining supply.
+
+```solidity
+contract RandomPack is ERC1155, RandomlyAssigned1155 {
+  constructor()
+    ERC1155("")
+    RandomlyAssigned1155(
+      new uint256[](3) /* [1, 2, 3] */,
+      new uint256[](3) /* [10000, 10000, 10000] */
+    )
+  {}
+
+  function mint(uint256 amount) external ensureAvailabilityFor(amount) {
+    for (uint256 i = 0; i < amount; i++) {
+      _mint(msg.sender, nextToken(), 1, "");
+    }
+  }
+}
+```
+
+> Uses the same on-chain randomness approach as `RandomlyAssigned`. The weighted selection loop is negligible for typical ERC1155 collections (dozens of token types).
+
 ## Local Development
 
 This project uses [Hardhat](https://hardhat.org/) and [pnpm](https://pnpm.io/).

contracts/RandomlyAssigned1155.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/// @author 1001.digital
+/// @title Randomly assign ERC1155 token IDs from a set of token types with individual supplies.
+abstract contract RandomlyAssigned1155 {
+    /// @dev Thrown when no tokens remain to be minted.
+    error NoTokensAvailable();
+    /// @dev Thrown when the requested mint amount exceeds available supply.
+    error RequestedTokensNotAvailable();
+    /// @dev Thrown when token ID and supply array lengths don't match.
+    error TokenIdSupplyMismatch();
+
+    // The available token IDs
+    uint256[] private _tokenIds;
+
+    // Remaining supply per token ID
+    mapping(uint256 => uint256) private _remaining;
+
+    // Total remaining across all token IDs
+    uint256 private _totalRemaining;
+
+    /// Instanciate the contract
+    /// @param tokenIds_ the token IDs available for minting
+    /// @param supplies_ the max supply for each token ID
+    constructor(uint256[] memory tokenIds_, uint256[] memory supplies_) {
+        if (tokenIds_.length != supplies_.length) revert TokenIdSupplyMismatch();
+
+        for (uint256 i = 0; i < tokenIds_.length; i++) {
+            _tokenIds.push(tokenIds_[i]);
+            _remaining[tokenIds_[i]] = supplies_[i];
+            _totalRemaining += supplies_[i];
+        }
+    }
+
+    /// @dev Get the total remaining token count across all token types
+    /// @return the available token count
+    function availableTokenCount() public view returns (uint256) {
+        return _totalRemaining;
+    }
+
+    /// @dev Get the remaining supply for a specific token ID
+    /// @return the remaining supply
+    function availableSupplyOf(uint256 tokenId) public view returns (uint256) {
+        return _remaining[tokenId];
+    }
+
+    /// Get the next token ID
+    /// @dev Randomly selects a token ID weighted by remaining supply.
+    /// @return the selected token ID
+    function nextToken() internal virtual returns (uint256) {
+        if (_totalRemaining == 0) revert NoTokensAvailable();
+
+        uint256 random = uint256(keccak256(
+            abi.encodePacked(
+                msg.sender,
+                block.coinbase,
+                block.prevrandao,
+                block.gaslimit,
+                block.timestamp
+            )
+        )) % _totalRemaining;
+
+        uint256 cumulative = 0;
+        uint256 selectedId;
+        for (uint256 i = 0; i < _tokenIds.length; i++) {
+            cumulative += _remaining[_tokenIds[i]];
+            if (random < cumulative) {
+                selectedId = _tokenIds[i];
+                break;
+            }
+        }
+
+        _remaining[selectedId]--;
+        _totalRemaining--;
+
+        return selectedId;
+    }
+
+    /// @dev Check whether another token is still available
+    modifier ensureAvailability() {
+        if (_totalRemaining == 0) revert NoTokensAvailable();
+        _;
+    }
+
+    /// @param amount Check whether number of tokens are still available
+    /// @dev Check whether tokens are still available
+    modifier ensureAvailabilityFor(uint256 amount) {
+        if (_totalRemaining < amount) revert RequestedTokensNotAvailable();
+        _;
+    }
+}

contracts/examples/RandomlyAssigned1155Example.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
+
+import "./../RandomlyAssigned1155.sol";
+
+contract RandomlyAssigned1155Example is ERC1155, RandomlyAssigned1155 {
+    constructor(
+        uint256[] memory tokenIds,
+        uint256[] memory supplies
+    )
+        ERC1155("")
+        RandomlyAssigned1155(tokenIds, supplies)
+    {}
+
+    function mint(uint256 amount) external
+        ensureAvailabilityFor(amount)
+    {
+        for (uint256 i = 0; i < amount; i++) {
+            _mint(msg.sender, nextToken(), 1, "");
+        }
+    }
+}

test/RandomlyAssigned1155.ts

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { network } from "hardhat";
+import { parseEventLogs } from "viem";
+
+describe("RandomlyAssigned1155", async function () {
+  const { viem } = await network.connect();
+  const publicClient = await viem.getPublicClient();
+  const [, buyerWallet] = await viem.getWalletClients();
+
+  const tokenIds = [1n, 2n, 3n];
+  const supplies = [5n, 5n, 5n];
+
+  it("Deployment should set the correct available supply", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    assert.equal(await contract.read.availableTokenCount(), 15n);
+  });
+
+  it("Reports available supply per token ID", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    assert.equal(await contract.read.availableSupplyOf([1n]), 5n);
+    assert.equal(await contract.read.availableSupplyOf([2n]), 5n);
+    assert.equal(await contract.read.availableSupplyOf([3n]), 5n);
+  });
+
+  it("Mints all tokens across all types", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    await contract.write.mint([15n], { account: buyerWallet.account });
+
+    for (const id of tokenIds) {
+      const balance = await contract.read.balanceOf([buyerWallet.account.address, id]);
+      assert.equal(balance, 5n);
+    }
+
+    assert.equal(await contract.read.availableTokenCount(), 0n);
+  });
+
+  it("Distributes tokens across multiple types", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+    const mintedIds: number[] = [];
+
+    for (let i = 0; i < 15; i++) {
+      const hash = await contract.write.mint([1n], { account: buyerWallet.account });
+      const receipt = await publicClient.getTransactionReceipt({ hash });
+      const logs = parseEventLogs({
+        abi: contract.abi,
+        logs: receipt.logs,
+        eventName: "TransferSingle",
+      });
+      mintedIds.push(Number(logs[0].args.id));
+    }
+
+    const uniqueTypes = new Set(mintedIds);
+    assert.equal(uniqueTypes.size, 3, "Expected all three token types to be minted");
+  });
+
+  it("Decreases available supply per token type on mint", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    await contract.write.mint([1n], { account: buyerWallet.account });
+
+    const total = await contract.read.availableTokenCount();
+    assert.equal(total, 14n);
+  });
+
+  it("Fails when trying to mint more than available", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    await assert.rejects(
+      contract.write.mint([16n], { account: buyerWallet.account }),
+      /RequestedTokensNotAvailable/,
+    );
+  });
+
+  it("Fails when all tokens are minted", async function () {
+    const contract = await viem.deployContract("RandomlyAssigned1155Example", [tokenIds, supplies]);
+
+    await contract.write.mint([15n], { account: buyerWallet.account });
+
+    await assert.rejects(
+      contract.write.mint([1n], { account: buyerWallet.account }),
+      /RequestedTokensNotAvailable/,
+    );
+  });
+});