@openzeppelin/wizard-stellar 0.1.0

package/dist/utils/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The actual latest version to use in links.
+ */
+export declare const contractsVersion = "0.1.0";
+export declare const contractsVersionTag = "v0.1.0";
+/**
+ * Semantic version string representing of the minimum compatible version of Contracts to display in output.
+ */
+export declare const compatibleContractsSemver = "^0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,gBAAgB,UAAU,CAAC;AACxC,eAAO,MAAM,mBAAmB,WAAyB,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,yBAAyB,WAAW,CAAC"}

package/dist/utils/version.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compatibleContractsSemver = exports.contractsVersionTag = exports.contractsVersion = void 0;
+/**
+ * The actual latest version to use in links.
+ */
+exports.contractsVersion = '0.1.0';
+exports.contractsVersionTag = `v${exports.contractsVersion}`;
+/**
+ * Semantic version string representing of the minimum compatible version of Contracts to display in output.
+ */
+exports.compatibleContractsSemver = '^0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACU,QAAA,gBAAgB,GAAG,OAAO,CAAC;AAC3B,QAAA,mBAAmB,GAAG,IAAI,wBAAgB,EAAE,CAAC;AAE1D;;GAEG;AACU,QAAA,yBAAyB,GAAG,QAAQ,CAAC"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@openzeppelin/wizard-stellar",
+  "version": "0.1.0",
+  "description": "A boilerplate generator to get started with OpenZeppelin Stellar Soroban Contracts",
+  "license": "AGPL-3.0-only",
+  "repository": "https://github.com/OpenZeppelin/contracts-wizard",
+  "main": "dist/index.js",
+  "ts:main": "src/index.ts",
+  "files": [
+    "LICENSE",
+    "NOTICE",
+    "/dist",
+    "/src",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "prepare": "tsc",
+    "prepublish": "rimraf dist *.tsbuildinfo",
+    "test": "ava",
+    "test:update-snapshots": "ava --update-snapshots",
+    "test:watch": "ava --watch",
+    "version": "node ../../../scripts/bump-changelog.js"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "@types/semver": "^7.5.7",
+    "ava": "^6.0.0",
+    "rimraf": "^5.0.0",
+    "ts-node": "^10.4.0",
+    "typescript": "^5.0.0",
+    "semver": "^7.6.0"
+  }
+}

package/src/add-pausable.ts

@@ -0,0 +1,40 @@
+import { getSelfArg } from './common-options';
+import type { ContractBuilder } from './contract';
+import type { Access } from './set-access-control';
+import { requireAccessControl } from './set-access-control';
+import { defineFunctions } from './utils/define-functions';
+
+export function addPausable(c: ContractBuilder, access: Access) {
+  c.addUseClause('openzeppelin_pausable', 'self', { alias: 'pausable' });
+  c.addUseClause('openzeppelin_pausable', 'Pausable');
+
+  const pausableTrait = {
+    name: 'Pausable',
+    for: c.name,
+    tags: ['contractimpl'],
+    section: 'Utils',
+  };
+
+  c.addFunction(pausableTrait, functions.paused);
+  c.addFunction(pausableTrait, functions.pause);
+  c.addFunction(pausableTrait, functions.unpause);
+
+  requireAccessControl(c, pausableTrait, functions.pause, access, 'caller');
+  requireAccessControl(c, pausableTrait, functions.unpause, access, 'caller');
+}
+
+const functions = defineFunctions({
+  paused: {
+    args: [getSelfArg()],
+    returns: 'bool',
+    code: ['pausable::paused(e)'],
+  },
+  pause: {
+    args: [getSelfArg(), { name: 'caller', type: 'Address' }],
+    code: ['pausable::pause(e, &caller)'],
+  },
+  unpause: {
+    args: [getSelfArg(), { name: 'caller', type: 'Address' }],
+    code: ['pausable::unpause(e, &caller)'],
+  },
+});

package/src/api.ts

@@ -0,0 +1,30 @@
+import type { CommonContractOptions } from './common-options';
+import type { FungibleOptions } from './fungible';
+import { printFungible, defaults as fungibledefaults } from './fungible';
+
+export interface WizardContractAPI<Options extends CommonContractOptions> {
+  /**
+   * Returns a string representation of a contract generated using the provided options. If opts is not provided, uses `defaults`.
+   */
+  print: (opts?: Options) => string;
+
+  /**
+   * The default options that are used for `print`.
+   */
+  defaults: Required<Options>;
+}
+
+export interface AccessControlAPI<Options extends CommonContractOptions> {
+  /**
+   * Whether any of the provided options require access control to be enabled. If this returns `true`, then calling `print` with the
+   * same options would cause the `access` option to default to `'ownable'` if it was `undefined` or `false`.
+   */
+  isAccessControlRequired: (opts: Partial<Options>) => boolean;
+}
+
+export type Fungible = WizardContractAPI<FungibleOptions>; // TODO add AccessControlAPI<FungibleOptions> when access control is implemented, if useful
+
+export const fungible: Fungible = {
+  print: printFungible,
+  defaults: fungibledefaults,
+};

package/src/build-generic.ts

@@ -0,0 +1,19 @@
+import type { FungibleOptions } from './fungible';
+import { buildFungible } from './fungible';
+
+export interface KindedOptions {
+  Fungible: { kind: 'Fungible' } & FungibleOptions;
+}
+
+export type GenericOptions = KindedOptions[keyof KindedOptions];
+
+export function buildGeneric(opts: GenericOptions) {
+  switch (opts.kind) {
+    case 'Fungible':
+      return buildFungible(opts);
+    default: {
+      const _: never = opts.kind; // TODO: When there are additional kinds above, change this assignment to just `opts` instead of `opts.kind`
+      throw new Error('Unknown ERC');
+    }
+  }
+}

package/src/common-options.ts

@@ -0,0 +1,38 @@
+import type { Argument } from './contract';
+import type { Access } from './set-access-control';
+import type { Info } from './set-info';
+import { defaults as infoDefaults } from './set-info';
+
+export const defaults: Required<CommonOptions> = {
+  info: infoDefaults,
+} as const;
+
+export const contractDefaults: Required<CommonContractOptions> = {
+  ...defaults,
+  access: false,
+} as const;
+
+export interface CommonOptions {
+  info?: Info;
+}
+
+export interface CommonContractOptions extends CommonOptions {
+  access?: Access;
+}
+
+export function withCommonDefaults(opts: CommonOptions): Required<CommonOptions> {
+  return {
+    info: opts.info ?? defaults.info,
+  };
+}
+
+export function withCommonContractDefaults(opts: CommonContractOptions): Required<CommonContractOptions> {
+  return {
+    ...withCommonDefaults(opts),
+    access: opts.access ?? contractDefaults.access,
+  };
+}
+
+export function getSelfArg(): Argument {
+  return { name: 'e', type: '&Env' };
+}

package/src/contract.ts

@@ -0,0 +1,201 @@
+import { toIdentifier } from './utils/convert-strings';
+
+export interface Contract {
+  license: string;
+  name: string;
+  useClauses: UseClause[];
+  constructorCode: string[];
+  constructorArgs: Argument[];
+  implementedTraits: ImplementedTrait[];
+  variables: Variable[];
+  errors: Error[];
+  ownable: boolean;
+}
+
+export interface Error {
+  name: string;
+  num: number;
+}
+
+export type Value = string | number | bigint | { lit: string } | { note: string; value: Value };
+
+export interface UseClause {
+  containerPath: string;
+  name: string;
+  groupable?: boolean;
+  alias?: string;
+}
+
+export interface BaseImplementedTrait {
+  name: string;
+  for: string;
+  tags: string[];
+  section?: string;
+  /**
+   * Priority for which trait to print first.
+   * Lower numbers are higher priority, undefined is lowest priority.
+   */
+  priority?: number;
+}
+
+export interface ImplementedTrait extends BaseImplementedTrait {
+  functions: ContractFunction[];
+  section?: string;
+}
+
+export interface BaseFunction {
+  name: string;
+  args: Argument[];
+  code: string[];
+  returns?: string;
+}
+
+export interface ContractFunction extends BaseFunction {
+  codeBefore?: string[];
+  tag?: string;
+}
+
+export interface Variable {
+  name: string;
+  type: string;
+  value: string;
+}
+
+export interface Argument {
+  name: string;
+  type?: string;
+}
+
+export class ContractBuilder implements Contract {
+  readonly name: string;
+  license = 'MIT';
+  ownable = false;
+
+  readonly constructorArgs: Argument[] = [];
+  readonly constructorCode: string[] = [];
+
+  private implementedTraitsMap: Map<string, ImplementedTrait> = new Map();
+  private variablesMap: Map<string, Variable> = new Map();
+  private useClausesMap: Map<string, UseClause> = new Map();
+  private errorsMap: Map<string, Error> = new Map();
+
+  constructor(name: string) {
+    this.name = toIdentifier(name, true);
+  }
+
+  get implementedTraits(): ImplementedTrait[] {
+    return [...this.implementedTraitsMap.values()];
+  }
+
+  get variables(): Variable[] {
+    return [...this.variablesMap.values()];
+  }
+
+  get useClauses(): UseClause[] {
+    return [...this.useClausesMap.values()];
+  }
+
+  get errors(): Error[] {
+    return [...this.errorsMap.values()];
+  }
+
+  addError(name: string, num: number): boolean {
+    if (this.errorsMap.has(name)) {
+      return false;
+    } else {
+      this.addUseClause('soroban_sdk', 'contracterror');
+      this.errorsMap.set(name, { name, num });
+      return true;
+    }
+  }
+
+  addUseClause(containerPath: string, name: string, options?: { groupable?: boolean; alias?: string }): void {
+    // groupable defaults to true
+    const groupable = options?.groupable ?? true;
+    const alias = options?.alias ?? '';
+    const uniqueName = alias.length > 0 ? alias : name;
+    const present = this.useClausesMap.has(uniqueName);
+    if (!present) {
+      this.useClausesMap.set(uniqueName, { containerPath, name, groupable, alias });
+    }
+  }
+
+  addVariable(variable: Variable): boolean {
+    if (this.variablesMap.has(variable.name)) {
+      return false;
+    } else {
+      this.variablesMap.set(variable.name, variable);
+      return true;
+    }
+  }
+
+  addImplementedTrait(baseTrait: BaseImplementedTrait): ImplementedTrait {
+    const key = baseTrait.name;
+    const existingTrait = this.implementedTraitsMap.get(key);
+    if (existingTrait !== undefined) {
+      return existingTrait;
+    } else {
+      const t: ImplementedTrait = {
+        name: baseTrait.name,
+        for: baseTrait.for,
+        tags: [...baseTrait.tags],
+        functions: [],
+        section: baseTrait.section,
+        priority: baseTrait.priority,
+      };
+      this.implementedTraitsMap.set(key, t);
+      return t;
+    }
+  }
+
+  addFunction(baseTrait: BaseImplementedTrait, fn: BaseFunction): ContractFunction {
+    const t = this.addImplementedTrait(baseTrait);
+
+    const signature = this.getFunctionSignature(fn);
+
+    // Look for the existing function with the same signature and return it if found
+    for (let i = 0; i < t.functions.length; i++) {
+      const existingFn = t.functions[i];
+      if (existingFn !== undefined && this.getFunctionSignature(existingFn) === signature) {
+        return existingFn;
+      }
+    }
+
+    // Otherwise, add the function
+    const contractFn: ContractFunction = {
+      ...fn,
+      codeBefore: [],
+    };
+    t.functions.push(contractFn);
+    return contractFn;
+  }
+
+  private getFunctionSignature(fn: BaseFunction): string {
+    return [fn.name, '(', ...fn.args.map(a => a.name), ')'].join('');
+  }
+
+  addFunctionCodeBefore(baseTrait: BaseImplementedTrait, fn: BaseFunction, codeBefore: string[]): void {
+    this.addImplementedTrait(baseTrait);
+    const existingFn = this.addFunction(baseTrait, fn);
+    existingFn.codeBefore = [...(existingFn.codeBefore ?? []), ...codeBefore];
+  }
+
+  addFunctionTag(baseTrait: BaseImplementedTrait, fn: BaseFunction, tag: string): void {
+    this.addImplementedTrait(baseTrait);
+    const existingFn = this.addFunction(baseTrait, fn);
+    existingFn.tag = tag;
+  }
+
+  addConstructorArgument(arg: Argument): void {
+    for (const existingArg of this.constructorArgs) {
+      if (existingArg.name == arg.name) {
+        return;
+      }
+    }
+    this.constructorArgs.push(arg);
+  }
+
+  addConstructorCode(code: string): void {
+    this.constructorCode.push(code);
+  }
+}

package/src/error.ts

@@ -0,0 +1,7 @@
+export type OptionsErrorMessages = { [prop in string]?: string };
+
+export class OptionsError extends Error {
+  constructor(readonly messages: OptionsErrorMessages) {
+    super('Invalid options');
+  }
+}