Cairo: Add ERC721Consecutive (#800)

Author: immrsd

.changeset/agile-newt-erc721-consecutive.md

@@ -0,0 +1,5 @@
+---
+'@openzeppelin/wizard-common': patch
+---
+
+Cairo: Add ERC721Consecutive extension.

packages/common/src/ai/descriptions/cairo.ts

@@ -65,6 +65,8 @@ export const cairoERC721Descriptions = {
   uriStorage: 'Allows updating token URIs for individual token IDs.',
   votes:
     'Whether to keep track of individual units for voting in on-chain governance. Voting durations can be expressed as block numbers or timestamps.',
+  consecutive:
+    'Enables gas-efficient batch minting of consecutive token IDs during construction (ERC-2309). The contract owner must call `mint_consecutive` from the constructor to issue the initial batch. Cannot be combined with enumerable.',
 };
 
 export const cairoERC1155Descriptions = {

packages/core/cairo_alpha/CHANGELOG.md

@@ -10,6 +10,7 @@
 - Add ERC1155Supply extension ([#765](https://github.com/OpenZeppelin/contracts-wizard/pull/765))
 - Add ERC721URIStorage extension ([#772](https://github.com/OpenZeppelin/contracts-wizard/pull/772))
 - Add ERC721Wrapper extension ([#764](https://github.com/OpenZeppelin/contracts-wizard/pull/764))
+- Add ERC721Consecutive extension ([#800](https://github.com/OpenZeppelin/contracts-wizard/pull/800))
 - Add ERC20Wrapper extension ([#763](https://github.com/OpenZeppelin/contracts-wizard/pull/763))
 
 - **Breaking changes**:

packages/core/cairo_alpha/src/erc721.ts

@@ -29,6 +29,7 @@ export const defaults: Required<ERC721Options> = {
   wrapper: false,
   uriStorage: false,
   votes: false,
+  consecutive: false,
   royaltyInfo: royaltyInfoDefaults,
   appName: '', // Defaults to empty string, but user must provide a non-empty value if votes are enabled
   appVersion: 'v1',
@@ -53,6 +54,7 @@ export interface ERC721Options extends CommonContractOptions {
   wrapper?: boolean;
   uriStorage?: boolean;
   votes?: boolean;
+  consecutive?: boolean;
   royaltyInfo?: RoyaltyInfoOptions;
   appName?: string;
   appVersion?: string;
@@ -71,6 +73,7 @@ function withDefaults(opts: ERC721Options): Required<ERC721Options> {
     uriStorage: opts.uriStorage ?? defaults.uriStorage,
     royaltyInfo: opts.royaltyInfo ?? defaults.royaltyInfo,
     votes: opts.votes ?? defaults.votes,
+    consecutive: opts.consecutive ?? defaults.consecutive,
     appName: opts.appName ?? defaults.appName,
     appVersion: opts.appVersion ?? defaults.appVersion,
   };
@@ -89,11 +92,20 @@ export function isAccessControlRequired(opts: Partial<ERC721Options>): boolean {
 export function buildERC721(opts: ERC721Options): Contract {
   const allOpts = withDefaults(opts);
 
+  if (allOpts.consecutive && allOpts.enumerable) {
+    throw new OptionsError({
+      consecutive:
+        'Consecutive cannot be combined with Enumerable: batch mints bypass the update hook that Enumerable relies on to track ownership.',
+    });
+  }
+
   const c = new ContractBuilder(allOpts.name, allOpts.macros);
 
   addBase(c, toByteArray(allOpts.name), toByteArray(allOpts.symbol), toByteArray(allOpts.baseUri));
   addERC721Mixin(c);
-  c.addUseClause('openzeppelin_token::erc721', 'ERC721OwnerOfDefaultImpl');
+  if (!allOpts.consecutive) {
+    c.addUseClause('openzeppelin_token::erc721', 'ERC721OwnerOfDefaultImpl');
+  }
 
   if (allOpts.pausable) {
     addPausable(c, allOpts.access);
@@ -111,6 +123,10 @@ export function buildERC721(opts: ERC721Options): Contract {
     addEnumerable(c);
   }
 
+  if (allOpts.consecutive) {
+    addConsecutive(c);
+  }
+
   if (allOpts.wrapper) {
     addWrapper(c);
   }
@@ -151,8 +167,8 @@ function addERC721Mixin(c: ContractBuilder) {
 /* Hooks */
 
 function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
-  const hasBeforeUpdateHook = opts.pausable || opts.enumerable || opts.votes;
-  const hasAfterUpdateHook = opts.uriStorage;
+  const hasBeforeUpdateHook = opts.pausable || opts.enumerable || opts.votes || opts.consecutive;
+  const hasAfterUpdateHook = opts.uriStorage || opts.consecutive;
   const hasCustomHooks = hasBeforeUpdateHook || hasAfterUpdateHook;
   if (hasCustomHooks) {
     const ERC721HooksTrait: BaseImplementedTrait = {
@@ -176,10 +192,10 @@ function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
 }
 
 function addBeforeUpdateHook(c: ContractBuilder, trait: BaseImplementedTrait, opts: Required<ERC721Options>) {
-  if (!opts.pausable && !opts.enumerable && !opts.votes) {
+  if (!opts.pausable && !opts.enumerable && !opts.votes && !opts.consecutive) {
     return;
   }
-  const requiresMutState = opts.enumerable || opts.votes;
+  const requiresMutState = opts.enumerable || opts.votes || opts.consecutive;
   const initStateLine = requiresMutState
     ? 'let mut contract_state = self.get_contract_mut()'
     : 'let contract_state = self.get_contract()';
@@ -210,6 +226,9 @@ function addBeforeUpdateHook(c: ContractBuilder, trait: BaseImplementedTrait, op
     beforeUpdateCode.push('let previous_owner = self._owner_of(token_id);');
     beforeUpdateCode.push('contract_state.votes.transfer_voting_units(previous_owner, to, 1);');
   }
+  if (opts.consecutive) {
+    beforeUpdateCode.push('contract_state.erc721_consecutive.before_update(to, token_id, auth)');
+  }
   c.addFunction(trait, {
     name: 'before_update',
     args: [
@@ -226,14 +245,17 @@ function addBeforeUpdateHook(c: ContractBuilder, trait: BaseImplementedTrait, op
 }
 
 function addAfterUpdateHook(c: ContractBuilder, trait: BaseImplementedTrait, opts: Required<ERC721Options>) {
-  if (!opts.uriStorage) {
+  if (!opts.uriStorage && !opts.consecutive) {
     return;
   }
   const initStateLine = 'let mut contract_state = self.get_contract_mut()';
   const afterUpdateCode = [initStateLine];
   if (opts.uriStorage) {
     afterUpdateCode.push('contract_state.erc721_uri_storage.after_update(to, token_id, auth)');
   }
+  if (opts.consecutive) {
+    afterUpdateCode.push('contract_state.erc721_consecutive.after_update(to, token_id, auth)');
+  }
   c.addFunction(trait, {
     name: 'after_update',
     args: [
@@ -255,6 +277,11 @@ function addEnumerable(c: ContractBuilder) {
   c.addComponent(components.ERC721EnumerableComponent, [], true);
 }
 
+function addConsecutive(c: ContractBuilder) {
+  c.addUseClause('openzeppelin_token::erc721::extensions::erc721_consecutive', 'DefaultConfig');
+  c.addComponent(components.ERC721ConsecutiveComponent, [], false);
+}
+
 function addBurnable(c: ContractBuilder) {
   c.addUseClause('core::num::traits', 'Zero');
   c.addUseClause('starknet', 'get_caller_address');
@@ -370,6 +397,24 @@ const components = defineComponents({
       },
     ],
   },
+  ERC721ConsecutiveComponent: {
+    path: 'openzeppelin_token::erc721::extensions',
+    substorage: {
+      name: 'erc721_consecutive',
+      type: 'ERC721ConsecutiveComponent::Storage',
+    },
+    event: {
+      name: 'ERC721ConsecutiveEvent',
+      type: 'ERC721ConsecutiveComponent::Event',
+    },
+    impls: [
+      {
+        name: 'ERC721ConsecutiveInternalImpl',
+        embed: false,
+        value: 'ERC721ConsecutiveComponent::InternalImpl<ContractState>',
+      },
+    ],
+  },
 });
 
 const functions = defineFunctions({

packages/core/cairo_alpha/src/generate/erc721.ts

@@ -29,6 +29,7 @@ function prepareBlueprint(opts: GeneratorOptions) {
     wrapper: booleans,
     uriStorage: booleans,
     votes: booleans,
+    consecutive: booleans,
     appName: ['MyApp'],
     appVersion: ['v1'],
     pausable: booleans,
@@ -43,5 +44,10 @@ function prepareBlueprint(opts: GeneratorOptions) {
 
 export function* generateERC721Options(opts: GeneratorOptions): Generator<Required<ERC721Options>> {
   const blueprint = prepareBlueprint(opts);
-  yield* generateAlternatives(blueprint);
+  for (const option of generateAlternatives(blueprint)) {
+    // Consecutive batch mints bypass the ERC721Component update hook that Enumerable depends on,
+    // so the combination is forbidden by buildERC721. Skip these to avoid invalid generated sources.
+    if (option.consecutive && option.enumerable) continue;
+    yield option;
+  }
 }

packages/core/cairo_alpha/src/tests/with_components_off/erc721/erc721.test.ts

@@ -85,6 +85,10 @@ testERC721('enumerable', {
   enumerable: true,
 });
 
+testERC721('consecutive', {
+  consecutive: true,
+});
+
 testERC721('wrapper', {
   wrapper: true,
 });
@@ -248,6 +252,21 @@ test('erc721 votes, empty version', async t => {
   t.is((error as OptionsError).messages.appVersion, 'Application Version is required when Votes are enabled');
 });
 
+test('erc721 consecutive + enumerable is not allowed', async t => {
+  const error = t.throws(() =>
+    buildERC721({
+      name: NAME,
+      symbol: SYMBOL,
+      consecutive: true,
+      enumerable: true,
+    }),
+  );
+  t.is(
+    (error as OptionsError).messages.consecutive,
+    'Consecutive cannot be combined with Enumerable: batch mints bypass the update hook that Enumerable relies on to track ownership.',
+  );
+});
+
 testERC721('erc721 votes, non-upgradeable', {
   votes: true,
   appName: APP_NAME,
@@ -295,4 +314,5 @@ test('API isAccessControlRequired', async t => {
   );
   t.is(erc721.isAccessControlRequired({ burnable: true }), false);
   t.is(erc721.isAccessControlRequired({ enumerable: true }), false);
+  t.is(erc721.isAccessControlRequired({ consecutive: true }), false);
 });

packages/core/cairo_alpha/src/tests/with_components_off/erc721/erc721.test.ts.md

@@ -620,6 +620,113 @@ Generated by [AVA](https://avajs.dev).
     }␊
     `
 
+## consecutive
+
+> Snapshot 1
+
+    `// SPDX-License-Identifier: MIT␊
+    // Compatible with OpenZeppelin Contracts for Cairo 4.0.0-alpha.1␊
+    ␊
+    #[starknet::contract]␊
+    mod MyToken {␊
+        use openzeppelin_access::ownable::OwnableComponent;␊
+        use openzeppelin_interfaces::upgrades::IUpgradeable;␊
+        use openzeppelin_introspection::src5::SRC5Component;␊
+        use openzeppelin_token::erc721::{ERC721Component, ERC721TokenURIDefaultImpl};␊
+        use openzeppelin_token::erc721::extensions::erc721_consecutive::DefaultConfig;␊
+        use openzeppelin_token::erc721::extensions::ERC721ConsecutiveComponent;␊
+        use openzeppelin_upgrades::UpgradeableComponent;␊
+        use starknet::{ClassHash, ContractAddress};␊
+    ␊
+        component!(path: ERC721Component, storage: erc721, event: ERC721Event);␊
+        component!(path: SRC5Component, storage: src5, event: SRC5Event);␊
+        component!(path: ERC721ConsecutiveComponent, storage: erc721_consecutive, event: ERC721ConsecutiveEvent);␊
+        component!(path: UpgradeableComponent, storage: upgradeable, event: UpgradeableEvent);␊
+        component!(path: OwnableComponent, storage: ownable, event: OwnableEvent);␊
+    ␊
+        // External␊
+        #[abi(embed_v0)]␊
+        impl ERC721MixinImpl = ERC721Component::ERC721MixinImpl<ContractState>;␊
+        #[abi(embed_v0)]␊
+        impl OwnableMixinImpl = OwnableComponent::OwnableMixinImpl<ContractState>;␊
+    ␊
+        // Internal␊
+        impl ERC721InternalImpl = ERC721Component::InternalImpl<ContractState>;␊
+        impl ERC721ConsecutiveInternalImpl = ERC721ConsecutiveComponent::InternalImpl<ContractState>;␊
+        impl UpgradeableInternalImpl = UpgradeableComponent::InternalImpl<ContractState>;␊
+        impl OwnableInternalImpl = OwnableComponent::InternalImpl<ContractState>;␊
+    ␊
+        #[storage]␊
+        struct Storage {␊
+            #[substorage(v0)]␊
+            erc721: ERC721Component::Storage,␊
+            #[substorage(v0)]␊
+            src5: SRC5Component::Storage,␊
+            #[substorage(v0)]␊
+            erc721_consecutive: ERC721ConsecutiveComponent::Storage,␊
+            #[substorage(v0)]␊
+            upgradeable: UpgradeableComponent::Storage,␊
+            #[substorage(v0)]␊
+            ownable: OwnableComponent::Storage,␊
+        }␊
+    ␊
+        #[event]␊
+        #[derive(Drop, starknet::Event)]␊
+        enum Event {␊
+            #[flat]␊
+            ERC721Event: ERC721Component::Event,␊
+            #[flat]␊
+            SRC5Event: SRC5Component::Event,␊
+            #[flat]␊
+            ERC721ConsecutiveEvent: ERC721ConsecutiveComponent::Event,␊
+            #[flat]␊
+            UpgradeableEvent: UpgradeableComponent::Event,␊
+            #[flat]␊
+            OwnableEvent: OwnableComponent::Event,␊
+        }␊
+    ␊
+        #[constructor]␊
+        fn constructor(ref self: ContractState, owner: ContractAddress) {␊
+            self.erc721.initializer("MyToken", "MTK", "");␊
+            self.ownable.initializer(owner);␊
+        }␊
+    ␊
+        impl ERC721HooksImpl of ERC721Component::ERC721HooksTrait<ContractState> {␊
+            fn before_update(␊
+                ref self: ERC721Component::ComponentState<ContractState>,␊
+                to: ContractAddress,␊
+                token_id: u256,␊
+                auth: ContractAddress,␊
+            ) {␊
+                let mut contract_state = self.get_contract_mut();␊
+                contract_state.erc721_consecutive.before_update(to, token_id, auth);␊
+            }␊
+    ␊
+            fn after_update(␊
+                ref self: ERC721Component::ComponentState<ContractState>,␊
+                to: ContractAddress,␊
+                token_id: u256,␊
+                auth: ContractAddress,␊
+            ) {␊
+                let mut contract_state = self.get_contract_mut();␊
+                contract_state.erc721_consecutive.after_update(to, token_id, auth);␊
+            }␊
+        }␊
+    ␊
+        //␊
+        // Upgradeable␊
+        //␊
+        ␊
+        #[abi(embed_v0)]␊
+        impl UpgradeableImpl of IUpgradeable<ContractState> {␊
+            fn upgrade(ref self: ContractState, new_class_hash: ClassHash) {␊
+                self.ownable.assert_only_owner();␊
+                self.upgradeable.upgrade(new_class_hash);␊
+            }␊
+        }␊
+    }␊
+    `
+
 ## wrapper
 
 > Snapshot 1

packages/core/cairo_alpha/src/tests/with_components_off/erc721/erc721.test.ts.snap

@@ -80,6 +80,10 @@ testERC721('enumerable', {
   enumerable: true,
 });
 
+testERC721('consecutive', {
+  consecutive: true,
+});
+
 testERC721('wrapper', {
   wrapper: true,
 });
@@ -244,6 +248,21 @@ test('erc721 votes, empty version', async t => {
   t.is((error as OptionsError).messages.appVersion, 'Application Version is required when Votes are enabled');
 });
 
+test('erc721 consecutive + enumerable is not allowed', async t => {
+  const error = t.throws(() =>
+    buildERC721({
+      name: NAME,
+      symbol: SYMBOL,
+      consecutive: true,
+      enumerable: true,
+    }),
+  );
+  t.is(
+    (error as OptionsError).messages.consecutive,
+    'Consecutive cannot be combined with Enumerable: batch mints bypass the update hook that Enumerable relies on to track ownership.',
+  );
+});
+
 testERC721('erc721 votes, non-upgradeable', {
   votes: true,
   appName: APP_NAME,
@@ -290,4 +309,5 @@ test('API isAccessControlRequired', async t => {
   );
   t.is(erc721.isAccessControlRequired({ burnable: true }), false);
   t.is(erc721.isAccessControlRequired({ enumerable: true }), false);
+  t.is(erc721.isAccessControlRequired({ consecutive: true }), false);
 });