@openzeppelin/wizard-stellar 0.6.3 → 0.6.4

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,6 +2,7 @@ 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';
@@ -16,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 };

package/src/index.ts

@@ -21,12 +21,14 @@ 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';

package/src/kind.ts

@@ -14,6 +14,7 @@ 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':

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'],

package/src/zip-rust.ts

@@ -1,4 +1,5 @@
 import JSZip from 'jszip';
+import { defaults as accountDefaults } from './account';
 import type { GenericOptions } from './build-generic';
 import type { Contract } from './contract';
 import { printContract, removeCreateLevelAttributes } from './print';
@@ -6,6 +7,7 @@ import {
   contractOptionsToContractName,
   createRustLibFile,
   getRequiredLibDependencies,
+  printAccountRustTest,
   printContractCargo,
   printRustNameTest,
   printVaultRustTest,
@@ -31,6 +33,19 @@ const gitIgnore = `\
 target/
 `;
 
+// Most contracts get the generic name assertion; kinds whose constructor takes
+// more than plain addresses need a template that can satisfy it.
+const printTest = (c: Contract, opts: GenericOptions) => {
+  switch (opts?.kind) {
+    case 'Account':
+      return printAccountRustTest(c, opts.policy ?? accountDefaults.policy);
+    case 'Vault':
+      return printVaultRustTest(c);
+    default:
+      return printRustNameTest(c);
+  }
+};
+
 export const createRustZipEnvironment = (c: Contract, opts: GenericOptions) => {
   const zip = new JSZip();
 
@@ -38,10 +53,7 @@ export const createRustZipEnvironment = (c: Contract, opts: GenericOptions) => {
   const requiredLibDeps = getRequiredLibDependencies(c);
 
   zip.file(`contracts/${contractName}/src/contract.rs`, removeCreateLevelAttributes(printContract(c)));
-  zip.file(
-    `contracts/${contractName}/src/test.rs`,
-    opts?.kind === 'Vault' ? printVaultRustTest(c) : printRustNameTest(c),
-  );
+  zip.file(`contracts/${contractName}/src/test.rs`, printTest(c, opts));
   zip.file(`contracts/${contractName}/src/lib.rs`, createRustLibFile);
   zip.file(`contracts/${contractName}/Cargo.toml`, printContractCargo(contractName, requiredLibDeps));
   zip.file('Cargo.toml', workspaceCargo(requiredLibDeps));

package/src/zip-shared.ts

@@ -101,9 +101,240 @@ fn initial_state() {
 `;
 };
 
+// A smart account contacts its policy and verifier contracts while it is being
+// constructed: `add_context_rule` installs every policy and canonicalizes every
+// external signer key through its verifier. A test that registers the account
+// therefore needs real contracts at those addresses, so the mocks below wrap the
+// library's own logic, the same way the reference examples do.
+const accountPolicies = {
+  'simple-threshold': {
+    struct: 'MockSimpleThresholdPolicy',
+    module: 'simple_threshold',
+    params: 'SimpleThresholdAccountParams',
+  },
+  'weighted-threshold': {
+    struct: 'MockWeightedThresholdPolicy',
+    module: 'weighted_threshold',
+    params: 'WeightedThresholdAccountParams',
+  },
+} as const;
+
+export type AccountPolicy = keyof typeof accountPolicies | false;
+
+// How many of each signer type the generated test deploys with. `weights` must
+// have one entry per assembled signer, so the counts drive that too.
+const testSignerCounts = {
+  delegated_signers: 2,
+  ed25519_keys: 1,
+  webauthn_keys: 1,
+} as const;
+
+const testConstructorArgValues: Record<string, (signerCount: number) => string> = {
+  delegated_signers: () => 'Vec::from_array(&env, [Address::generate(&env), Address::generate(&env)])',
+  ed25519_verifier: () => 'ed25519_verifier',
+  ed25519_keys: () => 'Vec::from_array(&env, [Bytes::from_slice(&env, &[1u8; 32])])',
+  webauthn_verifier: () => 'webauthn_verifier',
+  // A WebAuthn key is the 65-byte secp256r1 public key followed by an optional
+  // credential id; canonicalization reads the first 65 bytes.
+  webauthn_keys: () => 'Vec::from_array(&env, [Bytes::from_slice(&env, &[2u8; 65])])',
+  weights: signerCount => `Vec::from_array(&env, [${Array<string>(signerCount).fill('1u32').join(', ')}])`,
+  threshold: () => '1u32',
+  threshold_policy: () => 'policy',
+};
+
+const MOCK_ED25519_VERIFIER = `
+// Minimal Ed25519 verifier contract, for testing purposes only: a real
+// deployment passes the address of a verifier contract it trusts.
+#[contract]
+pub struct MockEd25519Verifier;
+
+#[contractimpl]
+impl Verifier for MockEd25519Verifier {
+    type KeyData = BytesN<32>;
+    type SigData = BytesN<64>;
+
+    fn verify(
+        e: &Env,
+        signature_payload: Bytes,
+        key_data: BytesN<32>,
+        sig_data: BytesN<64>,
+    ) -> bool {
+        ed25519::verify(e, &signature_payload, &key_data, &sig_data)
+    }
+
+    fn canonicalize_key(e: &Env, key_data: BytesN<32>) -> Bytes {
+        ed25519::canonicalize_key(e, &key_data)
+    }
+
+    fn batch_canonicalize_key(e: &Env, keys_data: Vec<BytesN<32>>) -> Vec<Bytes> {
+        ed25519::batch_canonicalize_key(e, &keys_data)
+    }
+}
+`;
+
+const MOCK_WEBAUTHN_VERIFIER = `
+// Minimal WebAuthn (passkey) verifier contract, for testing purposes only: a
+// real deployment passes the address of a verifier contract it trusts.
+#[contract]
+pub struct MockWebauthnVerifier;
+
+#[contractimpl]
+impl Verifier for MockWebauthnVerifier {
+    type KeyData = Bytes;
+    type SigData = Bytes;
+
+    fn verify(e: &Env, signature_payload: Bytes, key_data: Bytes, sig_data: Bytes) -> bool {
+        let sig_struct =
+            WebAuthnSigData::from_xdr(e, &sig_data).expect("WebAuthnSigData with correct format");
+        let pub_key: BytesN<65> =
+            extract_from_bytes(e, &key_data, 0..65).expect("65-byte public key to be extracted");
+
+        webauthn::verify(e, &signature_payload, &pub_key, &sig_struct)
+    }
+
+    fn canonicalize_key(e: &Env, key_data: Bytes) -> Bytes {
+        webauthn::canonicalize_key(e, &key_data)
+    }
+
+    fn batch_canonicalize_key(e: &Env, keys_data: Vec<Bytes>) -> Vec<Bytes> {
+        webauthn::batch_canonicalize_key(e, &keys_data)
+    }
+}
+`;
+
+const printMockPolicyContract = (policy: keyof typeof accountPolicies) => {
+  const { struct, module, params } = accountPolicies[policy];
+
+  return `
+// Minimal policy contract, for testing purposes only: the account installs its
+// policies during construction, so the test needs one deployed at that address.
+// A real deployment passes the address of a policy contract it trusts.
+#[contract]
+pub struct ${struct};
+
+#[contractimpl]
+impl Policy for ${struct} {
+    type AccountParams = ${module}::${params};
+
+    fn enforce(
+        e: &Env,
+        context: Context,
+        authenticated_signers: Vec<Signer>,
+        context_rule: ContextRule,
+        smart_account: Address,
+    ) {
+        ${module}::enforce(e, &context, &authenticated_signers, &context_rule, &smart_account)
+    }
+
+    fn install(
+        e: &Env,
+        install_params: Self::AccountParams,
+        context_rule: ContextRule,
+        smart_account: Address,
+    ) {
+        ${module}::install(e, &install_params, &context_rule, &smart_account)
+    }
+
+    fn uninstall(e: &Env, context_rule: ContextRule, smart_account: Address) {
+        ${module}::uninstall(e, &context_rule, &smart_account)
+    }
+}
+`;
+};
+
+export const printAccountRustTest = (c: Pick<Contract, 'constructorArgs' | 'name'>, policy: AccountPolicy) => {
+  const argNames = (c.constructorArgs || []).map(arg => arg.name);
+  const signerCount = Object.entries(testSignerCounts).reduce(
+    (total, [argName, count]) => (argNames.includes(argName) ? total + count : total),
+    0,
+  );
+
+  const hasEd25519 = argNames.includes('ed25519_keys');
+  const hasWebauthn = argNames.includes('webauthn_keys');
+  const hasPolicy = policy !== false;
+
+  // Every argument is spelled on its own line: the assembled tuple is otherwise
+  // far too long to read.
+  const registerArgs = argNames
+    .map(argName => `            ${testConstructorArgValues[argName]!(signerCount)},`)
+    .join('\n');
+
+  const hasMocks = hasEd25519 || hasWebauthn || hasPolicy;
+
+  const sorobanImports = [
+    ...(hasPolicy ? ['auth::Context'] : []),
+    ...(hasMocks ? ['contract', 'contractimpl'] : []),
+    'testutils::Address as _',
+    ...(hasWebauthn ? ['xdr::FromXdr'] : []),
+    'Address',
+    ...(hasEd25519 || hasWebauthn ? ['Bytes', 'BytesN'] : []),
+    'Env',
+    'Vec',
+  ];
+
+  // Kept on separate lines so that enabling both verifiers does not import
+  // `Verifier` twice.
+  const libImports = [
+    ...(hasPolicy
+      ? [
+          `use stellar_accounts::policies::{ ${accountPolicies[policy].module}, Policy };`,
+          'use stellar_accounts::smart_account::{ ContextRule, Signer };',
+        ]
+      : []),
+    ...(hasEd25519 || hasWebauthn ? ['use stellar_accounts::verifiers::Verifier;'] : []),
+    ...(hasEd25519 ? ['use stellar_accounts::verifiers::ed25519;'] : []),
+    ...(hasWebauthn
+      ? [
+          'use stellar_accounts::verifiers::utils::extract_from_bytes;',
+          'use stellar_accounts::verifiers::webauthn::{ self, WebAuthnSigData };',
+        ]
+      : []),
+  ];
+
+  const mockContracts = [
+    ...(hasEd25519 ? [MOCK_ED25519_VERIFIER] : []),
+    ...(hasWebauthn ? [MOCK_WEBAUTHN_VERIFIER] : []),
+    ...(hasPolicy ? [printMockPolicyContract(policy)] : []),
+  ];
+
+  const registrations = [
+    ...(hasEd25519 ? ['    let ed25519_verifier = env.register(MockEd25519Verifier, ());'] : []),
+    ...(hasWebauthn ? ['    let webauthn_verifier = env.register(MockWebauthnVerifier, ());'] : []),
+    ...(hasPolicy ? [`    let policy = env.register(${accountPolicies[policy].struct}, ());`] : []),
+  ];
+
+  return `#![cfg(test)]
+
+extern crate std;
+
+use soroban_sdk::{ ${sorobanImports.join(', ')} };
+${libImports.map(libImport => `${libImport}\n`).join('')}
+use crate::contract::{ ${c.name}, ${c.name}Client };
+${mockContracts.join('')}
+#[test]
+fn initial_state() {
+    let env = Env::default();
+${hasPolicy ? '    env.mock_all_auths();\n' : ''}
+${registrations.map(registration => `${registration}\n`).join('')}
+    let contract_addr = env.register(
+        ${c.name},
+        (
+${registerArgs}
+        ),
+    );
+    let client = ${c.name}Client::new(&env, &contract_addr);
+
+    assert_eq!(client.get_context_rules_count(), 1);
+}
+
+// Add more tests below
+`;
+};
+
 const libDependencies = [
   'stellar-tokens',
   'stellar-access',
+  'stellar-accounts',
   'stellar-contract-utils',
   'stellar-governance',
   'stellar-macros',