@openzeppelin/wizard-stellar 0.6.2 → 0.6.4

package/src/api.ts

@@ -1,13 +1,20 @@
 import type { CommonContractOptions, CommonOptions } from './common-options';
+import type { AccountOptions } from './account';
 import type { FungibleOptions } from './fungible';
 import type { GovernorOptions } from './governor';
 import type { NonFungibleOptions } from './non-fungible';
 import type { StablecoinOptions } from './stablecoin';
+import type { VaultOptions } from './vault';
 import {
   printStablecoin,
   defaults as stablecoinDefaults,
   isAccessControlRequired as stablecoinIsAccessControlRequired,
 } from './stablecoin';
+import {
+  printVault,
+  defaults as vaultDefaults,
+  isAccessControlRequired as vaultIsAccessControlRequired,
+} from './vault';
 import {
   printFungible,
   defaults as fungibledefaults,
@@ -23,6 +30,7 @@ import {
   defaults as nonFungibledefaults,
   isAccessControlRequired as nonFungibleIsAccessControlRequired,
 } from './non-fungible';
+import { printAccount, defaults as accountDefaults } from './account';
 
 export interface WizardContractAPI<Options extends CommonOptions> {
   /**
@@ -44,10 +52,21 @@ export interface AccessControlAPI<Options extends CommonContractOptions> {
   isAccessControlRequired: (opts: Partial<Options>) => boolean;
 }
 
+/**
+ * A smart account authorizes everything through `__check_auth` and its context
+ * rules, so it has no `access` option and therefore no `AccessControlAPI`.
+ */
+export type Account = WizardContractAPI<AccountOptions>;
 export type Fungible = WizardContractAPI<FungibleOptions> & AccessControlAPI<FungibleOptions>;
 export type Governor = WizardContractAPI<GovernorOptions> & AccessControlAPI<GovernorOptions>;
 export type NonFungible = WizardContractAPI<NonFungibleOptions> & AccessControlAPI<NonFungibleOptions>;
 export type Stablecoin = WizardContractAPI<StablecoinOptions> & AccessControlAPI<StablecoinOptions>;
+export type Vault = WizardContractAPI<VaultOptions> & AccessControlAPI<VaultOptions>;
+
+export const account: Account = {
+  print: printAccount,
+  defaults: accountDefaults,
+};
 
 export const fungible: Fungible = {
   print: printFungible,
@@ -72,3 +91,9 @@ export const stablecoin: Stablecoin = {
   defaults: stablecoinDefaults,
   isAccessControlRequired: stablecoinIsAccessControlRequired,
 };
+
+export const vault: Vault = {
+  print: printVault,
+  defaults: vaultDefaults,
+  isAccessControlRequired: vaultIsAccessControlRequired,
+};

package/src/build-generic.ts

@@ -1,3 +1,5 @@
+import type { AccountOptions } from './account';
+import { buildAccount } from './account';
 import type { FungibleOptions } from './fungible';
 import { buildFungible } from './fungible';
 import type { GovernorOptions } from './governor';
@@ -6,18 +8,25 @@ import type { NonFungibleOptions } from './non-fungible';
 import { buildNonFungible } from './non-fungible';
 import type { StablecoinOptions } from './stablecoin';
 import { buildStablecoin } from './stablecoin';
+import type { VaultOptions } from './vault';
+import { buildVault } from './vault';
 
 export interface KindedOptions {
+  Account: { kind: 'Account' } & AccountOptions;
   Fungible: { kind: 'Fungible' } & FungibleOptions;
   Governor: { kind: 'Governor' } & GovernorOptions;
   NonFungible: { kind: 'NonFungible' } & NonFungibleOptions;
   Stablecoin: { kind: 'Stablecoin' } & StablecoinOptions;
+  Vault: { kind: 'Vault' } & VaultOptions;
 }
 
 export type GenericOptions = KindedOptions[keyof KindedOptions];
 
 export function buildGeneric(opts: GenericOptions) {
   switch (opts.kind) {
+    case 'Account':
+      return buildAccount(opts);
+
     case 'Fungible':
       return buildFungible(opts);
 
@@ -30,6 +39,9 @@ export function buildGeneric(opts: GenericOptions) {
     case 'Stablecoin':
       return buildStablecoin(opts);
 
+    case 'Vault':
+      return buildVault(opts);
+
     default: {
       const _: never = opts;
       throw new Error('Unknown kind');

package/src/contract.ts

@@ -35,7 +35,11 @@ export interface BaseTraitImplBlock {
   traitName: string;
   structName: string;
   tags: string[];
-  assocType?: string;
+  /**
+   * Associated type bindings for the impl block. An array declares several of
+   * them, one per line (e.g. `CustomAccountInterface`'s `Error` and `Signature`).
+   */
+  assocType?: string | string[];
   section?: string;
   /**
    * Priority for which trait to print first.
@@ -70,6 +74,12 @@ export interface Variable {
 export interface Argument {
   name: string;
   type?: string;
+  /**
+   * Comment lines printed above the argument. Forces one argument per line, so
+   * only worth using where the caller needs guidance that the type cannot carry,
+   * such as where to obtain an address.
+   */
+  comment?: string[];
 }
 
 export class ContractBuilder implements Contract {
@@ -215,7 +225,7 @@ export class ContractBuilder implements Contract {
     return contractFn;
   }
 
-  overrideAssocType(traitName: string, newAssocType: string): void {
+  overrideAssocType(traitName: string, newAssocType: string | string[]): void {
     const trait = this.implementedTraitsMap.get(traitName);
     if (trait) {
       trait.assocType = newAssocType;
@@ -274,6 +284,18 @@ export class ContractBuilder implements Contract {
     this.constructorCode.push(code);
   }
 
+  /**
+   * Appends a block of constructor code verbatim, keeping duplicate lines.
+   *
+   * `addConstructorCode` deduplicates, which is right for the idempotent setup
+   * statements each generator contributes, but wrong for a multi-line block
+   * where lines such as `}` legitimately repeat. Empty entries separate groups
+   * and are printed as blank lines.
+   */
+  addConstructorCodeBlock(lines: string[]): void {
+    this.constructorCode.push(...lines);
+  }
+
   addDerives(derive: string): void {
     this.derivesSet.add(derive);
   }

package/src/generate/account.ts

@@ -0,0 +1,21 @@
+import type { AccountOptions } from '../account';
+import { policyOptions } from '../account';
+import { infoOptions } from '../set-info';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyAccount'],
+  delegatedSigners: booleans,
+  ed25519Signers: booleans,
+  webauthnSigners: booleans,
+  policy: policyOptions,
+  executionEntryPoint: booleans,
+  upgradeable: booleans,
+  info: infoOptions,
+};
+
+export function* generateAccountOptions(): Generator<Required<AccountOptions>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/generate/sources.ts

@@ -2,10 +2,12 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import crypto from 'crypto';
 
+import { generateAccountOptions } from './account';
 import { generateFungibleOptions } from './fungible';
 import { generateGovernorOptions } from './governor';
 import { generateNonFungibleOptions } from './non-fungible';
 import { generateStablecoinOptions } from './stablecoin';
+import { generateVaultOptions } from './vault';
 import type { GenericOptions, KindedOptions } from '../build-generic';
 import { buildGeneric } from '../build-generic';
 import { printContract } from '../print';
@@ -15,6 +17,12 @@ import type { Contract } from '../contract';
 type Kind = keyof KindedOptions;
 
 export function* generateOptions(kind?: Kind): Generator<GenericOptions> {
+  if (!kind || kind === 'Account') {
+    for (const kindOpts of generateAccountOptions()) {
+      yield { kind: 'Account', ...kindOpts };
+    }
+  }
+
   if (!kind || kind === 'Fungible') {
     for (const kindOpts of generateFungibleOptions()) {
       yield { kind: 'Fungible', ...kindOpts };
@@ -38,6 +46,12 @@ export function* generateOptions(kind?: Kind): Generator<GenericOptions> {
       yield { kind: 'Stablecoin', ...kindOpts };
     }
   }
+
+  if (!kind || kind === 'Vault') {
+    for (const kindOpts of generateVaultOptions()) {
+      yield { kind: 'Vault', ...kindOpts };
+    }
+  }
 }
 
 interface GeneratedContract {

package/src/generate/vault.ts

@@ -0,0 +1,21 @@
+import type { VaultOptions } from '../vault';
+import { accessOptions } from '../set-access-control';
+import { infoOptions } from '../set-info';
+import { generateAlternatives } from './alternatives';
+
+const booleans = [true, false];
+
+const blueprint = {
+  name: ['MyVault'],
+  symbol: ['MTK'],
+  decimalsOffset: ['0', '2'],
+  pausable: booleans,
+  upgradeable: booleans,
+  access: accessOptions,
+  info: infoOptions,
+  explicitImplementations: booleans,
+};
+
+export function* generateVaultOptions(): Generator<Required<VaultOptions>> {
+  yield* generateAlternatives(blueprint);
+}

package/src/index.ts

@@ -21,12 +21,16 @@ export { sanitizeKind } from './kind';
 
 export { contractsVersion, contractsVersionTag, compatibleContractsSemver } from './utils/version';
 
+export { account } from './api';
 export { fungible } from './api';
 export { governor } from './api';
 export { nonFungible } from './api';
 export { stablecoin } from './api';
+export { vault } from './api';
 
+export type { AccountOptions, Policy } from './account';
 export type { FungibleOptions } from './fungible';
 export type { GovernorOptions } from './governor';
 export type { NonFungibleOptions } from './non-fungible';
 export type { StablecoinOptions } from './stablecoin';
+export type { VaultOptions } from './vault';

package/src/kind.ts

@@ -14,10 +14,12 @@ export function sanitizeKind(kind: unknown): Kind {
 
 function isKind<T>(value: Kind | T): value is Kind {
   switch (value) {
+    case 'Account':
     case 'Fungible':
     case 'Governor':
     case 'NonFungible':
     case 'Stablecoin':
+    case 'Vault':
       return true;
 
     default: {

package/src/print.ts

@@ -64,8 +64,17 @@ function printContractErrors(contract: Contract): Lines[] {
   ];
 }
 
+// Lines that open, close or continue a block or expression are not statements,
+// so they must not be terminated. Needed by multi-line code such as a `for` loop
+// or a call whose arguments are spread over several lines.
+const CONTINUATION_LINE_ENDINGS = ['{', '}', ';', ',', '('];
+
+function needsSemicolon(line: string): boolean {
+  return line.length > 0 && !CONTINUATION_LINE_ENDINGS.includes(line.at(-1)!);
+}
+
 function withSemicolons(lines: string[]): string[] {
-  return lines.map(line => (line.endsWith(';') ? line : line + ';'));
+  return lines.map(line => (needsSemicolon(line) ? line + ';' : line));
 }
 
 function printVariables(contract: Contract): string[] {
@@ -208,8 +217,11 @@ function printImplementedTrait(trait: TraitImplBlock): Lines[] {
 
   const head = `impl ${trait.traitName} for ${trait.structName}`;
 
-  const assocTypeLines =
-    trait.assocType !== undefined && trait.assocType.trim().length > 0 ? [TAB + trait.assocType.trim(), ''] : [];
+  const assocTypes = (Array.isArray(trait.assocType) ? trait.assocType : [trait.assocType ?? ''])
+    .map(assocType => assocType.trim())
+    .filter(assocType => assocType.length > 0);
+
+  const assocTypeLines = assocTypes.length > 0 ? [...assocTypes.map(assocType => TAB + assocType), ''] : [];
 
   const functionLines = trait.functions.map(fn => printFunction(fn));
 
@@ -234,14 +246,14 @@ function printImplementedTrait(trait: TraitImplBlock): Lines[] {
 
 function printFunction(fn: ContractFunction): Lines[] {
   const head = `fn ${fn.name}`;
-  const args = fn.args.map(a => printArgument(a));
+  const args = printArguments(fn.args);
 
   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))) {
+      if (shouldEndWithSemicolon && needsSemicolon(line)) {
         codeLines[i] += ';';
       } else if (!shouldEndWithSemicolon && line.endsWith(';')) {
         codeLines[i] = line.slice(0, line.length - 1);
@@ -284,17 +296,23 @@ function printConstructor(contract: Contract): Lines[] {
     const head = 'fn __constructor';
     const args = [getSelfArg(), ...contract.constructorArgs];
 
-    const body = spaceBetween(withSemicolons(contract.constructorCode));
-
-    const constructor = printFunction2(
-      true,
-      head,
-      args.map(a => printArgument(a)),
-      [],
-      undefined,
-      undefined,
-      body,
+    // Empty entries separate logical groups of statements. Routing them through
+    // `spaceBetween` yields blank lines with no trailing indentation.
+    const groups = contract.constructorCode.reduce<string[][]>(
+      (acc, line) => {
+        if (line.length === 0) {
+          acc.push([]);
+        } else {
+          acc[acc.length - 1]!.push(line);
+        }
+        return acc;
+      },
+      [[]],
     );
+
+    const body = spaceBetween(...groups.map(group => withSemicolons(group)));
+
+    const constructor = printFunction2(true, head, printArguments(args), [], undefined, undefined, body);
     return constructor;
   } else {
     return [];
@@ -328,11 +346,12 @@ function printFunction2(
 
   if (args.length > 0) {
     const formattedArgs = args.join(', ');
-    if (formattedArgs.length > 80) {
+    // Commented arguments cannot share a line, so they force the expanded form.
+    if (formattedArgs.length > 80 || args.some(isComment)) {
       fn.push(accum);
       accum = '';
       // print each arg in a separate line
-      fn.push(args.map(arg => `${arg},`));
+      fn.push(args.map(arg => (isComment(arg) ? arg : `${arg},`)));
     } else {
       accum += `${formattedArgs}`;
     }
@@ -364,13 +383,23 @@ function printArgument(arg: Argument): string {
   }
 }
 
+// Expands each argument into its comment lines followed by the argument itself.
+// `printFunction2` recognizes the comment entries and leaves them untouched.
+function printArguments(args: Argument[]): string[] {
+  return args.flatMap(arg => [...(arg.comment ?? []).map(line => `// ${line}`), printArgument(arg)]);
+}
+
+function isComment(line: string): boolean {
+  return line.startsWith('//');
+}
+
 function printTopLevelDeclarations(contract: Contract): Lines[] {
   if (contract.topLevelDeclarations.length === 0) return [];
   return spaceBetween(...contract.topLevelDeclarations);
 }
 
 function printDocumentations(documentations: string[]): string[] {
-  return documentations.map(documentation => `//! ${documentation}`);
+  return documentations.map(documentation => (documentation.length > 0 ? `//! ${documentation}` : '//!'));
 }
 
 function printMetadata(contract: Contract) {

package/src/utils/compile-test.ts

@@ -27,6 +27,7 @@ const toCargoPath = (inputPath: string) => inputPath.replace(/\\/g, '/');
 const localDependencies = [
   ['stellar-tokens', 'packages/tokens'],
   ['stellar-access', 'packages/access'],
+  ['stellar-accounts', 'packages/accounts'],
   ['stellar-contract-utils', 'packages/contract-utils'],
   ['stellar-governance', 'packages/governance'],
   ['stellar-macros', 'packages/macros'],
@@ -45,7 +46,11 @@ async function rewriteWorkspaceCargoForLocalContracts(workspaceCargoPath: string
     readFile(upstreamCargoPath, 'utf8'),
   ]);
 
-  const sorobanMatch = upstreamCargo.match(/^\s*soroban-sdk\s*=\s*"([^"]+)"/m);
+  // Match both the bare-string form (`soroban-sdk = "26.1.0"`) and the table
+  // form (`soroban-sdk = { version = "26.1.0", features = [...] }`).
+  const sorobanMatch =
+    upstreamCargo.match(/^\s*soroban-sdk\s*=\s*"([^"]+)"/m) ??
+    upstreamCargo.match(/^\s*soroban-sdk\s*=\s*\{[^}]*?version\s*=\s*"([^"]+)"/m);
   if (sorobanMatch === null || sorobanMatch[1] === undefined) {
     throw new Error(`Unable to find soroban-sdk version in ${upstreamCargoPath}`);
   }