@openzeppelin/wizard-stellar 0.1.0

package/src/print.ts

@@ -0,0 +1,305 @@
+import type { Contract, Argument, ContractFunction, ImplementedTrait, UseClause } from './contract';
+
+import type { Lines } from './utils/format-lines';
+import { formatLines, spaceBetween } from './utils/format-lines';
+import { getSelfArg } from './common-options';
+import { compatibleContractsSemver } from './utils/version';
+
+const DEFAULT_SECTION = '1. with no section';
+const STANDALONE_IMPORTS_GROUP = 'Standalone Imports';
+const MAX_USE_CLAUSE_LINE_LENGTH = 90;
+const TAB = '    ';
+
+export function printContract(contract: Contract): string {
+  return formatLines(
+    ...spaceBetween(
+      [
+        `// SPDX-License-Identifier: ${contract.license}`,
+        `// Compatible with OpenZeppelin Stellar Soroban Contracts ${compatibleContractsSemver}`,
+      ],
+      spaceBetween(
+        printUseClauses(contract),
+        printVariables(contract),
+        printContractStruct(contract),
+        printContractErrors(contract),
+        printContractFunctions(contract),
+        printImplementedTraits(contract),
+      ),
+    ),
+  );
+}
+
+function printContractStruct(contract: Contract): Lines[] {
+  return ['#[contract]', `pub struct ${contract.name};`];
+}
+
+function printContractErrors(contract: Contract): Lines[] {
+  if (contract.errors.length === 0) {
+    return [];
+  }
+  return [
+    '#[contracterror]',
+    '#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]',
+    '#[repr(u32)]',
+    `pub enum ${contract.name}Error {`,
+    contract.errors.map(e => `${e.name} = ${e.num},`),
+    `}`,
+  ];
+}
+
+function withSemicolons(lines: string[]): string[] {
+  return lines.map(line => (line.endsWith(';') ? line : line + ';'));
+}
+
+function printVariables(contract: Contract): string[] {
+  return withSemicolons(contract.variables.map(v => `const ${v.name}: ${v.type} = ${v.value}`));
+}
+
+function printUseClauses(contract: Contract): Lines[] {
+  const useClauses = sortUseClauses(contract);
+
+  // group by containerPath
+  const grouped = useClauses.reduce((result: { [containerPath: string]: UseClause[] }, useClause: UseClause) => {
+    if (useClause.groupable) {
+      (result[useClause.containerPath] = result[useClause.containerPath] || []).push(useClause);
+    } else {
+      (result[STANDALONE_IMPORTS_GROUP] = result[STANDALONE_IMPORTS_GROUP] || []).push(useClause);
+    }
+    return result;
+  }, {});
+
+  const lines = Object.entries(grouped).flatMap(([groupName, group]) => getLinesFromUseClausesGroup(group, groupName));
+  return lines.flatMap(line => splitLongUseClauseLine(line.toString()));
+}
+
+function getLinesFromUseClausesGroup(group: UseClause[], groupName: string): Lines[] {
+  const lines = [];
+  if (groupName === STANDALONE_IMPORTS_GROUP) {
+    for (const useClause of group) {
+      lines.push(`use ${useClause.containerPath}::${nameWithAlias(useClause)};`);
+    }
+  } else {
+    if (group.length == 1) {
+      lines.push(`use ${groupName}::${nameWithAlias(group[0]!)};`);
+    } else if (group.length > 1) {
+      const names = group.map(useClause => nameWithAlias(useClause)).join(', ');
+      lines.push(`use ${groupName}::{${names}};`);
+    }
+  }
+  return lines;
+}
+
+function nameWithAlias(useClause: UseClause): string {
+  return useClause.alias ? `${useClause.name} as ${useClause.alias}` : useClause.name;
+}
+
+// TODO: remove this when we can use a formatting js library
+function splitLongUseClauseLine(line: string): Lines[] {
+  const lines = [];
+
+  const containsBraces = line.indexOf('{') !== -1;
+  if (containsBraces && line.length > MAX_USE_CLAUSE_LINE_LENGTH) {
+    // split at the first brace
+    lines.push(line.slice(0, line.indexOf('{') + 1));
+    lines.push(...splitLongLineInner(line.slice(line.indexOf('{') + 1, -2)));
+    lines.push('};');
+  } else {
+    lines.push(line);
+  }
+  return lines;
+}
+
+function splitLongLineInner(line: string): Lines[] {
+  const lines = [];
+  if (line.length > MAX_USE_CLAUSE_LINE_LENGTH) {
+    const max_accessible_string = line.slice(0, MAX_USE_CLAUSE_LINE_LENGTH);
+    const lastCommaIndex = max_accessible_string.lastIndexOf(',');
+    if (lastCommaIndex !== -1) {
+      lines.push(TAB + max_accessible_string.slice(0, lastCommaIndex + 1));
+      lines.push(...splitLongLineInner(line.slice(lastCommaIndex + 2)));
+    } else {
+      lines.push(TAB + max_accessible_string);
+    }
+  } else {
+    lines.push(TAB + line);
+  }
+  return lines;
+}
+
+function sortUseClauses(contract: Contract): UseClause[] {
+  return contract.useClauses.sort((a, b) => {
+    if (a.containerPath === b.containerPath) {
+      if (a.name === 'self' && b.name !== 'self') {
+        return -1;
+      } else if (a.name !== 'self' && b.name === 'self') {
+        return 1;
+      }
+      return nameWithAlias(a).localeCompare(nameWithAlias(b));
+    } else {
+      return a.containerPath.localeCompare(b.containerPath);
+    }
+  });
+}
+
+function printImplementedTraits(contract: Contract): Lines[] {
+  // sort first by priority, then number of tags, then name
+  const sortedTraits = contract.implementedTraits.sort((a, b) => {
+    if (a.priority !== b.priority) {
+      return (a.priority ?? Infinity) - (b.priority ?? Infinity);
+    }
+    if (a.tags.length !== b.tags.length) {
+      return a.tags.length - b.tags.length;
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  // group by section
+  const grouped = sortedTraits.reduce(
+    (result: { [section: string]: ImplementedTrait[] }, current: ImplementedTrait) => {
+      // default to no section
+      const section = current.section ?? DEFAULT_SECTION;
+      (result[section] = result[section] || []).push(current);
+      return result;
+    },
+    {},
+  );
+
+  const sections = Object.entries(grouped)
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([section, impls]) => printImplementedTraitsSection(section, impls as ImplementedTrait[]));
+
+  return spaceBetween(...sections);
+}
+
+function printImplementedTraitsSection(section: string, impls: ImplementedTrait[]): Lines[] {
+  const lines = [];
+  const isDefaultSection = section === DEFAULT_SECTION;
+  if (!isDefaultSection) {
+    lines.push('//');
+    lines.push(`// ${section}`);
+    lines.push('//');
+  }
+  impls.forEach((trait, index) => {
+    if (index > 0 || !isDefaultSection) {
+      lines.push('');
+    }
+    lines.push(...printImplementedTrait(trait));
+  });
+  return lines;
+}
+
+function printImplementedTrait(trait: ImplementedTrait): Lines[] {
+  const implLines = [];
+  implLines.push(...trait.tags.map(t => `#[${t}]`));
+  implLines.push(`impl ${trait.name} for ${trait.for} {`);
+  const fns = trait.functions.map(fn => printFunction(fn));
+  implLines.push(spaceBetween(...fns));
+  implLines.push('}');
+  return implLines;
+}
+
+function printFunction(fn: ContractFunction): Lines[] {
+  const head = `fn ${fn.name}`;
+  const args = fn.args.map(a => printArgument(a));
+
+  const codeLines = fn.codeBefore?.concat(fn.code) ?? fn.code;
+  for (let i = 0; i < codeLines.length; i++) {
+    const line = codeLines[i];
+    const shouldEndWithSemicolon = i < codeLines.length - 1 || fn.returns === undefined;
+    if (line !== undefined && line.length > 0) {
+      if (shouldEndWithSemicolon && !['{', '}', ';'].includes(line.charAt(line.length - 1))) {
+        codeLines[i] += ';';
+      } else if (!shouldEndWithSemicolon && line.endsWith(';')) {
+        codeLines[i] = line.slice(0, line.length - 1);
+      }
+    }
+  }
+
+  return printFunction2(head, args, fn.tag, fn.returns, undefined, codeLines);
+}
+
+function printContractFunctions(contract: Contract): Lines[] {
+  const implLines = [];
+  implLines.push('#[contractimpl]');
+  implLines.push(`impl ${contract.name} {`);
+  implLines.push(printConstructor(contract));
+  implLines.push('}');
+  return implLines;
+}
+
+function printConstructor(contract: Contract): Lines[] {
+  if (contract.constructorCode.length > 0) {
+    const head = 'pub fn __constructor';
+    const args = [getSelfArg(), ...contract.constructorArgs];
+
+    const body = spaceBetween(withSemicolons(contract.constructorCode));
+
+    const constructor = printFunction2(
+      head,
+      args.map(a => printArgument(a)),
+      undefined,
+      undefined,
+      undefined,
+      body,
+    );
+    return constructor;
+  } else {
+    return [];
+  }
+}
+
+// generic for functions and constructors
+// kindedName = 'fn foo'
+function printFunction2(
+  kindedName: string,
+  args: string[],
+  tag: string | undefined,
+  returns: string | undefined,
+  returnLine: string | undefined,
+  code: Lines[],
+): Lines[] {
+  const fn = [];
+
+  if (tag !== undefined) {
+    fn.push(`#[${tag}]`);
+  }
+
+  let accum = `${kindedName}(`;
+
+  if (args.length > 0) {
+    const formattedArgs = args.join(', ');
+    if (formattedArgs.length > 80) {
+      fn.push(accum);
+      accum = '';
+      // print each arg in a separate line
+      fn.push(args.map(arg => `${arg},`));
+    } else {
+      accum += `${formattedArgs}`;
+    }
+  }
+  accum += ')';
+
+  if (returns === undefined) {
+    accum += ' {';
+  } else {
+    accum += ` -> ${returns} {`;
+  }
+
+  fn.push(accum);
+  fn.push(code);
+  if (returnLine !== undefined) {
+    fn.push([returnLine]);
+  }
+  fn.push('}');
+
+  return fn;
+}
+
+function printArgument(arg: Argument): string {
+  if (arg.type !== undefined) {
+    const type = arg.type;
+    return `${arg.name}: ${type}`;
+  } else {
+    return `${arg.name}`;
+  }
+}

package/src/set-access-control.ts

@@ -0,0 +1,73 @@
+import type { BaseFunction, BaseImplementedTrait, ContractBuilder } from './contract';
+
+export const accessOptions = [false, 'ownable'] as const;
+export const DEFAULT_ACCESS_CONTROL = 'ownable';
+
+export type Access = (typeof accessOptions)[number];
+
+/**
+ * Sets access control for the contract via constructor args.
+ */
+export function setAccessControl(c: ContractBuilder, access: Access): void {
+  switch (access) {
+    case false:
+      break;
+    case 'ownable': {
+      if (!c.ownable) {
+        c.ownable = true;
+        c.addUseClause('soroban_sdk', 'symbol_short');
+        c.addUseClause('soroban_sdk', 'Symbol');
+        c.addVariable({ name: 'OWNER', type: 'Symbol', value: `symbol_short!("OWNER")` });
+        c.addConstructorArgument({ name: 'owner', type: 'Address' });
+        c.addConstructorCode('e.storage().instance().set(&OWNER, &owner);');
+      }
+      break;
+    }
+    default: {
+      const _: never = access;
+      throw new Error('Unknown value for `access`');
+    }
+  }
+}
+
+/**
+ * Enables access control for the contract and restricts the given function with access control.
+ *
+ * If `caller` is provided, requires that the caller is the owner. Otherwise, requires that the owner is authorized.
+ */
+export function requireAccessControl(
+  c: ContractBuilder,
+  trait: BaseImplementedTrait,
+  fn: BaseFunction,
+  access: Access,
+  caller?: string,
+): void {
+  if (access === false) {
+    access = DEFAULT_ACCESS_CONTROL;
+  }
+  setAccessControl(c, access);
+
+  switch (access) {
+    case 'ownable': {
+      c.addUseClause('soroban_sdk', 'Address');
+      const getOwner = 'let owner: Address = e.storage().instance().get(&OWNER).expect("owner should be set");';
+      if (caller) {
+        c.addUseClause('soroban_sdk', 'panic_with_error');
+        c.addError('Unauthorized', 1); // TODO: Ensure there are no conflicts in error codes
+        c.addFunctionCodeBefore(trait, fn, [
+          getOwner,
+          'if owner != caller {',
+          `    panic_with_error!(e, ${c.name}Error::Unauthorized)`,
+          '}',
+        ]);
+      } else {
+        c.addFunctionCodeBefore(trait, fn, [getOwner, 'owner.require_auth();']);
+      }
+      break;
+    }
+    default: {
+      const _: never = access;
+      throw new Error('Unknown value for `access`');
+    }
+  }
+}

package/src/set-info.ts

@@ -0,0 +1,17 @@
+import type { ContractBuilder } from './contract';
+
+export const infoOptions = [{}, { license: 'WTFPL' }] as const;
+
+export const defaults: Info = { license: 'MIT' };
+
+export type Info = {
+  license?: string;
+};
+
+export function setInfo(c: ContractBuilder, info: Info): void {
+  const { license } = info;
+
+  if (license) {
+    c.license = license;
+  }
+}

package/src/test.ts

@@ -0,0 +1,26 @@
+import { promises as fs } from 'fs';
+import os from 'os';
+import type { TestFn, ExecutionContext } from 'ava';
+import _test from 'ava';
+import path from 'path';
+
+import { writeGeneratedSources } from './generate/sources';
+import type { KindedOptions } from './build-generic';
+
+interface Context {
+  generatedSourcesPath: string;
+}
+
+const test = _test as TestFn<Context>;
+
+test.serial('fungible result generated', async t => {
+  await testGenerate(t, 'Fungible');
+});
+
+async function testGenerate(t: ExecutionContext<Context>, kind: keyof KindedOptions) {
+  const generatedSourcesPath = path.join(os.tmpdir(), 'oz-wizard-stellar');
+  await fs.rm(generatedSourcesPath, { force: true, recursive: true });
+  await writeGeneratedSources(generatedSourcesPath, true, kind);
+
+  t.pass();
+}

package/src/utils/convert-strings.ts

@@ -0,0 +1,83 @@
+import { OptionsError } from '../error';
+
+// TODO: Review and convert these to properly handle language restrictions for Stellar
+
+/**
+ * Converts to an identifier according to the rules in https://docs.cairo-lang.org/language_constructs/identifiers.html
+ */
+export function toIdentifier(str: string, capitalize = false): string {
+  const result = str
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // remove accents
+    .replace(/^[^a-zA-Z_]+/, '')
+    .replace(/^(.)/, c => (capitalize ? c.toUpperCase() : c))
+    .replace(/[^\w]+(.?)/g, (_, c) => c.toUpperCase());
+
+  if (result.length === 0) {
+    throw new OptionsError({
+      name: 'Identifier is empty or does not have valid characters',
+    });
+  } else {
+    return result;
+  }
+}
+
+/**
+ * Converts to a ByteArray compatible string literal
+ */
+export function toByteArray(str: string): string {
+  return str
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '') // remove accents
+    .replace(/[^\x20-\x7E]+/g, '') // remove non-ascii-printable characters
+    .replace(/(\\|")/g, (_, c) => '\\' + c); // escape backslash or double quotes
+}
+
+function maxValueOfUint(bits: number): bigint {
+  if (bits <= 0) {
+    throw new Error(`Number of bits must be positive (actual '${bits}').`);
+  }
+  if (bits % 8 !== 0) {
+    throw new Error(`The number of bits must be a multiple of 8 (actual '${bits}').`);
+  }
+  const bytes = bits / 8;
+  return BigInt('0x' + 'ff'.repeat(bytes));
+}
+
+const UINT_MAX_VALUES = {
+  u8: maxValueOfUint(8),
+  u16: maxValueOfUint(16),
+  u32: maxValueOfUint(32),
+  u64: maxValueOfUint(64),
+  u128: maxValueOfUint(128),
+  u256: maxValueOfUint(256),
+} as const;
+
+export type UintType = keyof typeof UINT_MAX_VALUES;
+
+/**
+ * Checks that a string/number value is a valid `uint` value and converts it to bigint
+ */
+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(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);
+}

package/src/utils/define-functions.ts

@@ -0,0 +1,9 @@
+import type { BaseFunction } from '../contract';
+
+type ImplicitNameFunction = Omit<BaseFunction, 'name'>;
+
+export function defineFunctions<F extends string>(fns: Record<F, ImplicitNameFunction>): Record<F, BaseFunction>;
+
+export function defineFunctions(fns: Record<string, ImplicitNameFunction>): Record<string, BaseFunction> {
+  return Object.fromEntries(Object.entries(fns).map(([name, fn]) => [name, Object.assign({ name }, fn)]));
+}

package/src/utils/format-lines.ts

@@ -0,0 +1,26 @@
+export type Lines = string | typeof whitespace | Lines[];
+
+const whitespace = Symbol('whitespace');
+
+export function formatLines(...lines: Lines[]): string {
+  return [...indentEach(0, lines)].join('\n') + '\n';
+}
+
+function* indentEach(indent: number, lines: Lines[]): Generator<string | typeof whitespace> {
+  for (const line of lines) {
+    if (line === whitespace) {
+      yield '';
+    } else if (Array.isArray(line)) {
+      yield* indentEach(indent + 1, line);
+    } else {
+      yield '    '.repeat(indent) + line;
+    }
+  }
+}
+
+export function spaceBetween(...lines: Lines[][]): Lines[] {
+  return lines
+    .filter(l => l.length > 0)
+    .flatMap<Lines>(l => [whitespace, ...l])
+    .slice(1);
+}

package/src/utils/sorted-by.ts

@@ -0,0 +1,3 @@
+export function sortedBy<T>(xs: Iterable<T>, fn: (x: T) => number): T[] {
+  return Array.from(xs).sort((a, b) => fn(a) - fn(b));
+}

package/src/utils/version.ts

@@ -0,0 +1,10 @@
+/**
+ * The actual latest version to use in links.
+ */
+export const contractsVersion = '0.1.0';
+export const contractsVersionTag = `v${contractsVersion}`;
+
+/**
+ * Semantic version string representing of the minimum compatible version of Contracts to display in output.
+ */
+export const compatibleContractsSemver = '^0.1.0';