DEVREL-833 check Solana local decimals when creating OFT

.changeset/six-dots-occur.md

@@ -0,0 +1,6 @@
+---
+"@layerzerolabs/lzapp-migration-example": patch
+"@layerzerolabs/oft-solana-example": patch
+---
+
+oft-solana: require user to confirm max total token supply given a local decimals value

examples/lzapp-migration/tasks/solana/createOFT.ts

@@ -23,9 +23,10 @@ import { types as devtoolsTypes } from '@layerzerolabs/devtools-evm-hardhat'
 import { assertAccountInitialized } from '@layerzerolabs/devtools-solana'
 import { promptToContinue } from '@layerzerolabs/io-devtools'
 import { EndpointId } from '@layerzerolabs/lz-definitions'
-import { OFT_DECIMALS as DEFAULT_SHARED_DECIMALS, oft202 } from '@layerzerolabs/oft-v2-solana-sdk'
+import { OFT_DECIMALS as DEFAULT_SHARED_DECIMALS, oft202 } from '@layerzerolabs/oft-v2-solana-sdk' // Note: 'oft202' should be used instead of 'oft'
 
 import { checkMultisigSigners, createMintAuthorityMultisig } from './multisig'
+import { formatAmount, localDecimalsToMaxSupply } from './utils'
 
 import {
     TransactionType,
@@ -117,6 +118,11 @@ interface CreateOFTTaskArgs {
      * The freeze authority address (only supported in onlyOftStore mode).
      */
     freezeAuthority?: string
+
+    /**
+     * Whether to continue without confirmation.
+     */
+    ci: boolean
 }
 
 // Define a Hardhat task for creating OFT on Solana
@@ -158,6 +164,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
         true
     )
     .addParam('computeUnitPriceScaleFactor', 'The compute unit price scale factor', 4, devtoolsTypes.float, true)
+    .addFlag('ci', 'Continue without confirmation')
     .setAction(
         async ({
             amount,
@@ -176,6 +183,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
             uri,
             freezeAuthority: freezeAuthorityStr,
             computeUnitPriceScaleFactor,
+            ci,
         }: CreateOFTTaskArgs) => {
             const isMABA = !!mintStr // the difference between MABA and OFT Adapter is that MABA uses mint/burn mechanism whereas OFT Adapter uses lock/unlock mechanism
             if (tokenProgramStr !== TOKEN_PROGRAM_ID.toBase58() && !isMABA) {
@@ -212,7 +220,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
                 )
             }
 
-            if (onlyOftStore) {
+            if (onlyOftStore && !ci) {
                 const continueWithOnlyOftStore = await promptToContinue(
                     `You have chosen \`--only-oft-store true\`. This means that only the OFT Store will be able to mint new tokens${freezeAuthorityStr ? '' : ' and that the Freeze Authority will be immediately renounced'}.  Continue?`
                 )
@@ -222,6 +230,13 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
             }
             // EOF: Validate combination of parameters
 
+            const maxSupply = formatAmount(localDecimalsToMaxSupply(decimals))
+            const maxSupplyStatement = `You have chosen ${decimals} local decimals. The maximum supply of your Solana OFT token will be ${maxSupply}.\n`
+            const confirmMaxSupply = await promptToContinue(maxSupplyStatement)
+            if (!confirmMaxSupply) {
+                return
+            }
+
             let mintAuthorityPublicKey: PublicKey = toWeb3JsPublicKey(oftStorePda) // we default to the OFT Store as the Mint Authority when there are no additional minters
 
             if (additionalMintersAsStrings) {

examples/lzapp-migration/tasks/solana/utils.ts

@@ -32,3 +32,81 @@ export function silenceSolana429(connection: Connection): void {
         return origWrite(chunk, ...args)
     }) as typeof process.stderr.write
 }
+
+// Max whole-token supply on Solana (u64)
+const U64_MAX = (1n << 64n) - 1n
+const UNITS = [
+    { base: 1_000_000_000_000n, suffix: 'T' },
+    { base: 1_000_000_000n, suffix: 'B' },
+    { base: 1_000_000n, suffix: 'M' },
+    { base: 1_000n, suffix: 'K' },
+]
+
+/**
+ * Computes the maximum whole-token supply representable by a Solana SPL mint
+ * given its local decimal precision, formatted for readability.
+ *
+ * Behavior:
+ * - Uses compact units when large enough: K (thousand), M (million), B (billion), T (trillion).
+ * - Values < 1000 are returned as a plain whole number string without a suffix.
+ * - Rounds "half up" to the provided display precision.
+ * - Near unit boundaries, rounding can promote the value to the next unit
+ *   (e.g., 999.6B -> 1.0T) which matches typical human-readable expectations.
+ *
+ * Parameters:
+ * - localDecimals: Non-negative integer count of decimals on the SPL mint.
+ * - maxDisplayDecimals: Fractional digits to include in the compact representation (0–6). Default is 1.
+ *
+ * Returns:
+ * - A human-readable string such as "18.4B", "1.0T", or "842".
+ *
+ * Throws:
+ * - If localDecimals is negative or not an integer.
+ * - If maxDisplayDecimals is not an integer in the inclusive range [0, 6].
+ *
+ * Examples:
+ * - maxSupplyWholeTokens(9)  -> "18.4B"   // typical 9-decimal mint
+ * - maxSupplyWholeTokens(12) -> "18.4M"
+ * - maxSupplyWholeTokens(18) -> "18"      // < 1K, returned as a plain number
+ */
+/** Returns the maximum whole-token supply (as bigint) for a given local decimal precision. */
+export function localDecimalsToMaxSupply(localDecimals: number): bigint {
+    if (!Number.isInteger(localDecimals) || localDecimals < 0) {
+        throw new Error('localDecimals must be a non-negative integer')
+    }
+    const scalingFactor = 10n ** BigInt(localDecimals)
+    return U64_MAX / scalingFactor
+}
+
+/** Formats a whole-token amount into a compact human-readable form using K/M/B/T. */
+export function formatAmount(whole: bigint, maxDisplayDecimals = 1): string {
+    if (!Number.isInteger(maxDisplayDecimals) || maxDisplayDecimals < 0 || maxDisplayDecimals > 6) {
+        throw new Error('precision must be an integer between 0 and 6')
+    }
+
+    for (let i = 0; i < UNITS.length; i++) {
+        const { base, suffix } = UNITS[i]
+        if (whole >= base) {
+            const pow = 10n ** BigInt(maxDisplayDecimals)
+            let scaled = (whole * pow + base / 2n) / base
+            let intPart = scaled / pow
+
+            if (intPart >= 1000n && i === 1) {
+                const higher = UNITS[0]
+                scaled = (whole * pow + higher.base / 2n) / higher.base
+                intPart = scaled / pow
+                const frac = scaled % pow
+                const fracStr =
+                    maxDisplayDecimals === 0 ? '' : frac.toString().padStart(maxDisplayDecimals, '0').replace(/0+$/, '')
+                return fracStr ? `${intPart}.${fracStr}${higher.suffix}` : `${intPart}${higher.suffix}`
+            }
+
+            const frac = scaled % pow
+            const fracStr =
+                maxDisplayDecimals === 0 ? '' : frac.toString().padStart(maxDisplayDecimals, '0').replace(/0+$/, '')
+            return fracStr ? `${intPart}.${fracStr}${suffix}` : `${intPart}${suffix}`
+        }
+    }
+
+    return whole.toString()
+}

examples/oft-solana/tasks/solana/createOFT.ts

@@ -26,6 +26,7 @@ import { EndpointId } from '@layerzerolabs/lz-definitions'
 import { OFT_DECIMALS as DEFAULT_SHARED_DECIMALS, oft } from '@layerzerolabs/oft-v2-solana-sdk'
 
 import { checkMultisigSigners, createMintAuthorityMultisig } from './multisig'
+import { formatAmount, localDecimalsToMaxSupply } from './utils'
 
 import {
     TransactionType,
@@ -117,6 +118,11 @@ interface CreateOFTTaskArgs {
      * The freeze authority address (only supported in onlyOftStore mode).
      */
     freezeAuthority?: string
+
+    /**
+     * Whether to continue without confirmation.
+     */
+    ci: boolean
 }
 
 // Define a Hardhat task for creating OFT on Solana
@@ -158,6 +164,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
         true
     )
     .addParam('computeUnitPriceScaleFactor', 'The compute unit price scale factor', 4, devtoolsTypes.float, true)
+    .addFlag('ci', 'Continue without confirmation')
     .setAction(
         async ({
             amount,
@@ -176,6 +183,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
             uri,
             freezeAuthority: freezeAuthorityStr,
             computeUnitPriceScaleFactor,
+            ci,
         }: CreateOFTTaskArgs) => {
             const isMABA = !!mintStr // the difference between MABA and OFT Adapter is that MABA uses mint/burn mechanism whereas OFT Adapter uses lock/unlock mechanism
             if (tokenProgramStr !== TOKEN_PROGRAM_ID.toBase58() && !isMABA) {
@@ -212,7 +220,7 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
                 )
             }
 
-            if (onlyOftStore) {
+            if (onlyOftStore && !ci) {
                 const continueWithOnlyOftStore = await promptToContinue(
                     `You have chosen \`--only-oft-store true\`. This means that only the OFT Store will be able to mint new tokens${freezeAuthorityStr ? '' : ' and that the Freeze Authority will be immediately renounced'}.  Continue?`
                 )
@@ -223,6 +231,13 @@ task('lz:oft:solana:create', 'Mints new SPL Token and creates new OFT Store acco
 
             // EOF: Validate combination of parameters
 
+            const maxSupply = formatAmount(localDecimalsToMaxSupply(decimals))
+            const maxSupplyStatement = `You have chosen ${decimals} local decimals. The maximum supply of your Solana OFT token will be ${maxSupply}.\n`
+            const confirmMaxSupply = await promptToContinue(maxSupplyStatement)
+            if (!confirmMaxSupply) {
+                return
+            }
+
             let mintAuthorityPublicKey: PublicKey = toWeb3JsPublicKey(oftStorePda) // we default to the OFT Store as the Mint Authority when there are no additional minters
 
             if (additionalMintersAsStrings) {

examples/oft-solana/tasks/solana/createOFTAdapter.ts

@@ -5,9 +5,12 @@ import bs58 from 'bs58'
 import { task } from 'hardhat/config'
 
 import { types as devtoolsTypes } from '@layerzerolabs/devtools-evm-hardhat'
+import { promptToContinue } from '@layerzerolabs/io-devtools'
 import { EndpointId } from '@layerzerolabs/lz-definitions'
 import { OFT_DECIMALS, oft } from '@layerzerolabs/oft-v2-solana-sdk'
 
+import { formatAmount, localDecimalsToMaxSupply } from './utils'
+
 import {
     TransactionType,
     addComputeUnitInstructions,
@@ -63,6 +66,14 @@ task('lz:oft-adapter:solana:create', 'Creates new OFT Adapter (OFT Store PDA)')
             const mint = publicKey(mintStr)
 
             const mintPDA = await getMint(connection, new PublicKey(mintStr), undefined, new PublicKey(tokenProgramStr))
+            const mintDecimals = mintPDA.decimals
+
+            const maxSupply = formatAmount(localDecimalsToMaxSupply(mintDecimals))
+            const maxSupplyStatement = `You provided Token Mint ${mintDecimals} local decimals. The maximum supply of your Solana OFT token will be ${maxSupply}.\n`
+            const confirmMaxSupply = await promptToContinue(maxSupplyStatement)
+            if (!confirmMaxSupply) {
+                return
+            }
 
             const mintAuthority = mintPDA.mintAuthority
 

examples/oft-solana/tasks/solana/utils.ts

@@ -83,3 +83,80 @@ export function silenceSolana429(connection: Connection): void {
         return origWrite(chunk, ...args)
     }) as typeof process.stderr.write
 }
+// Max whole-token supply on Solana (u64) formatted as "XB" or "Y.YT"
+const U64_MAX = (1n << 64n) - 1n
+const UNITS = [
+    { base: 1000000000000n, suffix: 'T' },
+    { base: 1000000000n, suffix: 'B' },
+    { base: 1000000n, suffix: 'M' },
+    { base: 1000n, suffix: 'K' },
+]
+/**
+ * Compute the maximum whole-token supply for a Solana SPL mint given its
+ * local decimal precision.
+ *
+ * - Uses the u64 max value ((1 << 64) - 1) divided by the scaling factor
+ *   10^localDecimals to derive the whole-token cap.
+ * - Returns the whole-token cap as a bigint.
+ *
+ * @param localDecimals Non-negative integer count of decimals on the SPL mint.
+ * @returns bigint Whole-token maximum supply.
+ * @throws Error if localDecimals is not a non-negative integer.
+ */
+export function localDecimalsToMaxSupply(localDecimals: number): bigint {
+    if (!Number.isInteger(localDecimals) || localDecimals < 0) {
+        throw new Error('localDecimals must be a non-negative integer')
+    }
+    const scalingFactor = 10n ** BigInt(localDecimals)
+    return U64_MAX / scalingFactor
+}
+
+/**
+ * Format a whole-token amount into a compact human-readable string using
+ * unit suffixes: K (thousand), M (million), B (billion), T (trillion).
+ *
+ * Behavior:
+ * - Values < 1000 are returned as a plain whole number string (no suffix).
+ * - Rounds half up to the requested precision.
+ * - At boundaries, rounding may promote to the next unit (e.g., 999.6B → 1.0T).
+ *
+ * @param whole The whole-token quantity to format.
+ * @param maxDisplayDecimals Fractional digits to include (0–6). Default 1.
+ * @returns Human-readable string such as "18.4B", "1.0T", or "842".
+ * @throws Error if maxDisplayDecimals is not an integer in [0, 6].
+ */
+export function formatAmount(whole: bigint, maxDisplayDecimals = 1): string {
+    if (!Number.isInteger(maxDisplayDecimals) || maxDisplayDecimals < 0 || maxDisplayDecimals > 6) {
+        throw new Error('precision must be an integer between 0 and 6')
+    }
+
+    for (let i = 0; i < UNITS.length; i++) {
+        const { base, suffix } = UNITS[i]
+        if (whole >= base) {
+            const pow = 10n ** BigInt(maxDisplayDecimals)
+            // round half up at the requested precision
+            let scaled = (whole * pow + base / 2n) / base
+            let intPart = scaled / pow
+
+            // if rounding pushes us to 1000 of this unit, bump to the next larger (e.g., 999.6B -> 1.0T)
+            if (intPart >= 1000n && i === 1) {
+                // B -> T
+                const higher = UNITS[0]
+                scaled = (whole * pow + higher.base / 2n) / higher.base
+                intPart = scaled / pow
+                const frac = scaled % pow
+                const fracStr =
+                    maxDisplayDecimals === 0 ? '' : frac.toString().padStart(maxDisplayDecimals, '0').replace(/0+$/, '')
+                return fracStr ? `${intPart}.${fracStr}${higher.suffix}` : `${intPart}${higher.suffix}`
+            }
+
+            const frac = scaled % pow
+            const fracStr =
+                maxDisplayDecimals === 0 ? '' : frac.toString().padStart(maxDisplayDecimals, '0').replace(/0+$/, '')
+            return fracStr ? `${intPart}.${fracStr}${suffix}` : `${intPart}${suffix}`
+        }
+    }
+
+    // < 1K -> show plain whole number
+    return whole.toString()
+}