Add Vesting (#425)

immrsd · ericglau · web-flow · commit e08725a1ea9a · 2025-01-13T17:06:28.000+01:00
Co-authored-by: Eric Lau &lt;ericglau@outlook.com&gt;
diff --git a/packages/core-cairo/CHANGELOG.md b/packages/core-cairo/CHANGELOG.md
@@ -1,7 +1,8 @@
 # Changelog
 
-## Unreleased
+## 0.21.0 (2025-01-09)
 
+- Add Vesting tab. ([#425](https://github.com/OpenZeppelin/contracts-wizard/pull/425))
 - Update Contracts Wizard license to AGPLv3. ([#424](https://github.com/OpenZeppelin/contracts-wizard/pull/424))
 
 ## 0.20.1 (2024-12-17)
diff --git a/packages/core-cairo/package.json b/packages/core-cairo/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@openzeppelin/wizard-cairo",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "A boilerplate generator to get started with OpenZeppelin Contracts for Cairo",
   "license": "AGPL-3.0-only",
   "repository": "https://github.com/OpenZeppelin/contracts-wizard",
diff --git a/packages/core-cairo/src/api.ts b/packages/core-cairo/src/api.ts
@@ -5,6 +5,7 @@ import { printERC1155, defaults as erc1155defaults, isAccessControlRequired as e
 import { printAccount, defaults as accountDefaults, AccountOptions } from './account';
 import { printGovernor, defaults as governorDefaults, isAccessControlRequired as governorIsAccessControlRequired, GovernorOptions } from './governor';
 import { printCustom, defaults as customDefaults, isAccessControlRequired as customIsAccessControlRequired, CustomOptions } from './custom';
+import { printVesting, defaults as vestingDefaults, isAccessControlRequired as vestingIsAccessControlRequired, VestingOptions } from './vesting';
 
 export interface WizardAccountAPI<Options extends CommonOptions>{
   /**
@@ -41,6 +42,7 @@ export type ERC721 = WizardContractAPI<ERC721Options>;
 export type ERC1155 = WizardContractAPI<ERC1155Options>;
 export type Account = WizardAccountAPI<AccountOptions>;
 export type Governor = WizardContractAPI<GovernorOptions>;
+export type Vesting = WizardContractAPI<VestingOptions>;
 export type Custom = WizardContractAPI<CustomOptions>;
 
 export const erc20: ERC20 = {
@@ -67,6 +69,11 @@ export const governor: Governor = {
   defaults: governorDefaults,
   isAccessControlRequired: governorIsAccessControlRequired
 }
+export const vesting: Vesting = {
+  print: printVesting,
+  defaults: vestingDefaults,
+  isAccessControlRequired: vestingIsAccessControlRequired
+}
 export const custom: Custom = {
   print: printCustom,
   defaults: customDefaults,
diff --git a/packages/core-cairo/src/build-generic.ts b/packages/core-cairo/src/build-generic.ts
@@ -4,12 +4,15 @@ import { ERC1155Options, buildERC1155 } from './erc1155';
 import { CustomOptions, buildCustom } from './custom';
 import { AccountOptions, buildAccount } from './account';
 import { GovernorOptions, buildGovernor } from './governor';
+import { VestingOptions, buildVesting } from './vesting';
+
 export interface KindedOptions {
   ERC20:    { kind: 'ERC20' }    & ERC20Options;
   ERC721:   { kind: 'ERC721' }   & ERC721Options;
   ERC1155:  { kind: 'ERC1155' }  & ERC1155Options;
   Account:  { kind: 'Account' }  & AccountOptions;
   Governor: { kind: 'Governor' } & GovernorOptions;
+  Vesting: { kind: 'Vesting' } & VestingOptions;
   Custom:   { kind: 'Custom' }   & CustomOptions;
 }
 
@@ -32,6 +35,9 @@ export function buildGeneric(opts: GenericOptions) {
     case 'Governor':
       return buildGovernor(opts);
 
+    case 'Vesting':
+      return buildVesting(opts);
+
     case 'Custom':
       return buildCustom(opts);
 
diff --git a/packages/core-cairo/src/generate/sources.ts b/packages/core-cairo/src/generate/sources.ts
@@ -8,6 +8,7 @@ import { generateERC1155Options } from './erc1155';
 import { generateAccountOptions } from './account';
 import { generateCustomOptions } from './custom';
 import { generateGovernorOptions } from './governor';
+import { generateVestingOptions } from './vesting';
 import { buildGeneric, GenericOptions, KindedOptions } from '../build-generic';
 import { printContract } from '../print';
 import { OptionsError } from '../error';
@@ -54,6 +55,12 @@ export function* generateOptions(kind?: Kind): Generator<GenericOptions> {
       yield { kind: 'Governor', ...kindOpts };
     }
   }
+
+  if (!kind || kind === 'Vesting') {
+    for (const kindOpts of generateVestingOptions()) {
+      yield { kind: 'Vesting', ...kindOpts };
+    }
+  }
 }
 
 interface GeneratedContract {
@@ -92,9 +99,27 @@ function generateContractSubset(subset: Subset, kind?: Kind): GeneratedContract[
     return contracts;
   } else {
     const getParents = (c: GeneratedContract) => c.contract.components.map(p => p.path);
+    function filterByUpgradeableSetTo(isUpgradeable: boolean) {
+      return (c: GeneratedContract) => {
+        switch (c.options.kind) {
+          case 'Vesting':
+            return isUpgradeable === false;
+          case 'Account':
+          case 'ERC20':
+          case 'ERC721':
+          case 'ERC1155':
+          case 'Governor':
+          case 'Custom':
+            return c.options.upgradeable === isUpgradeable;
+          default:
+            const _: never = c.options;
+            throw new Error('Unknown kind');
+        }
+      }
+    }
     return [
-      ...findCover(contracts.filter(c => c.options.upgradeable), getParents),
-      ...findCover(contracts.filter(c => !c.options.upgradeable), getParents),
+      ...findCover(contracts.filter(filterByUpgradeableSetTo(true)), getParents),
+      ...findCover(contracts.filter(filterByUpgradeableSetTo(false)), getParents),
     ];
   }
 }
diff --git a/packages/core-cairo/src/generate/vesting.ts b/packages/core-cairo/src/generate/vesting.ts
@@ -0,0 +1,16 @@
+import { infoOptions } from '../set-info';
+import type { VestingOptions } from '../vesting';
+import { generateAlternatives } from './alternatives';
+
+const blueprint = {
+  name: ['MyVesting'],
+  startDate: ['2024-12-31T23:59'],
+  duration: ['90 days', '1 year'],
+  cliffDuration: ['0 seconds', '30 day'],
+  schedule: ['linear', 'custom'] as const,
+  info: infoOptions
+};
+
+export function* generateVestingOptions(): Generator<Required<VestingOptions>> {
+  yield* generateAlternatives(blueprint);
+}
diff --git a/packages/core-cairo/src/governor.test.ts b/packages/core-cairo/src/governor.test.ts
@@ -125,9 +125,9 @@ testAPIEquivalence('API erc721 votes + timelock', {
 });
 
 testAPIEquivalence('API custom name', {
+  name: 'CustomGovernor',
   delay: '1 day',
   period: '1 week',
-  name: 'CustomGovernor',
 });
 
 testAPIEquivalence('API custom settings', {
@@ -146,7 +146,8 @@ testAPIEquivalence('API quorum mode absolute', {
   quorumAbsolute: '200',
 });
 
-testAPIEquivalence('API quorum mode percent', { name: NAME,
+testAPIEquivalence('API quorum mode percent', { 
+  name: NAME,
   delay: '1 day',
   period: '1 week',
   quorumMode: 'percent',
diff --git a/packages/core-cairo/src/index.ts b/packages/core-cairo/src/index.ts
@@ -25,4 +25,4 @@ export { sanitizeKind } from './kind';
 
 export { contractsVersion, contractsVersionTag, compatibleContractsSemver } from './utils/version';
 
-export { erc20, erc721, erc1155, account, governor, custom } from './api';
+export { erc20, erc721, erc1155, account, governor, vesting, custom } from './api';
diff --git a/packages/core-cairo/src/kind.ts b/packages/core-cairo/src/kind.ts
@@ -19,6 +19,7 @@ function isKind<T>(value: Kind | T): value is Kind {
     case 'ERC1155':
     case 'Account':
     case 'Governor':
+    case 'Vesting':
     case 'Custom':
       return true;
 
diff --git a/packages/core-cairo/src/set-upgradeable.ts b/packages/core-cairo/src/set-upgradeable.ts
@@ -11,7 +11,7 @@ export type Upgradeable = typeof upgradeableOptions[number];
 
 function setUpgradeableBase(c: ContractBuilder, upgradeable: Upgradeable): BaseImplementedTrait | undefined {
   if (upgradeable === false) {
-    return;
+    return undefined;
   }
 
   c.upgradeable = true;
diff --git a/packages/core-cairo/src/test.ts b/packages/core-cairo/src/test.ts
@@ -7,7 +7,6 @@ import { generateSources, writeGeneratedSources } from './generate/sources';
 import type { GenericOptions, KindedOptions } from './build-generic';
 import { custom, erc20, erc721, erc1155 } from './api';
 
-
 interface Context {
   generatedSourcesPath: string
 }
@@ -63,12 +62,27 @@ test('is access control required', async t => {
   for (const contract of generateSources('all')) {
     const regexOwnable = /(use openzeppelin::access::ownable::OwnableComponent)/gm;
 
-    if (contract.options.kind !== 'Account' && contract.options.kind !== 'Governor' && !contract.options.access) {
-      if (isAccessControlRequired(contract.options)) {
-        t.regex(contract.source, regexOwnable, JSON.stringify(contract.options));
-      } else {
-        t.notRegex(contract.source, regexOwnable, JSON.stringify(contract.options));
-      }
+    switch (contract.options.kind) {
+      case 'Account':
+      case 'Governor':
+      case 'Vesting':
+        // These contracts have no access control option
+        break;
+      case 'ERC20':
+      case 'ERC721':
+      case 'ERC1155':
+      case 'Custom':
+        if (!contract.options.access) {
+          if (isAccessControlRequired(contract.options)) {
+            t.regex(contract.source, regexOwnable, JSON.stringify(contract.options));
+          } else {
+            t.notRegex(contract.source, regexOwnable, JSON.stringify(contract.options));
+          }
+        }
+        break;
+      default:
+        const _: never = contract.options;
+        throw new Error('Unknown kind');
     }
   }
-});
+});
diff --git a/packages/core-cairo/src/utils/convert-strings.ts b/packages/core-cairo/src/utils/convert-strings.ts
@@ -70,20 +70,28 @@ const UINT_MAX_VALUES = {
 export type UintType = keyof typeof UINT_MAX_VALUES;
 
 /**
- * Validates a string value to be a valid uint and converts it to bigint
+ * Checks that a string/number value is a valid `uint` value and converts it to bigint
  */
-export function toUint(str: string, field: string, type: UintType): bigint {
-  const isValidNumber = /^\d+$/.test(str);
+export function toUint(value: number | string, field: string, type: UintType): bigint {
+  const valueAsStr = value.toString(); 
+  const isValidNumber = /^\d+$/.test(valueAsStr);
   if (!isValidNumber) {
     throw new OptionsError({
       [field]: 'Not a valid number'
     });
   }
-  const numValue = BigInt(str);
+  const numValue = BigInt(valueAsStr);
   if (numValue > UINT_MAX_VALUES[type]) {
     throw new OptionsError({
       [field]: `Value is greater than ${type} max value`
     });
   }
   return numValue;
 }
+
+/**
+ * Checks that a string/number value is a valid `uint` value
+ */
+export function validateUint(value: number | string, field: string, type: UintType): void {
+  const _ = toUint(value, field, type);
+}
diff --git a/packages/core-cairo/src/utils/duration.ts b/packages/core-cairo/src/utils/duration.ts
@@ -14,7 +14,7 @@ const secondsForUnit = { second, minute, hour, day, week, month, year };
 export function durationToTimestamp(duration: string): number {
   const match = duration.trim().match(durationPattern);
 
-  if (!match) {
+  if (!match || match.length < 2) {
     throw new Error('Bad duration format');
   }
 
diff --git a/packages/core-cairo/src/vesting.test.ts b/packages/core-cairo/src/vesting.test.ts
@@ -0,0 +1,123 @@
+import test from 'ava';
+import { OptionsError, vesting } from '.';
+import { buildVesting, VestingOptions } from './vesting';
+import { printContract } from './print';
+
+const defaults: VestingOptions = {
+  name: 'MyVesting',
+  startDate: '',
+  duration: '0 day',
+  cliffDuration: '0 day',
+  schedule: 'linear'
+};
+
+const CUSTOM_NAME = 'CustomVesting';
+const CUSTOM_DATE = '2024-12-31T23:59';
+const CUSTOM_DURATION = '36 months';
+const CUSTOM_CLIFF = '90 days';
+
+//
+// Test helpers
+//
+
+function testVesting(title: string, opts: Partial<VestingOptions>) {
+  test(title, t => {
+    const c = buildVesting({
+      ...defaults,
+      ...opts
+    });
+    t.snapshot(printContract(c));
+  });
+}
+
+function testAPIEquivalence(title: string, opts?: VestingOptions) {
+  test(title, t => {
+    t.is(vesting.print(opts), printContract(buildVesting({
+      ...defaults,
+      ...opts
+    })));
+  });
+}
+
+//
+// Snapshot tests
+//
+
+testVesting('custom name', {
+  name: CUSTOM_NAME,
+});
+
+testVesting('custom start date', {
+  startDate: CUSTOM_DATE
+});
+
+testVesting('custom duration', {
+  duration: CUSTOM_DURATION
+});
+
+testVesting('custom cliff', {
+  duration: CUSTOM_DURATION,
+  cliffDuration: CUSTOM_CLIFF
+});
+
+testVesting('custom schedule', {
+  schedule: 'custom'
+});
+
+testVesting('all custom settings', {
+  startDate: CUSTOM_DATE,
+  duration: CUSTOM_DURATION,
+  cliffDuration: CUSTOM_CLIFF,
+  schedule: 'custom'
+});
+
+//
+// API tests
+//
+
+testAPIEquivalence('API custom name', {
+  ...defaults,
+  name: CUSTOM_NAME
+});
+
+testAPIEquivalence('API custom start date', {
+  ...defaults,
+  startDate: CUSTOM_DATE
+});
+
+testAPIEquivalence('API custom duration', {
+  ...defaults,
+  duration: CUSTOM_DURATION
+});
+
+testAPIEquivalence('API custom cliff', {
+  ...defaults,
+  duration: CUSTOM_DURATION,
+  cliffDuration: CUSTOM_CLIFF
+});
+
+testAPIEquivalence('API custom schedule', {
+  ...defaults,
+  schedule: 'custom'
+});
+
+testAPIEquivalence('API all custom settings', {
+  ...defaults,
+  startDate: CUSTOM_DATE,
+  duration: CUSTOM_DURATION,
+  cliffDuration: CUSTOM_CLIFF,
+  schedule: 'custom'
+});
+
+test('Vesting API isAccessControlRequired', async t => {
+  t.is(vesting.isAccessControlRequired({}), true);
+});
+
+test('cliff too high', async t => {
+  const error = t.throws(() => buildVesting({
+    ...defaults,
+    duration: '20 days',
+    cliffDuration: '21 days'
+  }));
+  t.is((error as OptionsError).messages.cliffDuration, 'Cliff duration must be less than or equal to the total duration');
+});
diff --git a/packages/core-cairo/src/vesting.test.ts.md b/packages/core-cairo/src/vesting.test.ts.md
diff --git a/packages/core-cairo/src/vesting.test.ts.snap b/packages/core-cairo/src/vesting.test.ts.snap
diff --git a/packages/core-cairo/src/vesting.ts b/packages/core-cairo/src/vesting.ts
diff --git a/packages/ui/src/cairo/App.svelte b/packages/ui/src/cairo/App.svelte
diff --git a/packages/ui/src/cairo/VestingControls.svelte b/packages/ui/src/cairo/VestingControls.svelte
diff --git a/packages/ui/src/styles/global.css b/packages/ui/src/styles/global.css

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@openzeppelin/wizard-cairo",`
`3`		`- "version": "0.20.1",`
	`3`	`+ "version": "0.21.0",`
`4`	`4`	`"description": "A boilerplate generator to get started with OpenZeppelin Contracts for Cairo",`
`5`	`5`	`"license": "AGPL-3.0-only",`
`6`	`6`	`"repository": "https://github.com/OpenZeppelin/contracts-wizard",`
Original file line number	Diff line number	Diff line change
`@@ -25,4 +25,4 @@ export { sanitizeKind } from './kind';`
`25`	`25`
`26`	`26`	`export { contractsVersion, contractsVersionTag, compatibleContractsSemver } from './utils/version';`
`27`	`27`
`28`		`-export { erc20, erc721, erc1155, account, governor, custom } from './api';`
	`28`	`+export { erc20, erc721, erc1155, account, governor, vesting, custom } from './api';`
Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ export type Upgradeable = typeof upgradeableOptions[number];`
`11`	`11`
`12`	`12`	`function setUpgradeableBase(c: ContractBuilder, upgradeable: Upgradeable): BaseImplementedTrait \| undefined {`
`13`	`13`	`if (upgradeable === false) {`
`14`		`- return;`
	`14`	`+ return undefined;`
`15`	`15`	`}`
`16`	`16`
`17`	`17`	`c.upgradeable = true;`