@openzeppelin/wizard-stellar 0.2.2 → 0.3.0

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_ownable', 'self', { alias: 'ownable' });
+        c.addUseClause('stellar_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_access_control', 'self', { alias: 'access_control' });
+      c.addUseClause('stellar_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_ownable_macro', '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_access_control_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_access_control_macros', 'only_admin');
+          c.addFunctionTag(fn, 'only_admin', trait);
+        } else {
+          c.addFunctionCodeBefore(fn, ['access_control::enforce_admin_auth(e);'], trait);
+        }
+      }
+
       break;
     }
     default: {

package/src/set-info.ts

@@ -1,15 +1,22 @@
 import type { ContractBuilder } from './contract';
 
+export const TAG_SECURITY_CONTACT = `@custom:security-contact`;
+
 export const infoOptions = [{}, { license: 'WTFPL' }] as const;
 
 export const defaults: Info = { license: 'MIT' };
 
 export type Info = {
   license?: string;
+  securityContact?: string;
 };
 
 export function setInfo(c: ContractBuilder, info: Info): void {
-  const { license } = info;
+  const { securityContact, license } = info;
+
+  if (securityContact) {
+    c.addSecurityTag(securityContact);
+  }
 
   if (license) {
     c.license = license;

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_fungible', 'allowlist::{AllowList, FungibleAllowList}');
+    c.overrideAssocType('FungibleToken', 'type ContractType = AllowList;');
+  } else {
+    c.addUseClause('stellar_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.3.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.2.0';
+export const compatibleContractsSemver = '^0.3.0';
 
 /**
  * The Soroban version for which compilation and testing have passing tests

package/src/zip-rust.ts

@@ -0,0 +1,57 @@
+import JSZip from 'jszip';
+import type { GenericOptions } from './build-generic';
+import type { Contract } from './contract';
+import { printContract, removeCreateLevelAttributes } from './print';
+import {
+  addDependenciesWith,
+  allStellarDependencies,
+  contractOptionsToContractName,
+  createRustLibFile,
+  printContractCargo,
+  printRustNameTest,
+} from './zip-shared';
+import { contractsVersionTag, compatibleSorobanVersion } from './utils/version';
+
+const workspaceCargo = `[workspace]
+resolver = "2"
+members = ["contracts/*"]
+
+[workspace.package]
+authors = []
+edition = "2021"
+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'])}
+`;
+
+const readme = `\
+# Sample Rust Contract Environment
+
+This project demonstrates a basic Rust contract environment use case. It comes with a contract generated by [OpenZeppelin Wizard](https://wizard.openzeppelin.com/) and a test for that contract. Make sure you have the required dependencies and keep building!
+
+## Go further
+
+Continue your development journey with [Stellar CLI](https://github.com/stellar/stellar-cli).
+
+## Installing dependencies
+
+- See [Rust and Stellar installation guide](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup).
+- See [Git installation guide](https://github.com/git-guides/install-git).
+`;
+
+export async function zipRust(c: Contract, opts: GenericOptions) {
+  const zip = new JSZip();
+
+  const contractName = contractOptionsToContractName(opts?.kind || 'contract');
+
+  zip.file(`contracts/${contractName}/src/contract.rs`, removeCreateLevelAttributes(printContract(c)));
+  zip.file(`contracts/${contractName}/src/test.rs`, printRustNameTest(c));
+  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;
+}

package/src/zip-scaffold.ts

@@ -3,82 +3,14 @@ import type { GenericOptions } from './build-generic';
 import type { Contract } from './contract';
 import { printContract, removeCreateLevelAttributes } from './print';
 import { compatibleSorobanVersion, contractsVersionTag } from './utils/version';
-
-const dependencies = {
-  base: ['stellar-default-impl-macro'],
-  fungible: ['stellar-fungible'],
-  nonFungible: ['stellar-non-fungible'],
-  pausable: ['stellar-pausable', 'stellar-pausable-macros'],
-  upgradable: ['stellar-upgradeable', 'stellar-upgradeable-macros'],
-  soroban: ['soroban-sdk'],
-} as const;
-
-const addDependenciesWith = (dependencyValue: string, dependenciesToAdd: (keyof typeof dependencies)[]) =>
-  dependenciesToAdd.reduce((addedDependency, dependencyName) => {
-    return `${addedDependency}${dependencies[dependencyName].map(cargoDependencies => `${cargoDependencies} = ${dependencyValue}\n`).join('')}`;
-  }, '');
-
-const getDependenciesToAdd = (opts: GenericOptions): (keyof typeof dependencies)[] => {
-  const dependenciesToAdd: (keyof typeof dependencies)[] = ['base'];
-
-  if (opts.kind === 'Fungible') dependenciesToAdd.push('fungible');
-  if (opts.kind === 'NonFungible') dependenciesToAdd.push('nonFungible');
-  if (opts.pausable) dependenciesToAdd.push('pausable');
-  if (opts.upgradeable) dependenciesToAdd.push('upgradable');
-
-  return dependenciesToAdd;
-};
-
-const test = (c: Contract) => `#![cfg(test)]
-
-extern crate std;
-
-use soroban_sdk::{ ${getAddressArgs(c).length ? 'testutils::Address as _, Address, ' : ''}Env, String };
-
-use crate::contract::{ ${c.name}, ${c.name}Client };
-
-#[test]
-fn initial_state() {
-    let env = Env::default();
-
-    let contract_addr = env.register(${c.name}, (${getAddressArgs(c)
-      .map(() => 'Address::generate(&env)')
-      .join(',')}${getAddressArgs(c).length === 1 ? ',' : ''}));
-    let client = ${c.name}Client::new(&env, &contract_addr);
-
-    assert_eq!(client.name(), String::from_str(&env, "${c.name}"));
-}
-
-// Add more tests bellow
-`;
-
-function contractCargo(opts: GenericOptions, scaffoldContractName: string) {
-  return `[package]
-name = "${scaffoldContractName.replace(/_/, '-')}-contract"
-edition.workspace = true
-license.workspace = true
-publish = false
-version.workspace = true
-
-[lib]
-crate-type = ["cdylib"]
-doctest = false
-
-[dependencies]
-${addDependenciesWith('{ workspace = true }', [...getDependenciesToAdd(opts), 'soroban'])}
-[dev-dependencies]
-${addDependenciesWith('{ workspace = true, features = ["testutils"] }', ['soroban'])}
-`;
-}
-
-function pascalToSnakeCase(string: string) {
-  return string
-    .replace(/([A-Z])/g, '_$1')
-    .replace(/^_/, '')
-    .toLowerCase();
-}
-
-export const contractOptionsToScaffoldContractName = pascalToSnakeCase;
+import {
+  addDependenciesWith,
+  allStellarDependencies,
+  contractOptionsToContractName,
+  createRustLibFile,
+  printContractCargo,
+  printRustNameTest,
+} from './zip-shared';
 
 function getAddressArgs(c: Contract): string[] {
   return c.constructorArgs
@@ -161,11 +93,11 @@ setup_environment() {
 }
 `;
 
-  const updateWorkspaceCargo = (opts: GenericOptions) => `update_cargo() {
+  const updateWorkspaceCargo = `update_cargo() {
   cp Cargo.toml Cargo.toml.bak
 
   cat <<EOF > deps.tmp
-${addDependenciesWith(`{ git = "https://github.com/OpenZeppelin/stellar-contracts", tag = "${contractsVersionTag}" }`, getDependenciesToAdd(opts))}${addDependenciesWith(`{ version = "${compatibleSorobanVersion}" }`, ['soroban'])}
+${addDependenciesWith(`{ git = "https://github.com/OpenZeppelin/stellar-contracts", tag = "${contractsVersionTag}" }`, allStellarDependencies)}${addDependenciesWith(`{ version = "${compatibleSorobanVersion}" }`, ['soroban'])}
 EOF
 
   awk '
@@ -233,7 +165,7 @@ init_git(){
 
 ${environmentsFileUpdate(c, scaffoldContractName)}
 
-${updateWorkspaceCargo(opts)}
+${updateWorkspaceCargo}
 
 build_contracts() {
   cargo build
@@ -293,7 +225,7 @@ This project demonstrates a basic Scaffold use case. It comes with a contract ge
 ## Installing dependencies
 
 - See [Git installation guide](https://github.com/git-guides/install-git).
-- See [Rust installation guide](https://www.rust-lang.org/tools/install).
+- See [Rust and Stellar installation guide](https://developers.stellar.org/docs/build/smart-contracts/getting-started/setup).
 - See [Scaffold CLI installation guide](https://github.com/AhaLabs/scaffold-stellar?tab=readme-ov-file#quick-start).
 - See [Docker installation guide](https://docs.docker.com/engine/install/).
 - See [Node installation guide](https://nodejs.org/en/download).
@@ -325,22 +257,15 @@ npm run dev
 `;
 };
 
-const createLib = `#![no_std]
-#![allow(dead_code)]
-
-mod contract;
-mod test;
-`;
-
 export async function zipScaffold(c: Contract, opts: GenericOptions) {
   const zip = new JSZip();
 
-  const scaffoldContractName = contractOptionsToScaffoldContractName(opts?.kind || 'contract');
+  const scaffoldContractName = contractOptionsToContractName(opts?.kind || 'contract');
 
   zip.file(`contracts/${scaffoldContractName}/src/contract.rs`, removeCreateLevelAttributes(printContract(c)));
-  zip.file(`contracts/${scaffoldContractName}/src/test.rs`, test(c));
-  zip.file(`contracts/${scaffoldContractName}/src/lib.rs`, createLib);
-  zip.file(`contracts/${scaffoldContractName}/Cargo.toml`, contractCargo(opts, scaffoldContractName));
+  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));
 

package/src/zip-shared.ts

@@ -0,0 +1,85 @@
+import type { Contract } from './contract';
+
+function pascalToSnakeCase(string: string) {
+  return string
+    .replace(/([A-Z])/g, '_$1')
+    .replace(/^_/, '')
+    .toLowerCase();
+}
+
+export const contractOptionsToContractName = pascalToSnakeCase;
+
+export function getAddressArgs(c: Pick<Contract, 'constructorArgs'>): string[] {
+  return (c.constructorArgs || [])
+    .filter(constructorArg => constructorArg.type?.trim() === 'Address')
+    .map(constructorArg => constructorArg.name);
+}
+
+export const printRustNameTest = (c: Pick<Contract, 'constructorArgs' | 'name'>) => `#![cfg(test)]
+
+extern crate std;
+
+use soroban_sdk::{ ${getAddressArgs(c).length ? 'testutils::Address as _, Address, ' : ''}Env, String };
+
+use crate::contract::{ ${c.name}, ${c.name}Client };
+
+#[test]
+fn initial_state() {
+    let env = Env::default();
+
+    let contract_addr = env.register(${c.name}, (${getAddressArgs(c)
+      .map(() => 'Address::generate(&env)')
+      .join(',')}${getAddressArgs(c).length === 1 ? ',' : ''}));
+    let client = ${c.name}Client::new(&env, &contract_addr);
+
+    assert_eq!(client.name(), String::from_str(&env, "${c.name}"));
+}
+
+// Add more tests bellow
+`;
+
+const getKeysOf = <TObject extends Record<string, unknown>>(objectToGetKeysOf: TObject) =>
+  Object.keys(objectToGetKeysOf) as (keyof TObject)[];
+
+export const stellarDependencies = {
+  base: ['stellar-default-impl-macro'],
+  fungible: ['stellar-fungible'],
+  nonFungible: ['stellar-non-fungible'],
+  pausable: ['stellar-pausable', 'stellar-pausable-macros'],
+  upgradable: ['stellar-upgradeable', 'stellar-upgradeable-macros'],
+} as const;
+
+export const allStellarDependencies = getKeysOf(stellarDependencies);
+
+export const allDependencies = {
+  ...stellarDependencies,
+  soroban: ['soroban-sdk'],
+} as const;
+
+export const addDependenciesWith = (dependencyValue: string, dependenciesToAdd: (keyof typeof allDependencies)[]) =>
+  dependenciesToAdd.reduce((addedDependency, dependencyName) => {
+    return `${addedDependency}${allDependencies[dependencyName].map(cargoDependencies => `${cargoDependencies} = ${dependencyValue}\n`).join('')}`;
+  }, '');
+
+export const printContractCargo = (scaffoldContractName: string) => `[package]
+name = "${scaffoldContractName.replace(/_/, '-')}-contract"
+edition.workspace = true
+license.workspace = true
+publish = false
+version.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+doctest = false
+
+[dependencies]
+${addDependenciesWith('{ workspace = true }', [...allStellarDependencies, 'soroban'])}
+[dev-dependencies]
+${addDependenciesWith('{ workspace = true, features = ["testutils"] }', ['soroban'])}`;
+
+export const createRustLibFile = `#![no_std]
+#![allow(dead_code)]
+
+mod contract;
+mod test;
+`;