Stellar vault (#821)

Author: ozgunozerk

.changeset/stellar-vault.md

@@ -0,0 +1,8 @@
+---
+'@openzeppelin/wizard-stellar': patch
+'@openzeppelin/wizard-common': patch
+'@openzeppelin/contracts-mcp': patch
+'@openzeppelin/contracts-cli': patch
+---
+
+Add Stellar tokenized `Vault` contract type, a Fungible Token that issues shares for an underlying asset (ERC-4626-style), with support for pausable, upgradeable, and access control options.

packages/cli/src/cli.test.ts.md

@@ -11,7 +11,7 @@ Generated by [AVA](https://avajs.dev).
     `Usage: npx @openzeppelin/contracts-cli <command> [options]␊
     ␊
     Commands:␊
-      solidity-erc20, solidity-erc721, solidity-erc1155, solidity-stablecoin, solidity-rwa, solidity-account, solidity-governor, solidity-custom, cairo-erc20, cairo-erc721, cairo-erc1155, cairo-account, cairo-multisig, cairo-governor, cairo-vesting, cairo-custom, stellar-fungible, stellar-governor, stellar-stablecoin, stellar-non-fungible, stylus-erc20, stylus-erc721, stylus-erc1155, confidential-erc7984, uniswap-hooks␊
+      solidity-erc20, solidity-erc721, solidity-erc1155, solidity-stablecoin, solidity-rwa, solidity-account, solidity-governor, solidity-custom, cairo-erc20, cairo-erc721, cairo-erc1155, cairo-account, cairo-multisig, cairo-governor, cairo-vesting, cairo-custom, stellar-fungible, stellar-governor, stellar-stablecoin, stellar-non-fungible, stellar-vault, stylus-erc20, stylus-erc721, stylus-erc1155, confidential-erc7984, uniswap-hooks␊
     ␊
     Generated contract source code is printed to stdout.␊
     ␊
@@ -25,7 +25,7 @@ Generated by [AVA](https://avajs.dev).
     `Usage: npx @openzeppelin/contracts-cli <command> [options]␊
     ␊
     Commands:␊
-      solidity-erc20, solidity-erc721, solidity-erc1155, solidity-stablecoin, solidity-rwa, solidity-account, solidity-governor, solidity-custom, cairo-erc20, cairo-erc721, cairo-erc1155, cairo-account, cairo-multisig, cairo-governor, cairo-vesting, cairo-custom, stellar-fungible, stellar-governor, stellar-stablecoin, stellar-non-fungible, stylus-erc20, stylus-erc721, stylus-erc1155, confidential-erc7984, uniswap-hooks␊
+      solidity-erc20, solidity-erc721, solidity-erc1155, solidity-stablecoin, solidity-rwa, solidity-account, solidity-governor, solidity-custom, cairo-erc20, cairo-erc721, cairo-erc1155, cairo-account, cairo-multisig, cairo-governor, cairo-vesting, cairo-custom, stellar-fungible, stellar-governor, stellar-stablecoin, stellar-non-fungible, stellar-vault, stylus-erc20, stylus-erc721, stylus-erc1155, confidential-erc7984, uniswap-hooks␊
     ␊
     Generated contract source code is printed to stdout.␊
     ␊
@@ -539,6 +539,26 @@ Generated by [AVA](https://avajs.dev).
       --info.license <string>               The license used by the contract, default is "MIT"␊
     `
 
+## stellar-vault --help
+
+> Snapshot 1
+
+    `stellar-vault: Make a tokenized vault that issues Fungible Token shares for an underlying asset, similar to ERC-4626.␊
+    ␊
+    Required:␊
+      --name <string>                       The name of the contract␊
+      --symbol <string>                     The short symbol for the token␊
+    ␊
+    Options:␊
+      --decimalsOffset <string>             Virtual decimals offset added to the underlying asset decimals to derive the vault share decimals, used to mitigate inflation (donation) attacks via virtual shares. The default of 0 is already safe: it makes such attacks non-profitable. Higher values make attacks orders of magnitude more costly, at the cost of virtual shares absorbing a tiny portion of the value accrued to the vault. Must be between 0 and 10.␊
+      --pausable                            Whether privileged accounts will be able to pause specifically marked functionality. Useful for emergency response.␊
+      --access <ownable|roles>              The type of access control to provision. Ownable is a simple mechanism with a single account authorized for all privileged actions. Roles is a flexible mechanism with a separate role for each privileged action. A role can have many authorized accounts.␊
+      --explicitImplementations             Whether the contract should use explicit trait implementations instead of using the default ones provided by the library.␊
+      --upgradeable                         Whether the contract can be upgraded.␊
+      --info.securityContact <string>       Email where people can contact you to report security issues. Will only be visible if contract source code is verified.␊
+      --info.license <string>               The license used by the contract, default is "MIT"␊
+    `
+
 ## stylus-erc20 --help
 
 > Snapshot 1

packages/cli/src/cli.test.ts.snap

@@ -41,13 +41,15 @@ import {
   governor as stellarGovernor,
   stablecoin as stellarStablecoin,
   nonFungible,
+  vault as stellarVault,
 } from '@openzeppelin/wizard-stellar';
 import { stellarPrompts } from '@openzeppelin/wizard-common';
 import {
   stellarFungibleSchema,
   stellarGovernorSchema,
   stellarStablecoinSchema,
   stellarNonFungibleSchema,
+  stellarVaultSchema,
 } from '@openzeppelin/wizard-common/schemas';
 
 import { erc20 as stylusErc20, erc721 as stylusErc721, erc1155 as stylusErc1155 } from '@openzeppelin/wizard-stylus';
@@ -133,6 +135,7 @@ export const registry = {
     opts => nonFungible.print(opts),
     stellarPrompts.NonFungible,
   ),
+  'stellar-vault': createRegistryEntry(stellarVaultSchema, opts => stellarVault.print(opts), stellarPrompts.Vault),
 
   // Stylus
   'stylus-erc20': createRegistryEntry(stylusERC20Schema, opts => stylusErc20.print(opts), stylusPrompts.ERC20),

packages/cli/src/registry.ts

@@ -7,6 +7,7 @@ export const stellarPrompts = {
   NonFungible:
     'Make a non-fungible token per the Non-Fungible Token Standard, compatible with SEP-50, similar to ERC-721.',
   Stablecoin: 'Make a stablecoin that uses Fungible Token Standard, compatible with SEP-41.',
+  Vault: 'Make a tokenized vault that issues Fungible Token shares for an underlying asset, similar to ERC-4626.',
 };
 
 export const stellarCommonDescriptions = {
@@ -38,6 +39,11 @@ export const stellarStablecoinDescriptions = {
   votes: 'Whether to enable vote checkpoints and delegation for governance.',
 };
 
+export const stellarVaultDescriptions = {
+  decimalsOffset:
+    'Virtual decimals offset added to the underlying asset decimals to derive the vault share decimals, used to mitigate inflation (donation) attacks via virtual shares. The default of 0 is already safe: it makes such attacks non-profitable. Higher values make attacks orders of magnitude more costly, at the cost of virtual shares absorbing a tiny portion of the value accrued to the vault. Must be between 0 and 10.',
+};
+
 export const stellarGovernorDescriptions = {
   version: 'The semantic version label returned by the governor contract.',
   votingDelay: 'Number of ledgers between proposal creation and voting start (17,000 ledgers are approx. 1 day).',

packages/common/src/ai/descriptions/stellar.ts

@@ -30,6 +30,7 @@ export {
   stellarInfoSchema,
   stellarStablecoinSchema,
   stellarNonFungibleSchema,
+  stellarVaultSchema,
 } from './stellar';
 
 export { stylusCommonSchema, stylusERC20Schema, stylusERC721Schema, stylusERC1155Schema } from './stylus';

packages/common/src/ai/schemas/index.ts

@@ -30,6 +30,7 @@ import {
   stellarGovernorSchema,
   stellarStablecoinSchema,
   stellarNonFungibleSchema,
+  stellarVaultSchema,
   stylusERC20Schema,
   stylusERC721Schema,
   stylusERC1155Schema,
@@ -96,6 +97,7 @@ const allSchemas: [string, z.ZodRawShape][] = [
   ['stellarFungible', stellarFungibleSchema],
   ['stellarStablecoin', stellarStablecoinSchema],
   ['stellarNonFungible', stellarNonFungibleSchema],
+  ['stellarVault', stellarVaultSchema],
   ['stylusERC20', stylusERC20Schema],
   ['stylusERC721', stylusERC721Schema],
   ['stylusERC1155', stylusERC1155Schema],
@@ -154,6 +156,7 @@ function _stellarTypeAssertions() {
     Governor: z.object(stellarGovernorSchema).parse({}),
     Stablecoin: z.object(stellarStablecoinSchema).parse({}),
     NonFungible: z.object(stellarNonFungibleSchema).parse({}),
+    Vault: z.object(stellarVaultSchema).parse({}),
   };
 }
 

packages/common/src/ai/schemas/schemas.test.ts

@@ -7,6 +7,7 @@ import {
   stellarFungibleDescriptions,
   stellarNonFungibleDescriptions,
   stellarStablecoinDescriptions,
+  stellarVaultDescriptions,
 } from '../../index';
 
 export const stellarInfoSchema = z
@@ -57,6 +58,14 @@ export const stellarStablecoinSchema = {
     .describe(stellarStablecoinDescriptions.limitations),
 } as const satisfies z.ZodRawShape;
 
+export const stellarVaultSchema = {
+  name: z.string().describe(commonDescriptions.name),
+  symbol: z.string().describe(commonDescriptions.symbol),
+  decimalsOffset: z.string().optional().describe(stellarVaultDescriptions.decimalsOffset),
+  pausable: z.boolean().optional().describe(commonDescriptions.pausable),
+  ...stellarCommonSchema,
+} as const satisfies z.ZodRawShape;
+
 export const stellarNonFungibleSchema = {
   name: z.string().describe(commonDescriptions.name),
   symbol: z.string().describe(commonDescriptions.symbol),

packages/common/src/ai/schemas/stellar.ts

@@ -3,11 +3,17 @@ import type { FungibleOptions } from './fungible';
 import type { GovernorOptions } from './governor';
 import type { NonFungibleOptions } from './non-fungible';
 import type { StablecoinOptions } from './stablecoin';
+import type { VaultOptions } from './vault';
 import {
   printStablecoin,
   defaults as stablecoinDefaults,
   isAccessControlRequired as stablecoinIsAccessControlRequired,
 } from './stablecoin';
+import {
+  printVault,
+  defaults as vaultDefaults,
+  isAccessControlRequired as vaultIsAccessControlRequired,
+} from './vault';
 import {
   printFungible,
   defaults as fungibledefaults,
@@ -48,6 +54,7 @@ export type Fungible = WizardContractAPI<FungibleOptions> & AccessControlAPI<Fun
 export type Governor = WizardContractAPI<GovernorOptions> & AccessControlAPI<GovernorOptions>;
 export type NonFungible = WizardContractAPI<NonFungibleOptions> & AccessControlAPI<NonFungibleOptions>;
 export type Stablecoin = WizardContractAPI<StablecoinOptions> & AccessControlAPI<StablecoinOptions>;
+export type Vault = WizardContractAPI<VaultOptions> & AccessControlAPI<VaultOptions>;
 
 export const fungible: Fungible = {
   print: printFungible,
@@ -72,3 +79,9 @@ export const stablecoin: Stablecoin = {
   defaults: stablecoinDefaults,
   isAccessControlRequired: stablecoinIsAccessControlRequired,
 };
+
+export const vault: Vault = {
+  print: printVault,
+  defaults: vaultDefaults,
+  isAccessControlRequired: vaultIsAccessControlRequired,
+};

packages/core/stellar/src/api.ts

@@ -6,12 +6,15 @@ import type { NonFungibleOptions } from './non-fungible';
 import { buildNonFungible } from './non-fungible';
 import type { StablecoinOptions } from './stablecoin';
 import { buildStablecoin } from './stablecoin';
+import type { VaultOptions } from './vault';
+import { buildVault } from './vault';
 
 export interface KindedOptions {
   Fungible: { kind: 'Fungible' } & FungibleOptions;
   Governor: { kind: 'Governor' } & GovernorOptions;
   NonFungible: { kind: 'NonFungible' } & NonFungibleOptions;
   Stablecoin: { kind: 'Stablecoin' } & StablecoinOptions;
+  Vault: { kind: 'Vault' } & VaultOptions;
 }
 
 export type GenericOptions = KindedOptions[keyof KindedOptions];
@@ -30,6 +33,9 @@ export function buildGeneric(opts: GenericOptions) {
     case 'Stablecoin':
       return buildStablecoin(opts);
 
+    case 'Vault':
+      return buildVault(opts);
+
     default: {
       const _: never = opts;
       throw new Error('Unknown kind');