@openzeppelin/wizard-stellar 0.6.2 → 0.6.3

package/src/vault.ts

@@ -0,0 +1,378 @@
+import { ContractBuilder } from './contract';
+import type { Access } from './set-access-control';
+import { setAccessControl } from './set-access-control';
+import { addPausable } from './add-pausable';
+import { addUpgradeable } from './add-upgradeable';
+import { defineFunctions } from './utils/define-functions';
+import type { CommonContractOptions } from './common-options';
+import { withCommonContractDefaults, getSelfArg } from './common-options';
+import { setInfo } from './set-info';
+import { contractDefaults as commonDefaults } from './common-options';
+import { printContract } from './print';
+import { toByteArray, toUint } from './utils/convert-strings';
+import { OptionsError } from './error';
+import { pickKeys } from '@openzeppelin/wizard-common';
+
+// Upper bound enforced by the library's `Vault::set_decimals_offset`
+// (`stellar_tokens::vault::MAX_DECIMALS_OFFSET`); a larger value panics on deploy.
+const MAX_DECIMALS_OFFSET = 10;
+
+export const defaults: Required<VaultOptions> = {
+  name: 'MyVault',
+  symbol: 'MTK',
+  decimalsOffset: '0',
+  pausable: false,
+  upgradeable: false,
+  access: commonDefaults.access,
+  info: commonDefaults.info,
+  explicitImplementations: commonDefaults.explicitImplementations,
+} as const;
+
+export function printVault(opts: VaultOptions = defaults): string {
+  return printContract(buildVault(opts));
+}
+
+export interface VaultOptions extends CommonContractOptions {
+  name: string;
+  symbol: string;
+  decimalsOffset?: string;
+  pausable?: boolean;
+  upgradeable?: boolean;
+}
+
+export function withDefaults(opts: VaultOptions): Required<VaultOptions> {
+  return {
+    ...opts,
+    ...withCommonContractDefaults(opts),
+    decimalsOffset: opts.decimalsOffset ?? defaults.decimalsOffset,
+    pausable: opts.pausable ?? defaults.pausable,
+    upgradeable: opts.upgradeable ?? defaults.upgradeable,
+  };
+}
+
+export function isAccessControlRequired(opts: Partial<VaultOptions>): boolean {
+  return opts.pausable === true || opts.upgradeable === true;
+}
+
+export function buildVault(opts: VaultOptions): ContractBuilder {
+  const c = new ContractBuilder(opts.name);
+
+  const allOpts = withDefaults(opts);
+
+  const decimalsOffset = toUint(allOpts.decimalsOffset, 'decimalsOffset', 'u32');
+  if (decimalsOffset > MAX_DECIMALS_OFFSET) {
+    throw new OptionsError({
+      decimalsOffset: `Maximum decimals offset is ${MAX_DECIMALS_OFFSET}`,
+    });
+  }
+
+  addBase(
+    c,
+    toByteArray(allOpts.name),
+    toByteArray(allOpts.symbol),
+    decimalsOffset,
+    allOpts.pausable,
+    allOpts.explicitImplementations,
+  );
+
+  if (allOpts.pausable) {
+    addPausable(c, allOpts.access, allOpts.explicitImplementations);
+  }
+
+  if (allOpts.upgradeable) {
+    addUpgradeable(c, allOpts.access, allOpts.explicitImplementations);
+  }
+
+  setAccessControl(c, allOpts.access, allOpts.explicitImplementations);
+
+  // The AccessControl trait surface (e.g. `get_existing_roles`, role lookups)
+  // references `Symbol` and `Vec`, which the contracttrait macro and explicit
+  // implementations need in scope even when no function is role-gated.
+  if (allOpts.access === 'roles') {
+    c.addUseClause('soroban_sdk', 'Symbol');
+    c.addUseClause('soroban_sdk', 'Vec');
+  }
+
+  setInfo(c, allOpts.info);
+
+  return c;
+}
+
+function addBase(
+  c: ContractBuilder,
+  name: string,
+  symbol: string,
+  decimalsOffset: bigint,
+  pausable: boolean,
+  explicitImplementations: boolean,
+) {
+  // The underlying asset is supplied at deployment, while the virtual decimals
+  // offset is a baked-in configuration value. The offset must be set before the
+  // metadata because the vault derives its decimals from the underlying asset's
+  // decimals plus the offset.
+  c.addConstructorArgument({ name: 'asset', type: 'Address' });
+  c.addConstructorCode('Vault::set_asset(e, asset);');
+  c.addConstructorCode(`Vault::set_decimals_offset(e, ${decimalsOffset});`);
+  c.addConstructorCode(
+    `Base::set_metadata(e, Self::decimals(e), String::from_str(e, "${name}"), String::from_str(e, "${symbol}"));`,
+  );
+
+  // Set token functions
+  c.addUseClause('stellar_tokens::fungible', 'Base');
+  c.addUseClause('stellar_tokens::fungible', 'FungibleToken');
+  c.addUseClause('stellar_tokens::vault', 'FungibleVault');
+  c.addUseClause('stellar_tokens::vault', 'Vault');
+  // The base token functions we emit delegate to `Self::ContractType::...`,
+  // which resolve through the `ContractOverrides` trait that `Vault` implements,
+  // so it must be in scope. This happens with explicit implementations (all
+  // functions are spelled out) and when pausable adds transfer overrides.
+  if (explicitImplementations || pausable) c.addUseClause('stellar_tokens::fungible', 'ContractOverrides');
+  c.addUseClause('soroban_sdk', 'contract');
+  c.addUseClause('soroban_sdk', 'contractimpl');
+  c.addUseClause('soroban_sdk', 'String');
+  c.addUseClause('soroban_sdk', 'Env');
+  c.addUseClause('soroban_sdk', 'Address');
+  c.addUseClause('soroban_sdk', 'MuxedAddress');
+
+  const fungibleTokenTrait = {
+    traitName: 'FungibleToken',
+    structName: c.name,
+    tags: explicitImplementations ? ['contractimpl'] : ['contractimpl(contracttrait)'],
+    assocType: 'type ContractType = Vault;',
+  };
+
+  c.addTraitImplBlock(fungibleTokenTrait);
+
+  if (explicitImplementations) {
+    c.addTraitForEachFunctions(fungibleTokenTrait, fungibleTokenTraitFunctions);
+  } else {
+    // The vault overrides decimals to derive them from the underlying asset and
+    // the virtual decimals offset.
+    c.addTraitFunction(fungibleTokenTrait, functions.decimals);
+  }
+
+  if (pausable) {
+    c.addUseClause('stellar_macros', 'when_not_paused');
+
+    c.addTraitFunction(fungibleTokenTrait, functions.transfer);
+    c.addFunctionTag(functions.transfer, 'when_not_paused', fungibleTokenTrait);
+
+    c.addTraitFunction(fungibleTokenTrait, functions.transfer_from);
+    c.addFunctionTag(functions.transfer_from, 'when_not_paused', fungibleTokenTrait);
+  }
+
+  const fungibleVaultTrait = {
+    traitName: 'FungibleVault',
+    structName: c.name,
+    tags: explicitImplementations ? ['contractimpl'] : ['contractimpl(contracttrait)'],
+    section: 'Extensions',
+  };
+
+  if (explicitImplementations) {
+    c.addTraitForEachFunctions(fungibleVaultTrait, fungibleVaultTraitFunctions);
+  } else {
+    c.addTraitImplBlock(fungibleVaultTrait);
+  }
+}
+
+export const functions = defineFunctions({
+  // FungibleToken Trait
+  total_supply: {
+    args: [getSelfArg()],
+    returns: 'i128',
+    code: ['Self::ContractType::total_supply(e)'],
+  },
+  balance: {
+    args: [getSelfArg(), { name: 'account', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::balance(e, &account)'],
+  },
+  allowance: {
+    args: [getSelfArg(), { name: 'owner', type: 'Address' }, { name: 'spender', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::allowance(e, &owner, &spender)'],
+  },
+  transfer: {
+    args: [
+      getSelfArg(),
+      { name: 'from', type: 'Address' },
+      { name: 'to', type: 'MuxedAddress' },
+      { name: 'amount', type: 'i128' },
+    ],
+    code: ['Self::ContractType::transfer(e, &from, &to, amount)'],
+  },
+  transfer_from: {
+    args: [
+      getSelfArg(),
+      { name: 'spender', type: 'Address' },
+      { name: 'from', type: 'Address' },
+      { name: 'to', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+    ],
+    code: ['Self::ContractType::transfer_from(e, &spender, &from, &to, amount)'],
+  },
+  approve: {
+    args: [
+      getSelfArg(),
+      { name: 'owner', type: 'Address' },
+      { name: 'spender', type: 'Address' },
+      { name: 'amount', type: 'i128' },
+      { name: 'live_until_ledger', type: 'u32' },
+    ],
+    code: ['Self::ContractType::approve(e, &owner, &spender, amount, live_until_ledger)'],
+  },
+  // The vault derives decimals from the underlying asset's decimals plus the
+  // virtual offset, so it overrides the default metadata-based implementation.
+  decimals: {
+    args: [getSelfArg()],
+    returns: 'u32',
+    code: ['Vault::decimals(e)'],
+  },
+  name: {
+    args: [getSelfArg()],
+    returns: 'String',
+    code: ['Self::ContractType::name(e)'],
+  },
+  symbol: {
+    args: [getSelfArg()],
+    returns: 'String',
+    code: ['Self::ContractType::symbol(e)'],
+  },
+
+  // FungibleVault Trait
+  query_asset: {
+    args: [getSelfArg()],
+    returns: 'Address',
+    code: ['Self::ContractType::query_asset(e)'],
+  },
+  total_assets: {
+    args: [getSelfArg()],
+    returns: 'i128',
+    code: ['Self::ContractType::total_assets(e)'],
+  },
+  convert_to_shares: {
+    args: [getSelfArg(), { name: 'assets', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::convert_to_shares(e, assets)'],
+  },
+  convert_to_assets: {
+    args: [getSelfArg(), { name: 'shares', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::convert_to_assets(e, shares)'],
+  },
+  max_deposit: {
+    args: [getSelfArg(), { name: 'receiver', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::max_deposit(e, receiver)'],
+  },
+  preview_deposit: {
+    args: [getSelfArg(), { name: 'assets', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::preview_deposit(e, assets)'],
+  },
+  deposit: {
+    args: [
+      getSelfArg(),
+      { name: 'assets', type: 'i128' },
+      { name: 'receiver', type: 'Address' },
+      { name: 'from', type: 'Address' },
+      { name: 'operator', type: 'Address' },
+    ],
+    returns: 'i128',
+    code: ['Self::ContractType::deposit(e, assets, receiver, from, operator)'],
+  },
+  max_mint: {
+    args: [getSelfArg(), { name: 'receiver', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::max_mint(e, receiver)'],
+  },
+  preview_mint: {
+    args: [getSelfArg(), { name: 'shares', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::preview_mint(e, shares)'],
+  },
+  mint: {
+    args: [
+      getSelfArg(),
+      { name: 'shares', type: 'i128' },
+      { name: 'receiver', type: 'Address' },
+      { name: 'from', type: 'Address' },
+      { name: 'operator', type: 'Address' },
+    ],
+    returns: 'i128',
+    code: ['Self::ContractType::mint(e, shares, receiver, from, operator)'],
+  },
+  max_withdraw: {
+    args: [getSelfArg(), { name: 'owner', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::max_withdraw(e, owner)'],
+  },
+  preview_withdraw: {
+    args: [getSelfArg(), { name: 'assets', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::preview_withdraw(e, assets)'],
+  },
+  withdraw: {
+    args: [
+      getSelfArg(),
+      { name: 'assets', type: 'i128' },
+      { name: 'receiver', type: 'Address' },
+      { name: 'owner', type: 'Address' },
+      { name: 'operator', type: 'Address' },
+    ],
+    returns: 'i128',
+    code: ['Self::ContractType::withdraw(e, assets, receiver, owner, operator)'],
+  },
+  max_redeem: {
+    args: [getSelfArg(), { name: 'owner', type: 'Address' }],
+    returns: 'i128',
+    code: ['Self::ContractType::max_redeem(e, owner)'],
+  },
+  preview_redeem: {
+    args: [getSelfArg(), { name: 'shares', type: 'i128' }],
+    returns: 'i128',
+    code: ['Self::ContractType::preview_redeem(e, shares)'],
+  },
+  redeem: {
+    args: [
+      getSelfArg(),
+      { name: 'shares', type: 'i128' },
+      { name: 'receiver', type: 'Address' },
+      { name: 'owner', type: 'Address' },
+      { name: 'operator', type: 'Address' },
+    ],
+    returns: 'i128',
+    code: ['Self::ContractType::redeem(e, shares, receiver, owner, operator)'],
+  },
+});
+
+const fungibleTokenTraitFunctions = pickKeys(functions, [
+  'total_supply',
+  'balance',
+  'allowance',
+  'transfer',
+  'transfer_from',
+  'approve',
+  'decimals',
+  'name',
+  'symbol',
+]);
+
+const fungibleVaultTraitFunctions = pickKeys(functions, [
+  'query_asset',
+  'total_assets',
+  'convert_to_shares',
+  'convert_to_assets',
+  'max_deposit',
+  'preview_deposit',
+  'deposit',
+  'max_mint',
+  'preview_mint',
+  'mint',
+  'max_withdraw',
+  'preview_withdraw',
+  'withdraw',
+  'max_redeem',
+  'preview_redeem',
+  'redeem',
+]);

package/src/zip-rust.ts

@@ -8,6 +8,7 @@ import {
   getRequiredLibDependencies,
   printContractCargo,
   printRustNameTest,
+  printVaultRustTest,
   workspaceCargo,
 } from './zip-shared';
 
@@ -37,7 +38,10 @@ 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`, printRustNameTest(c));
+  zip.file(
+    `contracts/${contractName}/src/test.rs`,
+    opts?.kind === 'Vault' ? printVaultRustTest(c) : printRustNameTest(c),
+  );
   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

@@ -39,6 +39,68 @@ fn initial_state() {
 // Add more tests bellow
 `;
 
+// The vault's constructor takes an underlying asset address and derives its own
+// decimals by calling into that asset contract. A generated address would have
+// no `decimals()` to call, so the test deploys a minimal mock fungible asset
+// first and registers the vault against it. A single-element tuple needs a
+// trailing comma in Rust.
+export const printVaultRustTest = (c: Pick<Contract, 'constructorArgs' | 'name'>) => {
+  const registerArgs = (c.constructorArgs || []).map(arg =>
+    arg.name === 'asset' ? 'asset_address.clone()' : 'Address::generate(&env)',
+  );
+  const registerTuple = `(${registerArgs.join(', ')}${registerArgs.length === 1 ? ',' : ''})`;
+
+  return `#![cfg(test)]
+
+extern crate std;
+
+use soroban_sdk::{
+    contract, contractimpl, testutils::Address as _, Address, Env, MuxedAddress, String,
+};
+use stellar_tokens::fungible::{Base, FungibleToken};
+
+use crate::contract::{ ${c.name}, ${c.name}Client };
+
+// Mock asset contract: a minimal fungible token used as the vault's underlying asset.
+#[contract]
+pub struct MockAssetContract;
+
+#[contractimpl]
+impl MockAssetContract {
+    pub fn __constructor(e: &Env, initial_supply: i128, admin: Address) {
+        Base::set_metadata(
+            e,
+            18,
+            String::from_str(e, "Mock Asset Token"),
+            String::from_str(e, "MAT"),
+        );
+        Base::mint(e, &admin, initial_supply);
+    }
+}
+
+#[contractimpl(contracttrait)]
+impl FungibleToken for MockAssetContract {
+    type ContractType = Base;
+}
+
+#[test]
+fn initial_state() {
+    let env = Env::default();
+
+    let admin = Address::generate(&env);
+    let asset_address = env.register(MockAssetContract, (1_000_000_000i128, admin));
+
+    let contract_addr = env.register(${c.name}, ${registerTuple});
+    let client = ${c.name}Client::new(&env, &contract_addr);
+
+    assert_eq!(client.query_asset(), asset_address);
+    assert_eq!(client.name(), String::from_str(&env, "${c.name}"));
+}
+
+// Add more tests bellow
+`;
+};
+
 const libDependencies = [
   'stellar-tokens',
   'stellar-access',