@openzeppelin/wizard-stellar 0.2.3 → 0.4.1

package/src/print.ts

@@ -248,7 +248,7 @@ function printFunction(fn: ContractFunction): Lines[] {
     }
   }
 
-  return printFunction2(fn.pub, head, args, fn.tag, fn.returns, undefined, codeLines);
+  return printFunction2(fn.pub, head, args, fn.tags, fn.returns, undefined, codeLines);
 }
 
 function printContractFunctions(contract: Contract): Lines[] {
@@ -289,7 +289,7 @@ function printConstructor(contract: Contract): Lines[] {
       true,
       head,
       args.map(a => printArgument(a)),
-      undefined,
+      [],
       undefined,
       undefined,
       body,
@@ -306,15 +306,15 @@ function printFunction2(
   pub: boolean | undefined,
   kindedName: string,
   args: string[],
-  tag: string | undefined,
+  tags: string[],
   returns: string | undefined,
   returnLine: string | undefined,
   code: Lines[],
 ): Lines[] {
   const fn = [];
 
-  if (tag !== undefined) {
-    fn.push(`#[${tag}]`);
+  for (let i = 0; i < tags.length; i++) {
+    fn.push(`#[${tags[i]}]`);
   }
 
   let accum = '';

package/src/set-access-control.ts

@@ -1,9 +1,14 @@
 import type { BaseFunction, BaseTraitImplBlock, ContractBuilder } from './contract';
 
-export const accessOptions = [false, 'ownable'] as const;
+export const accessOptions = [false, 'ownable', 'roles'] as const;
 export const DEFAULT_ACCESS_CONTROL = 'ownable';
 
 export type Access = (typeof accessOptions)[number];
+export type AccessProps = {
+  useMacro: boolean;
+  caller?: string;
+  role?: string;
+};
 
 /**
  * Sets access control for the contract via constructor args.
@@ -15,14 +20,40 @@ export function setAccessControl(c: ContractBuilder, access: Access): void {
     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.addUseClause('soroban_sdk', 'Address');
+        c.addUseClause('stellar_contract_utils::ownable', 'self', { alias: 'ownable' });
+        c.addUseClause('stellar_contract_utils::ownable', 'Ownable');
+
+        const ownableTrait = {
+          traitName: 'Ownable',
+          structName: c.name,
+          tags: ['default_impl', 'contractimpl'],
+          section: 'Utils',
+        };
+        c.addTraitImplBlock(ownableTrait);
+
         c.addConstructorArgument({ name: 'owner', type: 'Address' });
-        c.addConstructorCode('e.storage().instance().set(&OWNER, &owner);');
+        c.addConstructorCode('ownable::set_owner(e, &owner);');
       }
       break;
     }
+    case 'roles': {
+      c.addUseClause('soroban_sdk', 'Address');
+      c.addUseClause('stellar_contract_utils::access_control', 'self', { alias: 'access_control' });
+      c.addUseClause('stellar_contract_utils::access_control', 'AccessControl');
+
+      const accessControltrait = {
+        traitName: 'AccessControl',
+        structName: c.name,
+        tags: ['default_impl', 'contractimpl'],
+        section: 'Utils',
+      };
+      c.addTraitImplBlock(accessControltrait);
+
+      c.addConstructorArgument({ name: 'admin', type: 'Address' });
+      c.addConstructorCode('access_control::set_admin(e, &admin);');
+      break;
+    }
     default: {
       const _: never = access;
       throw new Error('Unknown value for `access`');
@@ -32,15 +63,13 @@ export function setAccessControl(c: ContractBuilder, access: Access): void {
 
 /**
  * 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: BaseTraitImplBlock | undefined,
   fn: BaseFunction,
   access: Access,
-  caller?: string,
+  accessProps: AccessProps = { useMacro: true },
 ): void {
   if (access === false) {
     access = DEFAULT_ACCESS_CONTROL;
@@ -49,19 +78,43 @@ export function requireAccessControl(
 
   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(
-          fn,
-          [getOwner, `if owner != ${caller} {`, `    panic_with_error!(e, ${c.name}Error::Unauthorized)`, '}'],
-          trait,
-        );
+      c.addUseClause('stellar_macros', 'only_owner');
+
+      if (accessProps.useMacro) {
+        c.addFunctionTag(fn, 'only_owner', trait);
       } else {
-        c.addFunctionCodeBefore(fn, [getOwner, 'owner.require_auth();'], trait);
+        c.addFunctionCodeBefore(fn, [`ownable::enforce_owner_auth(e);`], trait);
       }
+
+      break;
+    }
+    case 'roles': {
+      const { useMacro, caller, role } = accessProps;
+
+      if (caller && role) {
+        c.addUseClause('soroban_sdk', 'Symbol');
+        c.addConstructorArgument({ name: role, type: 'Address' });
+        c.addConstructorCode(`access_control::grant_role_no_auth(e, &admin, &${role}, &Symbol::new(e, "${role}"));`);
+
+        if (useMacro) {
+          c.addUseClause('stellar_macros', 'only_role');
+          c.addFunctionTag(fn, `only_role(${caller}, "${role}")`, trait);
+        } else {
+          c.addFunctionCodeBefore(
+            fn,
+            [`access_control::ensure_role(e, ${caller}, &Symbol::new(e, "${role}"));`],
+            trait,
+          );
+        }
+      } else {
+        if (useMacro) {
+          c.addUseClause('stellar_macros', 'only_admin');
+          c.addFunctionTag(fn, 'only_admin', trait);
+        } else {
+          c.addFunctionCodeBefore(fn, ['access_control::enforce_admin_auth(e);'], trait);
+        }
+      }
+
       break;
     }
     default: {

package/src/stablecoin.ts

@@ -0,0 +1,124 @@
+import type { Contract, ContractBuilder } from './contract';
+import { defineFunctions } from './utils/define-functions';
+import { getSelfArg } from './common-options';
+import { printContract } from './print';
+import type { FungibleOptions } from './fungible';
+import {
+  buildFungible,
+  defaults as fungibleDefaults,
+  withDefaults as withFungibleDefaults,
+  functions as fungibleFunctions,
+  isAccessControlRequired as fungibleIsAccessControlRequired,
+} from './fungible';
+import { requireAccessControl, type Access } from './set-access-control';
+
+export const defaults: Required<StablecoinOptions> = {
+  ...fungibleDefaults,
+  name: 'MyStablecoin',
+  symbol: 'MST',
+  limitations: false,
+} as const;
+
+export const limitationsOptions = [false, 'allowlist', 'blocklist'] as const;
+
+export function printStablecoin(opts: StablecoinOptions = defaults): string {
+  return printContract(buildStablecoin(opts));
+}
+
+export interface StablecoinOptions extends FungibleOptions {
+  limitations?: false | 'allowlist' | 'blocklist';
+}
+
+function withDefaults(opts: StablecoinOptions): Required<StablecoinOptions> {
+  return {
+    ...withFungibleDefaults(opts),
+    name: opts.name ?? defaults.name,
+    symbol: opts.symbol ?? defaults.symbol,
+    limitations: opts.limitations ?? defaults.limitations,
+  };
+}
+
+export function isAccessControlRequired(opts: Partial<StablecoinOptions>): boolean {
+  return fungibleIsAccessControlRequired(opts) || opts.limitations !== false;
+}
+
+export function buildStablecoin(opts: StablecoinOptions): Contract {
+  const allOpts = withDefaults(opts);
+
+  const c = buildFungible(allOpts);
+
+  if (allOpts.limitations) {
+    addLimitations(c, allOpts.access, allOpts.limitations);
+  }
+
+  return c;
+}
+
+function addLimitations(c: ContractBuilder, access: Access, mode: 'allowlist' | 'blocklist') {
+  const type = mode === 'allowlist';
+
+  const limitationsTrait = {
+    traitName: type ? 'FungibleAllowList' : 'FungibleBlockList',
+    structName: c.name,
+    tags: ['contractimpl'],
+    section: 'Extensions',
+  };
+
+  if (type) {
+    c.addUseClause('stellar_tokens::fungible', 'allowlist::{AllowList, FungibleAllowList}');
+    c.overrideAssocType('FungibleToken', 'type ContractType = AllowList;');
+  } else {
+    c.addUseClause('stellar_tokens::fungible', 'blocklist::{BlockList, FungibleBlockList}');
+    c.overrideAssocType('FungibleToken', 'type ContractType = BlockList;');
+  }
+
+  const [getterFn, addFn, removeFn] = type
+    ? [functions.allowed, functions.allow_user, functions.disallow_user]
+    : [functions.blocked, functions.block_user, functions.unblock_user];
+
+  c.addTraitFunction(limitationsTrait, getterFn);
+
+  const accessProps = {
+    useMacro: true,
+    role: 'manager',
+    caller: 'operator',
+  };
+
+  c.addTraitFunction(limitationsTrait, addFn);
+  requireAccessControl(c, limitationsTrait, addFn, access, accessProps);
+
+  c.addTraitFunction(limitationsTrait, removeFn);
+  requireAccessControl(c, limitationsTrait, removeFn, access, accessProps);
+}
+
+const functions = {
+  ...fungibleFunctions,
+  ...defineFunctions({
+    allowed: {
+      args: [getSelfArg(), { name: 'account', type: 'Address' }],
+      returns: 'bool',
+      code: ['AllowList::allowed(e, &account)'],
+    },
+    allow_user: {
+      args: [getSelfArg(), { name: 'user', type: 'Address' }, { name: 'operator', type: 'Address' }],
+      code: ['AllowList::allow_user(e, &user)'],
+    },
+    disallow_user: {
+      args: [getSelfArg(), { name: 'user', type: 'Address' }, { name: 'operator', type: 'Address' }],
+      code: ['AllowList::disallow_user(e, &user)'],
+    },
+    blocked: {
+      args: [getSelfArg(), { name: 'account', type: 'Address' }],
+      returns: 'bool',
+      code: ['BlockList::blocked(e, &account)'],
+    },
+    block_user: {
+      args: [getSelfArg(), { name: 'user', type: 'Address' }, { name: 'operator', type: 'Address' }],
+      code: ['BlockList::block_user(e, &user)'],
+    },
+    unblock_user: {
+      args: [getSelfArg(), { name: 'user', type: 'Address' }, { name: 'operator', type: 'Address' }],
+      code: ['BlockList::unblock_user(e, &user)'],
+    },
+  }),
+};

package/src/utils/define-functions.ts

@@ -1,9 +1,16 @@
 import type { BaseFunction } from '../contract';
 
-type ImplicitNameFunction = Omit<BaseFunction, 'name'>;
+type OverridableImplicitNameFunction = Omit<BaseFunction, 'name'> & { name?: string };
 
-export function defineFunctions<F extends string>(fns: Record<F, ImplicitNameFunction>): Record<F, BaseFunction>;
+export function defineFunctions<F extends string>(
+  fns: Record<F, OverridableImplicitNameFunction>,
+): 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)]));
+export function defineFunctions(fns: Record<string, OverridableImplicitNameFunction>): Record<string, BaseFunction> {
+  return Object.fromEntries(
+    Object.entries(fns).map(([implicitName, fn]) => [
+      implicitName,
+      Object.assign({ name: fn.name ?? implicitName }, fn),
+    ]),
+  );
 }

package/src/utils/version.ts

@@ -1,13 +1,13 @@
 /**
  * The actual latest version to use in links.
  */
-export const contractsVersion = '0.2.0';
+export const contractsVersion = '0.4.1';
 export const contractsVersionTag = `v${contractsVersion}`;
 
 /**
  * Semantic version string representing of the minimum compatible version of Contracts to display in output.
  */
-export const compatibleContractsSemver = '^0.2.0';
+export const compatibleContractsSemver = '^0.4.1';
 
 /**
  * The Soroban version for which compilation and testing have passing tests

package/src/zip-rust.ts

@@ -4,13 +4,13 @@ import type { Contract } from './contract';
 import { printContract, removeCreateLevelAttributes } from './print';
 import {
   addDependenciesWith,
-  allStellarDependencies,
+  libDependencies,
   contractOptionsToContractName,
   createRustLibFile,
   printContractCargo,
   printRustNameTest,
 } from './zip-shared';
-import { contractsVersionTag, compatibleSorobanVersion } from './utils/version';
+import { contractsVersion, compatibleSorobanVersion } from './utils/version';
 
 const workspaceCargo = `[workspace]
 resolver = "2"
@@ -23,7 +23,7 @@ license = "Apache-2.0"
 version = "0.0.1"
 
 [workspace.dependencies]
-${addDependenciesWith(`{ git = "https://github.com/OpenZeppelin/stellar-contracts", tag = "${contractsVersionTag}" }`, allStellarDependencies)}${addDependenciesWith(`{ version = "${compatibleSorobanVersion}" }`, ['soroban'])}
+${addDependenciesWith(`"${compatibleSorobanVersion}"`, ['soroban-sdk'])}${addDependenciesWith(`"=${contractsVersion}"`, [...libDependencies])}
 `;
 
 const readme = `\
@@ -41,7 +41,7 @@ Continue your development journey with [Stellar CLI](https://github.com/stellar/
 - See [Git installation guide](https://github.com/git-guides/install-git).
 `;
 
-export async function zipRust(c: Contract, opts: GenericOptions) {
+export const createRustZipEnvironment = (c: Contract, opts: GenericOptions) => {
   const zip = new JSZip();
 
   const contractName = contractOptionsToContractName(opts?.kind || 'contract');
@@ -51,7 +51,11 @@ export async function zipRust(c: Contract, opts: GenericOptions) {
   zip.file(`contracts/${contractName}/src/lib.rs`, createRustLibFile);
   zip.file(`contracts/${contractName}/Cargo.toml`, printContractCargo(contractName));
   zip.file('Cargo.toml', workspaceCargo);
-  zip.file('README.md', readme);
 
   return zip;
-}
+};
+
+const addRustProjectReadme = (zip: JSZip) => zip.file('README.md', readme);
+
+export const zipRustProject = async (c: Contract, opts: GenericOptions) =>
+  addRustProjectReadme(createRustZipEnvironment(c, opts));

package/src/zip-scaffold.ts

@@ -1,138 +1,14 @@
-import JSZip from 'jszip';
+import type JSZip from 'jszip';
 import type { GenericOptions } from './build-generic';
 import type { Contract } from './contract';
-import { printContract, removeCreateLevelAttributes } from './print';
-import { compatibleSorobanVersion, contractsVersionTag } from './utils/version';
-import {
-  addDependenciesWith,
-  allStellarDependencies,
-  contractOptionsToContractName,
-  createRustLibFile,
-  printContractCargo,
-  printRustNameTest,
-} from './zip-shared';
+import { createRustZipEnvironment } from './zip-rust';
 
-function getAddressArgs(c: Contract): string[] {
-  return c.constructorArgs
-    .filter(constructorArg => constructorArg.type?.toLowerCase() === 'address')
-    .map(constructorArg => constructorArg.name);
-}
-
-const setupSh = (c: Contract, opts: GenericOptions, scaffoldContractName: string) => {
-  const environmentsFileUpdate = (setUpContract: Contract, setUpScaffoldContractName: string) => `
-# Update environments.toml: remove original contracts and insert wizard's contract
-setup_environment() {
-  local file="environments.toml"
-  local temp
-  temp="$(mktemp)"
-
-  local in_dev_contracts=0
-  local skip_entry=0
-  local contract_entry_inserted=0
-  insert_contract_entry() {
-    {
-      printf '%s\\n' "[development.contracts.${setUpScaffoldContractName}_contract]" \\
-        "client = true" "" \\
-        "# If your contract has a \\\`__constructor\\\`, specify your arguments to it here." \\
-        "# These are the same arguments you could pass after the \\\`--\\\` in a call to" \\
-        "# \\\`stellar contract deploy\\\`" \\
-        "# Only available in \\\`development\\\` and \\\`test\\\` environments" \\
-        ${
-          setUpContract.constructorArgs.length
-            ? // Mind the spacing
-              `"# TODO add appropriate values for for the constructors arguments" \\
-        "constructor_args = \\"\\"\\"" \\
-        "${setUpContract.constructorArgs.map(constructorArg => `--${constructorArg.name} \\"ADD_${constructorArg.name.toLocaleUpperCase()}_${constructorArg.type?.toLocaleUpperCase() || 'ARGUMENT'}_HERE\\"`).join(' ')}" \\
-        "\\"\\"\\"" \\
-        ""`
-            : '""'
-        }
-    } >> "$temp"
-  }
-
-  while IFS= read -r line; do
-    if [[ $contract_entry_inserted -eq 0 && $line == '[staging.network]' ]]; then
-      insert_contract_entry
-      contract_entry_inserted=1
-    fi
-
-    if [[ $line =~ ^\\[development\\.contracts\\]$ ]]; then
-      printf '%s\\n' "$line" >> "$temp"
-      in_dev_contracts=1
-      skip_entry=0
-      continue
-    fi
-
-    if [[ $line =~ ^\\[[^]]+\\]$ ]]; then
-      if (( in_dev_contracts )) && [[ $line =~ ^\\[development\\.contracts\\..+\\]$ ]]; then
-        skip_entry=1
-        in_dev_contracts=0
-        continue
-      fi
-      in_dev_contracts=0
-      skip_entry=0
-      printf '%s\\n' "$line" >> "$temp"
-      continue
-    fi
-
-    if (( skip_entry )); then
-      continue
-    fi
-
-    if (( in_dev_contracts )); then
-      if [[ $line =~ ^[[:space:]]*# ]]; then
-        printf '%s\\n' "$line" >> "$temp"
-      fi
-      continue
-    fi
-
-    printf '%s\\n' "$line" >> "$temp"
-  done < "$file"
-
-  mv "$temp" "$file"
-}
-`;
-
-  const updateWorkspaceCargo = `update_cargo() {
-  cp Cargo.toml Cargo.toml.bak
-
-  cat <<EOF > deps.tmp
-${addDependenciesWith(`{ git = "https://github.com/OpenZeppelin/stellar-contracts", tag = "${contractsVersionTag}" }`, allStellarDependencies)}${addDependenciesWith(`{ version = "${compatibleSorobanVersion}" }`, ['soroban'])}
-EOF
-
-  awk '
-    BEGIN {
-      inserted = 0
-      deps = ""
-      while ((getline line < "deps.tmp") > 0) {
-        deps = deps line "\\n"
-      }
-      close("deps.tmp")
-    }
-    /^\\[workspace.dependencies\\]/ {
-      in_deps = 1
-      print
-      if (!inserted) {
-        printf "%s", deps
-        inserted = 1
-      }
-      next
-    }
-    /^\\[/ { in_deps = 0 }
-    in_deps { next }
-    { print }
-  ' Cargo.toml.bak > Cargo.toml
-
-  rm deps.tmp
-  rm Cargo.toml.bak
-}`;
-
-  return `\
+const setupSh = `\
 #!/usr/bin/env bash
 #
 # setup.sh
-# 
-# This script is meant to set up a Scaffold project and insert the Wizard's contracts in the project
+#
+# This script is meant to set up a Scaffold project with the Wizard's contracts
 
 check_is_installed() {
   if ! which "$1" &> /dev/null; then
@@ -143,18 +19,7 @@ check_is_installed() {
 }
 
 scaffold() {
-  tmp_folder="tmp"
-  stellar scaffold init "$tmp_folder"
-
-  rm -rf "$tmp_folder/contracts"
-
-  local current_directory
-  current_directory="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-
-  shopt -s dotglob
-
-  cp -a "$current_directory/$tmp_folder"/. "$current_directory"/
-  rm -rf "$current_directory/$tmp_folder"
+  stellar-scaffold upgrade
 }
 
 init_git(){
@@ -163,10 +28,6 @@ init_git(){
   git commit -m "openzeppelin: add wizard output" --quiet
 }
 
-${environmentsFileUpdate(c, scaffoldContractName)}
-
-${updateWorkspaceCargo}
-
 build_contracts() {
   cargo build
 }
@@ -196,10 +57,6 @@ then
   echo "🏗️ Building Scaffold project"
 
   scaffold
-  
-  setup_environment
-
-  update_cargo
 
   build_contracts
 
@@ -212,15 +69,11 @@ else
   echo "✅ Scaffold project already initialized."
 fi
 `;
-};
-
-const readme = (c: Contract) => {
-  const hasTodosToResolve = (c: Contract) => getAddressArgs(c).length > 0;
 
-  return `\
+const wizardReadme = `\
 # Sample Scaffold Project
 
-This project demonstrates a basic Scaffold use case. It comes with a contract generated by [OpenZeppelin Wizard](https://wizard.openzeppelin.com/), a test for that contract, and a script that initiate a Stellar Scaffold project with this contract. [Scaffold Stellar](https://github.com/AhaLabs/scaffold-stellar?tab=readme-ov-file#scaffold-stellar) is a convention-over-configuration toolkit for blockchain and distributed application development on the Stellar network. It provides a seamless development experience through CLI tools, smart contract management, and deployment utilities.
+This project demonstrates a basic Scaffold use case. It comes with a contract generated by [OpenZeppelin Wizard](https://wizard.openzeppelin.com/), a test for that contract, and a script that initiates a Stellar Scaffold project with this contract. [Scaffold Stellar](https://github.com/AhaLabs/scaffold-stellar?tab=readme-ov-file#scaffold-stellar) is a convention-over-configuration toolkit for blockchain and distributed application development on the Stellar network. It provides a seamless development experience through CLI tools, smart contract management, and deployment utilities.
 
 ## Installing dependencies
 
@@ -235,7 +88,6 @@ This project demonstrates a basic Scaffold use case. It comes with a contract ge
 \`\`\`
 bash setup.sh
 \`\`\`
-${hasTodosToResolve(c) ? '\n## Resolve any TODOs \n\nSearch for any TODO comments in the project and resolve them (search for TODO with your code editor).\n' : ''}
 
 ## Testing the contract
 
@@ -255,19 +107,13 @@ stellar scaffold watch --build-clients
 npm run dev
 \`\`\`
 `;
-};
-
-export async function zipScaffold(c: Contract, opts: GenericOptions) {
-  const zip = new JSZip();
 
-  const scaffoldContractName = contractOptionsToContractName(opts?.kind || 'contract');
-
-  zip.file(`contracts/${scaffoldContractName}/src/contract.rs`, removeCreateLevelAttributes(printContract(c)));
-  zip.file(`contracts/${scaffoldContractName}/src/test.rs`, printRustNameTest(c));
-  zip.file(`contracts/${scaffoldContractName}/src/lib.rs`, createRustLibFile);
-  zip.file(`contracts/${scaffoldContractName}/Cargo.toml`, printContractCargo(scaffoldContractName));
-  zip.file('setup.sh', setupSh(c, opts, scaffoldContractName));
-  zip.file('README-WIZARD.md', readme(c));
+const addScaffoldProjectFiles = (zip: JSZip) => {
+  zip.file('README-WIZARD.md', wizardReadme);
+  zip.file('setup.sh', setupSh);
 
   return zip;
-}
+};
+
+export const zipScaffoldProject = async (c: Contract, opts: GenericOptions) =>
+  addScaffoldProjectFiles(createRustZipEnvironment(c, opts));