@openzeppelin/wizard-stellar 0.1.0

package/src/fungible.ts

@@ -0,0 +1,300 @@
+import type { Contract } from './contract';
+import { ContractBuilder } from './contract';
+import type { Access } from './set-access-control';
+import { requireAccessControl, setAccessControl } from './set-access-control';
+import { addPausable } from './add-pausable';
+import { defineFunctions } from './utils/define-functions';
+import type { CommonContractOptions } from './common-options';
+import { withCommonContractDefaults, getSelfArg } from './common-options';
+import { setInfo } from './set-info';
+import { OptionsError } from './error';
+import { contractDefaults as commonDefaults } from './common-options';
+import { printContract } from './print';
+import { toByteArray, toUint } from './utils/convert-strings';
+
+export const defaults: Required<FungibleOptions> = {
+  name: 'MyToken',
+  symbol: 'MTK',
+  burnable: false,
+  pausable: false,
+  premint: '0',
+  mintable: false,
+  access: commonDefaults.access, // TODO: Determine whether Access Control options should be visible in the UI before they are implemented as modules
+  info: commonDefaults.info,
+} as const;
+
+export function printFungible(opts: FungibleOptions = defaults): string {
+  return printContract(buildFungible(opts));
+}
+
+export interface FungibleOptions extends CommonContractOptions {
+  name: string;
+  symbol: string;
+  burnable?: boolean;
+  pausable?: boolean;
+  premint?: string;
+  mintable?: boolean;
+}
+
+function withDefaults(opts: FungibleOptions): Required<FungibleOptions> {
+  return {
+    ...opts,
+    ...withCommonContractDefaults(opts),
+    burnable: opts.burnable ?? defaults.burnable,
+    pausable: opts.pausable ?? defaults.pausable,
+    premint: opts.premint || defaults.premint,
+    mintable: opts.mintable ?? defaults.mintable,
+  };
+}
+
+export function buildFungible(opts: FungibleOptions): Contract {
+  const c = new ContractBuilder(opts.name);
+
+  const allOpts = withDefaults(opts);
+
+  addBase(c, toByteArray(allOpts.name), toByteArray(allOpts.symbol), allOpts.pausable);
+
+  if (allOpts.premint) {
+    addPremint(c, allOpts.premint);
+  }
+
+  if (allOpts.pausable) {
+    addPausable(c, allOpts.access);
+  }
+
+  if (allOpts.burnable) {
+    addBurnable(c, allOpts.pausable);
+  }
+
+  if (allOpts.mintable) {
+    addMintable(c, allOpts.access, allOpts.pausable);
+  }
+
+  setAccessControl(c, allOpts.access);
+  setInfo(c, allOpts.info);
+
+  return c;
+}
+
+function addBase(c: ContractBuilder, name: string, symbol: string, pausable: boolean) {
+  // Set metadata
+  c.addConstructorCode(
+    `fungible::metadata::set_metadata(e, 18, String::from_str(e, "${name}"), String::from_str(e, "${symbol}"));`,
+  );
+
+  // Set token functions
+  c.addUseClause('openzeppelin_fungible_token', 'self', { alias: 'fungible' });
+  c.addUseClause('openzeppelin_fungible_token', 'FungibleToken');
+  c.addUseClause('soroban_sdk', 'contract');
+  c.addUseClause('soroban_sdk', 'contractimpl');
+  c.addUseClause('soroban_sdk', 'Address');
+  c.addUseClause('soroban_sdk', 'String');
+  c.addUseClause('soroban_sdk', 'Env');
+  c.addUseClause('soroban_sdk', 'Symbol');
+
+  const fungibleTokenTrait = {
+    name: 'FungibleToken',
+    for: c.name,
+    tags: ['contractimpl'],
+  };
+
+  c.addFunction(fungibleTokenTrait, functions.total_supply);
+  c.addFunction(fungibleTokenTrait, functions.balance);
+  c.addFunction(fungibleTokenTrait, functions.allowance);
+  c.addFunction(fungibleTokenTrait, functions.transfer);
+  c.addFunction(fungibleTokenTrait, functions.transfer_from);
+  c.addFunction(fungibleTokenTrait, functions.approve);
+  c.addFunction(fungibleTokenTrait, functions.decimals);
+  c.addFunction(fungibleTokenTrait, functions.name);
+  c.addFunction(fungibleTokenTrait, functions.symbol);
+
+  if (pausable) {
+    c.addUseClause('openzeppelin_pausable_macros', 'when_not_paused');
+    c.addFunctionTag(fungibleTokenTrait, functions.transfer, 'when_not_paused');
+    c.addFunctionTag(fungibleTokenTrait, functions.transfer_from, 'when_not_paused');
+  }
+}
+
+function addBurnable(c: ContractBuilder, pausable: boolean) {
+  c.addUseClause('openzeppelin_fungible_token', 'burnable::FungibleBurnable');
+  c.addUseClause('soroban_sdk', 'Address');
+
+  const fungibleBurnableTrait = {
+    name: 'FungibleBurnable',
+    for: c.name,
+    tags: ['contractimpl'],
+    section: 'Extensions',
+  };
+
+  c.addFunction(fungibleBurnableTrait, functions.burn);
+  c.addFunction(fungibleBurnableTrait, functions.burn_from);
+
+  if (pausable) {
+    c.addUseClause('openzeppelin_pausable_macros', 'when_not_paused');
+    c.addFunctionTag(fungibleBurnableTrait, functions.burn, 'when_not_paused');
+    c.addFunctionTag(fungibleBurnableTrait, functions.burn_from, 'when_not_paused');
+  }
+}
+
+export const premintPattern = /^(\d*\.?\d*)$/;
+
+function addPremint(c: ContractBuilder, amount: string) {
+  if (amount !== undefined && amount !== '0') {
+    if (!premintPattern.test(amount)) {
+      throw new OptionsError({
+        premint: 'Not a valid number',
+      });
+    }
+
+    // TODO: handle signed int?
+    const premintAbsolute = toUint(getInitialSupply(amount, 18), 'premint', 'u128');
+
+    c.addUseClause('openzeppelin_fungible_token', 'mintable::FungibleMintable');
+    c.addUseClause('soroban_sdk', 'Address');
+
+    c.addConstructorArgument({ name: 'recipient', type: 'Address' });
+    c.addConstructorCode(`fungible::mintable::mint(e, &recipient, ${premintAbsolute});`);
+  }
+}
+
+/**
+ * Calculates the initial supply that would be used in an Fungible contract based on a given premint amount and number of decimals.
+ *
+ * @param premint Premint amount in token units, may be fractional
+ * @param decimals The number of decimals in the token
+ * @returns `premint` with zeros padded or removed based on `decimals`.
+ * @throws OptionsError if `premint` has more than one decimal character or is more precise than allowed by the `decimals` argument.
+ */
+export function getInitialSupply(premint: string, decimals: number): string {
+  let result;
+  const premintSegments = premint.split('.');
+  if (premintSegments.length > 2) {
+    throw new OptionsError({
+      premint: 'Not a valid number',
+    });
+  } else {
+    const firstSegment = premintSegments[0] ?? '';
+    let lastSegment = premintSegments[1] ?? '';
+    if (decimals > lastSegment.length) {
+      try {
+        lastSegment += '0'.repeat(decimals - lastSegment.length);
+      } catch {
+        // .repeat gives an error if decimals number is too large
+        throw new OptionsError({
+          premint: 'Decimals number too large',
+        });
+      }
+    } else if (decimals < lastSegment.length) {
+      throw new OptionsError({
+        premint: 'Too many decimals',
+      });
+    }
+    // concat segments without leading zeros
+    result = firstSegment.concat(lastSegment).replace(/^0+/, '');
+  }
+  if (result.length === 0) {
+    result = '0';
+  }
+  return result;
+}
+
+function addMintable(c: ContractBuilder, access: Access, pausable: boolean) {
+  c.addUseClause('openzeppelin_fungible_token', 'mintable::FungibleMintable');
+
+  const fungibleMintableTrait = {
+    name: 'FungibleMintable',
+    for: c.name,
+    tags: ['contractimpl'],
+    section: 'Extensions',
+  };
+
+  c.addFunction(fungibleMintableTrait, functions.mint);
+
+  requireAccessControl(c, fungibleMintableTrait, functions.mint, access);
+
+  if (pausable) {
+    c.addFunctionTag(fungibleMintableTrait, functions.mint, 'when_not_paused');
+  }
+}
+
+const functions = defineFunctions({
+  // Token Functions
+  total_supply: {
+    args: [getSelfArg()],
+    returns: 'i128',
+    code: ['fungible::total_supply(e)'],
+  },
+  balance: {
+    args: [getSelfArg(), { name: 'account', type: 'Address' }],
+    returns: 'i128',
+    code: ['fungible::balance(e, &account)'],
+  },
+  allowance: {
+    args: [getSelfArg(), { name: 'owner', type: 'Address' }, { name: 'spender', type: 'Address' }],
+    returns: 'i128',
+    code: ['fungible::allowance(e, &owner, &spender)'],
+  },
+  transfer: {
+    args: [
+      getSelfArg(),
+      { name: 'from', type: 'Address' },
+      { name: 'to', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+    ],
+    code: ['fungible::transfer(e, &from, &to, amount)'],
+  },
+  transfer_from: {
+    args: [
+      getSelfArg(),
+      { name: 'spender', type: 'Address' },
+      { name: 'from', type: 'Address' },
+      { name: 'to', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+    ],
+    code: ['fungible::transfer_from(e, &spender, &from, &to, amount)'],
+  },
+  approve: {
+    args: [
+      getSelfArg(),
+      { name: 'owner', type: 'Address' },
+      { name: 'spender', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+      { name: 'live_until_ledger', type: 'u32' },
+    ],
+    code: ['fungible::approve(e, &owner, &spender, amount, live_until_ledger)'],
+  },
+  decimals: {
+    args: [getSelfArg()],
+    returns: 'u32',
+    code: ['fungible::metadata::decimals(e)'],
+  },
+  name: {
+    args: [getSelfArg()],
+    returns: 'String',
+    code: ['fungible::metadata::name(e)'],
+  },
+  symbol: {
+    args: [getSelfArg()],
+    returns: 'String',
+    code: ['fungible::metadata::symbol(e)'],
+  },
+
+  // Extensions
+  burn: {
+    args: [getSelfArg(), { name: 'from', type: 'Address' }, { name: 'amount', type: 'i128' }],
+    code: ['fungible::burnable::burn(e, &from, amount)'],
+  },
+  burn_from: {
+    args: [
+      getSelfArg(),
+      { name: 'spender', type: 'Address' },
+      { name: 'from', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+    ],
+    code: ['fungible::burnable::burn_from(e, &spender, &from, amount)'],
+  },
+  mint: {
+    args: [getSelfArg(), { name: 'account', type: 'Address' }, { name: 'amount', type: 'i128' }],
+    code: ['fungible::mintable::mint(e, &account, amount);'],
+  },
+});

package/src/generate/alternatives.ts

@@ -0,0 +1,32 @@
+type Blueprint = Record<string, readonly unknown[]>;
+
+type Alternatives<B extends Blueprint> = {
+  [k in keyof B]: B[k][number];
+};
+
+export function* generateAlternatives<B extends Blueprint>(blueprint: B): Generator<Alternatives<B>> {
+  const entries = Object.entries(blueprint).map(([key, values]) => ({
+    key,
+    values,
+    current: 0,
+    limit: values.length,
+  }));
+
+  for (; !done(); advance()) {
+    yield Object.fromEntries(entries.map(e => [e.key, e.values[e.current % e.limit]])) as Alternatives<B>;
+  }
+
+  function done() {
+    const last = entries[entries.length - 1];
+    return last?.current === last?.limit;
+  }
+
+  function advance() {
+    for (const e of entries) {
+      e.current = (e.current % e.limit) + 1;
+      if (e.current < e.limit) {
+        break;
+      }
+    }
+  }
+}

package/src/generate/fungible.ts

@@ -0,0 +1,21 @@
+import type { FungibleOptions } from '../fungible';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyToken'],
+  symbol: ['MTK'],
+  burnable: booleans,
+  pausable: booleans,
+  mintable: booleans,
+  premint: ['1'],
+  access: accessOptions,
+  info: infoOptions,
+};
+
+export function* generateFungibleOptions(): Generator<Required<FungibleOptions>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/sources.ts

@@ -0,0 +1,75 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+
+import { generateFungibleOptions } from './fungible';
+import type { GenericOptions, KindedOptions } from '../build-generic';
+import { buildGeneric } from '../build-generic';
+import { printContract } from '../print';
+import { OptionsError } from '../error';
+import type { Contract } from '../contract';
+
+type Kind = keyof KindedOptions;
+
+export function* generateOptions(kind?: Kind): Generator<GenericOptions> {
+  if (!kind || kind === 'Fungible') {
+    for (const kindOpts of generateFungibleOptions()) {
+      yield { kind: 'Fungible', ...kindOpts };
+    }
+  }
+}
+
+interface GeneratedContract {
+  id: string;
+  options: GenericOptions;
+  contract: Contract;
+}
+
+interface GeneratedSource extends GeneratedContract {
+  source: string;
+}
+
+function generateContractSubset(kind?: Kind): GeneratedContract[] {
+  const contracts = [];
+
+  for (const options of generateOptions(kind)) {
+    const id = crypto.createHash('sha1').update(JSON.stringify(options)).digest().toString('hex');
+
+    try {
+      const contract = buildGeneric(options);
+      contracts.push({ id, options, contract });
+    } catch (e: unknown) {
+      if (e instanceof OptionsError) {
+        continue;
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  return contracts;
+}
+
+export function* generateSources(uniqueName?: boolean, kind?: Kind): Generator<GeneratedSource> {
+  let counter = 1;
+  for (const c of generateContractSubset(kind)) {
+    if (uniqueName) {
+      c.contract.name = `Contract${counter++}`;
+    }
+    const source = printContract(c.contract);
+    yield { ...c, source };
+  }
+}
+
+export async function writeGeneratedSources(dir: string, uniqueName?: boolean, kind?: Kind): Promise<string[]> {
+  await fs.mkdir(dir, { recursive: true });
+  const contractNames = [];
+
+  for (const { id, contract, source } of generateSources(uniqueName, kind)) {
+    const name = uniqueName ? contract.name : id;
+    await fs.writeFile(path.format({ dir, name, ext: '.rs' }), source);
+    contractNames.push(name);
+  }
+
+  return contractNames;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export type { GenericOptions, KindedOptions } from './build-generic';
+export { buildGeneric } from './build-generic';
+
+export type { Contract } from './contract';
+export { ContractBuilder } from './contract';
+
+export { printContract } from './print';
+
+export type { Access } from './set-access-control';
+export type { Info } from './set-info';
+
+export { premintPattern } from './fungible';
+
+export { defaults as infoDefaults } from './set-info';
+
+export type { OptionsErrorMessages } from './error';
+export { OptionsError } from './error';
+
+export type { Kind } from './kind';
+export { sanitizeKind } from './kind';
+
+export { contractsVersion, contractsVersionTag, compatibleContractsSemver } from './utils/version';
+
+export { fungible } from './api';

package/src/kind.ts

@@ -0,0 +1,26 @@
+import type { GenericOptions } from './build-generic';
+
+export type Kind = GenericOptions['kind'];
+
+export function sanitizeKind(kind: unknown): Kind {
+  if (typeof kind === 'string') {
+    const sanitized = kind.replace(/^(ERC|.)/i, c => c.toUpperCase());
+    if (isKind(sanitized)) {
+      return sanitized;
+    }
+  }
+  return 'Fungible';
+}
+
+function isKind<T>(value: Kind | T): value is Kind {
+  switch (value) {
+    case 'Fungible':
+      return true;
+
+    default: {
+      // Static assert that we've checked all kinds.
+      const _: T = value;
+      return false;
+    }
+  }
+}