@openzeppelin/wizard-stellar 0.2.3 → 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/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