feat: add erc721 consecutive extension

Author: ericnordelo

.changeset/cairo-alpha-erc721-consecutive.md

@@ -0,0 +1,5 @@
+---
+"@openzeppelin/wizard-common": patch
+---
+
+Cairo: ERC721 consecutive description for AI prompts.

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

@@ -58,6 +58,8 @@ export const cairoERC721Descriptions = {
   baseUri: 'A base uri for the non-fungible token.',
   enumerable:
     'Whether to allow on-chain enumeration of all tokens or those owned by an account. Increases gas cost of transfers.',
+  consecutive:
+    'Whether to enable batch minting of consecutive token IDs during construction. CAUTION: ERC721 extensions that implement custom balanceOf logic, such as ERC721Consecutive, interfere with enumerability and should not be used together with ERC721Enumerable.',
   votes:
     'Whether to keep track of individual units for voting in on-chain governance. Voting durations can be expressed as block numbers or timestamps.',
 };

packages/core/cairo_alpha/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Add ERC721Consecutive extension ([#765](https://github.com/OpenZeppelin/contracts-wizard/pull/765))
+
+- **Breaking changes**:
+  - Use OpenZeppelin Contracts for Cairo v4.0.0-alpha.0.
+
 ## 3.0.0 (2026-01-10)
 
 - Add support for `with_components` macro. ([#703](https://github.com/OpenZeppelin/contracts-wizard/pull/703))

packages/core/cairo_alpha/ava.config.js

@@ -1,6 +1,7 @@
 module.exports = {
   extensions: ['ts'],
   require: ['ts-node/register'],
+  files: ['src/**/*.test.ts'],
   watchmode: {
     ignoreChanges: ['contracts', 'artifacts', 'cache'],
   },

packages/core/cairo_alpha/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openzeppelin/wizard-cairo-alpha",
   "private": true,
-  "version": "3.0.0",
+  "version": "4.0.0-alpha.0",
   "description": "A boilerplate generator to get started with the latest alpha version of OpenZeppelin Contracts for Cairo",
   "license": "AGPL-3.0-only",
   "repository": "https://github.com/OpenZeppelin/contracts-wizard",

packages/core/cairo_alpha/src/erc721.ts

@@ -26,6 +26,7 @@ export const defaults: Required<ERC721Options> = {
   pausable: false,
   mintable: false,
   enumerable: false,
+  consecutive: false,
   votes: false,
   royaltyInfo: royaltyInfoDefaults,
   appName: '', // Defaults to empty string, but user must provide a non-empty value if votes are enabled
@@ -48,6 +49,7 @@ export interface ERC721Options extends CommonContractOptions {
   pausable?: boolean;
   mintable?: boolean;
   enumerable?: boolean;
+  consecutive?: boolean;
   votes?: boolean;
   royaltyInfo?: RoyaltyInfoOptions;
   appName?: string;
@@ -63,6 +65,7 @@ function withDefaults(opts: ERC721Options): Required<ERC721Options> {
     pausable: opts.pausable ?? defaults.pausable,
     mintable: opts.mintable ?? defaults.mintable,
     enumerable: opts.enumerable ?? defaults.enumerable,
+    consecutive: opts.consecutive ?? defaults.consecutive,
     royaltyInfo: opts.royaltyInfo ?? defaults.royaltyInfo,
     votes: opts.votes ?? defaults.votes,
     appName: opts.appName ?? defaults.appName,
@@ -78,6 +81,14 @@ 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:
+        'ERC721 extensions that implement custom balanceOf logic, such as ERC721Consecutive, interfere with enumerability and should not be used together with ERC721Enumerable.',
+    });
+  }
+
   const c = new ContractBuilder(allOpts.name, allOpts.macros);
 
   addBase(c, toByteArray(allOpts.name), toByteArray(allOpts.symbol), toByteArray(allOpts.baseUri));
@@ -99,6 +110,10 @@ export function buildERC721(opts: ERC721Options): Contract {
     addEnumerable(c);
   }
 
+  if (allOpts.consecutive) {
+    addConsecutive(c);
+  }
+
   setAccessControl(c, allOpts.access);
   setUpgradeable(c, allOpts.upgradeable, allOpts.access);
   setInfo(c, allOpts.info);
@@ -110,7 +125,7 @@ export function buildERC721(opts: ERC721Options): Contract {
 }
 
 function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
-  const usesCustomHooks = opts.pausable || opts.enumerable || opts.votes;
+  const usesCustomHooks = opts.pausable || opts.enumerable || opts.consecutive || opts.votes;
   if (usesCustomHooks) {
     const ERC721HooksTrait: BaseImplementedTrait = {
       name: `ERC721HooksImpl`,
@@ -121,7 +136,7 @@ function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
     c.addImplementedTrait(ERC721HooksTrait);
     c.addUseClause('starknet', 'ContractAddress');
 
-    const requiresMutState = opts.enumerable || opts.votes;
+    const requiresMutState = opts.enumerable || opts.consecutive || opts.votes;
     const initStateLine = requiresMutState
       ? 'let mut contract_state = self.get_contract_mut()'
       : 'let contract_state = self.get_contract()';
@@ -132,6 +147,9 @@ function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
     if (opts.enumerable) {
       beforeUpdateCode.push('contract_state.erc721_enumerable.before_update(to, token_id)');
     }
+    if (opts.consecutive) {
+      beforeUpdateCode.push('contract_state.erc721_consecutive.before_update(to, token_id, auth)');
+    }
     if (opts.votes) {
       if (!opts.appName) {
         throw new OptionsError({
@@ -167,6 +185,27 @@ function addHooks(c: ContractBuilder, opts: Required<ERC721Options>) {
       ],
       code: beforeUpdateCode,
     });
+
+    // Add after_update hook for consecutive
+    if (opts.consecutive) {
+      const afterUpdateCode = [
+        'let mut contract_state = self.get_contract_mut()',
+        'contract_state.erc721_consecutive.after_update(to, token_id, auth)',
+      ];
+      c.addFunction(ERC721HooksTrait, {
+        name: 'after_update',
+        args: [
+          {
+            name: 'ref self',
+            type: `ERC721Component::ComponentState<ContractState>`,
+          },
+          { name: 'to', type: 'ContractAddress' },
+          { name: 'token_id', type: 'u256' },
+          { name: 'auth', type: 'ContractAddress' },
+        ],
+        code: afterUpdateCode,
+      });
+    }
   } else {
     c.addUseClause('openzeppelin_token::erc721', 'ERC721HooksEmptyImpl');
   }
@@ -190,6 +229,11 @@ function addEnumerable(c: ContractBuilder) {
   c.addComponent(components.ERC721EnumerableComponent, [], true);
 }
 
+function addConsecutive(c: ContractBuilder) {
+  c.addComponent(components.ERC721ConsecutiveComponent, [], true);
+  c.addUseClause('openzeppelin_token::erc721::extensions::erc721_consecutive', 'DefaultConfig');
+}
+
 function addBurnable(c: ContractBuilder) {
   c.addUseClause('core::num::traits', 'Zero');
   c.addUseClause('starknet', 'get_caller_address');
@@ -247,6 +291,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

@@ -24,6 +24,7 @@ function prepareBlueprint(opts: GeneratorOptions) {
     baseUri: ['https://example.com/'],
     burnable: booleans,
     enumerable: booleans,
+    consecutive: booleans,
     votes: booleans,
     appName: ['MyApp'],
     appVersion: ['v1'],