feat: Base ERC-1155 wrapper + bridge spec for Regen credits (draft)

[brawlaphant]

Builds toward Base specifically, per the operator's own 2025 forum design (Option B: ERC Wrapper + Bridging Layer — forum.regen.network/t/erc-compatible-wrapping-fractionalization-of-regen-credits-for-defi-integration/463).

What this is

• RFC-BASE-ERC-WRAPPER-BRIDGE.md: lock Regen credits → classify into Klima-aligned carbon-class baskets → mint ICS-20 baskets on Regen Ledger → bridge via Axelar to Base → unwrap as ERC-1155. Covers basket model, ICS-20 mechanics, Axelar path, Klima pool registration, risk analysis, 3-phase rollout, open questions.
• BaseRegenCreditBasket.sol: real ERC-1155 wrapper contract (not a stub) — depositAndMint (ERC-20→ERC-1155), withdraw, markRetired (immutable lock), per-token metadata (credit class/vintage/region/IPFS URI), role-gated access control (MINTER/PAUSER/METADATA_UPDATER). Compiles clean via Hardhat, full test scaffold included (8 suites).

Why regen-compute, not agentic-tokenomics

This repo already owns cross-chain ops (Osmosis swaps, ecoBridge). agentic-tokenomics owns CosmWasm governance contracts — this is EVM-side bridging infra, so it belongs here.

Status

draft — agent-built, operator-reviewed before this PR. No mainnet deployment, no capital movement. Open questions (ICS-20 denom registration, metadata storage approach, ERC-1155 vs ERC-20 basket tradeoff) are tracked in the RFC; operator approval is required before any Phase 3 mainnet step.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces the Base ERC-1155 Wrapper and Bridge for Regen Ecocredits, including an architectural RFC, the BaseRegenCreditBasket Solidity contract, mock tokens, Hardhat configuration, and unit tests. The contract wraps bridged ICS-20 tokens into fungible ERC-1155 credit-class baskets on Coinbase Base. Feedback on the implementation highlights a critical bug where duplicate token IDs are minted for the same basket type instead of reusing existing ones, which breaks fungibility. Other recommendations include removing the unused baseURI variable, emitting events on configuration updates, implementing a metadata update function for the defined METADATA_UPDATER_ROLE, and adding test coverage for duplicate deposits.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Critical Bug: Duplicate Token IDs for Same Basket Type

Currently, depositAndMint always increments nextTokenId and mints a new token ID, even if a basket with the same basketId (hash of creditClass, vintage, region) already exists. This breaks the fungibility of the basket and leaves subsequent deposits orphaned from the basketIdToTokenId mapping.

Instead, the function should check if a tokenId already exists for the given basketId. If it does, it should reuse that tokenId (after verifying the basket is not retired) and increment its total supply.

        // Record basket ID (hash of class + vintage + region for deduplication) 
        bytes32 basketId = keccak256(
            abi.encodePacked(creditClass, vintage, region)
        );

        tokenId = basketIdToTokenId[basketId];
        if (tokenId == 0) {
            tokenId = nextTokenId++;
            basketIdToTokenId[basketId] = tokenId;

            // Store metadata
            basketMetadata[tokenId] = CreditBasketMetadata({
                creditClass: creditClass,
                vintage: vintage,
                region: region,
                metadataUri: metadataUri,
                minter: msg.sender,
                createdAt: block.timestamp,
                isRetired: false,
                retirementReason: ""
            });
        } else {
            require(!basketMetadata[tokenId].isRetired, "Cannot deposit into a retired basket");
        }

        // Mint ERC-1155 tokens to the caller
        _mint(msg.sender, tokenId, amount, "");

        // Track total supply
        totalSupplyPerToken[tokenId] += amount;

[gemini-code-assist]

Unused State Variable baseURI

The baseURI state variable is defined and initialized to "ipfs://" but is never used anywhere in the contract. The uri function completely overrides the base ERC1155 implementation and returns basketMetadata[tokenId].metadataUri directly. This unused variable should be removed to clean up the code and save gas.

[gemini-code-assist]

Missing Event for Configuration Updates

Updating critical configuration parameters like the bridged token address should emit an event so that off-chain indexers and clients can track the change. Let's define a BridgedTokenAddressUpdated event here.

    event Withdrawn(
        address indexed withdrawer,
        uint256 indexed tokenId,
        uint256 amount
    );

    /**
     * @notice Emitted when the bridged ERC-20 token address is updated
     */
    event BridgedTokenAddressUpdated(
        address indexed oldAddress,
        address indexed newAddress
    );

[gemini-code-assist]

Unused Role METADATA_UPDATER_ROLE and Missing Metadata Update Function

The role METADATA_UPDATER_ROLE is defined and granted to the deployer in the constructor, but there is no function in the contract that actually uses this role or allows updating the metadata URI.

We should implement an updateMetadataUri function restricted to METADATA_UPDATER_ROLE to allow updating the metadata URI for a token, and emit the standard URI event. We should also emit the BridgedTokenAddressUpdated event in setBridgedTokenAddress.

    function setBridgedTokenAddress(address newAddress) 
        external 
        onlyOwner 
    {
        require(newAddress != address(0), "Invalid address");
        emit BridgedTokenAddressUpdated(address(bridgedBasketToken), newAddress);
        bridgedBasketToken = IERC20(newAddress);
    }

    /**
     * @notice Update the metadata URI for a specific basket
     * @param tokenId ID of the basket to update
     * @param newMetadataUri New metadata URI
     */
    function updateMetadataUri(
        uint256 tokenId,
        string calldata newMetadataUri
    ) external onlyRole(METADATA_UPDATER_ROLE) {
        require(basketMetadata[tokenId].createdAt > 0, "Basket does not exist");
        require(bytes(newMetadataUri).length > 0, "Metadata URI cannot be empty");
        basketMetadata[tokenId].metadataUri = newMetadataUri;
        emit URI(newMetadataUri, tokenId);
    }

[gemini-code-assist]

Missing Test Case for Duplicate Deposits

The test suite currently does not verify the behavior of duplicate deposits for the same basket type. Adding a test case for this ensures that duplicate deposits correctly reuse the same tokenId and update the total supply.

      expect(await mockToken.balanceOf(basket.address)).to.equal(amount);
    });

    it("Should reuse existing tokenId and update supply on duplicate deposit", async function () {
      const amount = ethers.parseEther("100");
      const creditClass = "VCS";
      const vintage = 2020;
      const region = "Africa";
      const metadataUri = "ipfs://QmXxxx";

      await mockToken.connect(user1).approve(basket.address, amount * 2n);

      // First deposit
      await basket.connect(minter).depositAndMint(
        amount,
        creditClass,
        vintage,
        region,
        metadataUri
      );

      // Second deposit with same attributes
      await basket.connect(minter).depositAndMint(
        amount,
        creditClass,
        vintage,
        region,
        metadataUri
      );

      // Verify that only one token ID was created and supply is updated
      expect(await basket.getTokenIdByBasketId(ethers.solidityPackedKeccak256(
        ["string", "uint32", "string"],
        [creditClass, vintage, region]
      ))).to.equal(1);
      expect(await basket.getTotalSupply(1)).to.equal(amount * 2n);
    });