feat(devtools-starknet): fix ByteArray encoding and add wire support

Key fixes:
- Fix fromHex to handle odd-length hex strings by padding with leading '0'
  (Buffer.from silently truncates odd-length strings)
- Fix ByteArray encoding in setEnforcedOptions to use raw calldata instead
  of string-based encoding (starknet.js UTF-8 re-encodes bytes >= 128)
- Update sendStarknet to use createRpcUrlFactory() for RPC URL resolution
- Update starknet.js v8 Account constructor format

These fixes resolve the "out of bound" error when sending from Starknet OFT
caused by corrupted enforced options (byte 0x80 becoming UTF-8 0xc2 0x80).

Author: St0rmBr3w

examples/oft-main/.gitignore

@@ -30,6 +30,8 @@ deployments/
 # Sui build artifacts and deployment info
 sui/*/build/
 sui/deploy.json
+sui/**/oft_deploy.json
+sui/**/token_deploy.json
 
 # Starknet deployment info
 starknet/deploy.json

examples/oft-main/layerzero.config.ts

@@ -56,10 +56,23 @@ const SUI_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
     },
 ]
 
+const STARKNET_ENFORCED_OPTIONS: OAppEnforcedOption[] = [
+    {
+        msgType: 1,
+        optionType: ExecutorOptionType.LZ_RECEIVE,
+        gas: 500000, // Cairo steps for lzReceive execution on Starknet
+        value: 0,
+    },
+]
+
 type SuiDeployment = {
     oftPackageId: string
 }
 
+type StarknetDeployment = {
+    oftAddress: string
+}
+
 const loadJson = <T>(relativePath: string): T => {
     const fullPath = path.join(__dirname, relativePath)
     if (!fs.existsSync(fullPath)) {
@@ -69,12 +82,18 @@ const loadJson = <T>(relativePath: string): T => {
 }
 
 const suiDeployment = loadJson<SuiDeployment>('./sui/deploy.json')
+const starknetDeployment = loadJson<StarknetDeployment>('./starknet/deploy.json')
 
 const suiContract: OmniPointHardhat = {
     eid: EndpointId.SUI_V2_MAINNET,
     address: suiDeployment.oftPackageId,
 }
 
+const starknetContract: OmniPointHardhat = {
+    eid: EndpointId.STARKNET_V2_MAINNET,
+    address: starknetDeployment.oftAddress,
+}
+
 // Learn about Message Execution Options: https://docs.layerzero.network/v2/developers/solana/oft/overview#message-execution-options
 // Learn more about the Simple Config Generator - https://docs.layerzero.network/v2/developers/evm/technical-reference/simple-config
 export default async function () {
@@ -88,12 +107,20 @@ export default async function () {
             [15, 15],
             [SUI_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS],
         ],
+        [
+            arbitrumContract,
+            starknetContract,
+            [['LayerZero Labs'], []],
+            [15, 15],
+            [STARKNET_ENFORCED_OPTIONS, EVM_ENFORCED_OPTIONS],
+        ],
+        [suiContract, starknetContract, [[], []], [15, 15], [STARKNET_ENFORCED_OPTIONS, SUI_ENFORCED_OPTIONS]],
     ] as const
 
     const connections = await generateConnectionsConfig(pathways as any)
 
     return {
-        contracts: [{ contract: arbitrumContract }, { contract: suiContract }],
+        contracts: [{ contract: arbitrumContract }, { contract: suiContract }, { contract: starknetContract }],
         connections,
     }
 }

examples/oft-main/starknet/deploy-starknet-mainnet.js

@@ -55,15 +55,6 @@ async function main() {
         throw new Error('ERC20 ABI not found or invalid in oft-mint-burn-starknet package');
     }
     console.log('ERC20 ABI entries:', ERC20_ABI.length);
-    const txDetails = {
-        tip: 0n,
-        resourceBounds: {
-            l1_gas: { max_amount: 80_000n, max_price_per_unit: 60_000_000_000_000n },
-            l2_gas: { max_amount: 1_000_000n, max_price_per_unit: 10_000_000_000n },
-            l1_data_gas: { max_amount: 80_000n, max_price_per_unit: 60_000_000_000_000n },
-        },
-    };
-
     const existing = loadExistingDeploy();
     let erc20Address = process.env.STARKNET_ERC20_ADDRESS || existing?.erc20Address;
     let oftAddress = process.env.STARKNET_OFT_ADDRESS || existing?.oftAddress;
@@ -78,13 +69,10 @@ async function main() {
             decimals: ERC20_DECIMALS,
             default_admin: ACCOUNT_ADDRESS,
         });
-        const erc20Deploy = await account.deploy(
-            {
-                classHash: ERC20_CLASS_HASH,
-                constructorCalldata: erc20ConstructorCalldata,
-            },
-            txDetails
-        );
+        const erc20Deploy = await account.deploy({
+            classHash: ERC20_CLASS_HASH,
+            constructorCalldata: erc20ConstructorCalldata,
+        });
         await provider.waitForTransaction(erc20Deploy.transaction_hash);
         erc20Address = Array.isArray(erc20Deploy.contract_address)
             ? erc20Deploy.contract_address[0]
@@ -100,20 +88,17 @@ async function main() {
 
     if (!oftAddress) {
         console.log('Deploying OFTMintBurnAdapter...');
-        const oftDeploy = await account.deploy(
-            {
-                classHash: OFT_CLASS_HASH,
-                constructorCalldata: [
-                    erc20Address,
-                    erc20Address,
-                    ENDPOINT_ADDRESS,
-                    ACCOUNT_ADDRESS,
-                    STRK_TOKEN_ADDRESS,
-                    SHARED_DECIMALS,
-                ],
-            },
-            txDetails
-        );
+        const oftDeploy = await account.deploy({
+            classHash: OFT_CLASS_HASH,
+            constructorCalldata: [
+                erc20Address,
+                erc20Address,
+                ENDPOINT_ADDRESS,
+                ACCOUNT_ADDRESS,
+                STRK_TOKEN_ADDRESS,
+                SHARED_DECIMALS,
+            ],
+        });
         await provider.waitForTransaction(oftDeploy.transaction_hash);
         oftAddress = Array.isArray(oftDeploy.contract_address)
             ? oftDeploy.contract_address[0]
@@ -134,12 +119,12 @@ async function main() {
 
     console.log('Granting MINTER_ROLE...');
     const grantMinter = erc20.populateTransaction.grant_role(minterRole, oftAddress);
-    const grantMinterTx = await account.execute([grantMinter], txDetails);
+    const grantMinterTx = await account.execute([grantMinter]);
     await provider.waitForTransaction(grantMinterTx.transaction_hash);
 
     console.log('Granting BURNER_ROLE...');
     const grantBurner = erc20.populateTransaction.grant_role(burnerRole, oftAddress);
-    const grantBurnerTx = await account.execute([grantBurner], txDetails);
+    const grantBurnerTx = await account.execute([grantBurner]);
     await provider.waitForTransaction(grantBurnerTx.transaction_hash);
 
     const out = {

examples/oft-main/tasks/common/sendOFT.ts

@@ -116,7 +116,8 @@ task('lz:oft:send', 'Sends OFT tokens cross‐chain from any supported chain')
             if (!args.oftAddress) {
                 throw new Error('Starknet send requires oftAddress')
             }
-            const { sendStarknet } = await import('../starknet/sendStarknet')
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { sendStarknet } = require('../starknet/sendStarknet')
             result = await sendStarknet({
                 ...(args as StarknetArgs),
                 oftAddress: args.oftAddress,

examples/oft-main/tasks/common/wire.ts

@@ -235,7 +235,15 @@ task(TASK_LZ_OAPP_WIRE)
                         if (endpointIdToChainType(eid) !== ChainType.STARKNET) {
                             throw new Error('Not a Starknet EID')
                         }
-                        return starknetSignerFactory(eid)
+                        try {
+                            logger.debug(`Creating Starknet signer for eid ${eid}`)
+                            const signer = await starknetSignerFactory(eid)
+                            logger.debug(`Successfully created Starknet signer for eid ${eid}`)
+                            return signer
+                        } catch (error) {
+                            logger.error(`Failed to create Starknet signer for eid ${eid}: ${error}`)
+                            throw error
+                        }
                     },
                     aptosSignerFactory,
                     ...(solanaSignerFactory ? [solanaSignerFactory] : []),

examples/oft-main/tasks/starknet/sendStarknet.ts

@@ -1,10 +1,6 @@
-import fs from 'node:fs'
-import { createRequire } from 'node:module'
-import path from 'node:path'
-
 import { Contract } from 'starknet'
 
-import { createConnectionFactory } from '@layerzerolabs/devtools-starknet'
+import { createConnectionFactory, createRpcUrlFactory } from '@layerzerolabs/devtools-starknet'
 import { EndpointId, Stage, endpointIdToStage } from '@layerzerolabs/lz-definitions'
 
 import { SendResult } from '../common/types'
@@ -13,27 +9,21 @@ import { parseDecimalToUnits } from '../solana/utils'
 
 import { assertStarknetEid, getStarknetAccountFromEnv } from './utils'
 
-const hexToBytes = (value?: string) =>
-    value ? Uint8Array.from(Buffer.from(value.replace(/^0x/, ''), 'hex')) : new Uint8Array()
-
-const toCairoByteArray = (hex?: string) => {
-    const clean = (hex ?? '').replace(/^0x/, '')
-    if (!clean) {
-        return { data: [], pending_word: '0x0', pending_word_len: 0 }
-    }
-    const bytes = Buffer.from(clean, 'hex')
-    const chunkSize = 31
-    const data: string[] = []
-    for (let offset = 0; offset + chunkSize <= bytes.length; offset += chunkSize) {
-        data.push(`0x${bytes.subarray(offset, offset + chunkSize).toString('hex')}`)
-    }
-    const remainder = bytes.length % chunkSize
-    const pendingBytes = remainder ? bytes.subarray(bytes.length - remainder) : Buffer.alloc(0)
-    return {
-        data,
-        pending_word: pendingBytes.length ? `0x${pendingBytes.toString('hex')}` : '0x0',
-        pending_word_len: pendingBytes.length,
+/**
+ * Convert hex string to a string for Cairo ByteArray.
+ * In starknet.js v8, ByteArray parameters accept plain strings.
+ *
+ * NOTE: This uses latin1 encoding which can be corrupted by starknet.js's
+ * UTF-8 re-encoding for bytes >= 128. For enforced options which typically
+ * contain 0x80-0xFF bytes, use hexToByteArrayCalldata() with raw calldata.
+ */
+const hexToString = (hex?: string): string => {
+    if (!hex || hex === '0x' || hex === '') {
+        return ''
     }
+    const clean = hex.replace(/^0x/, '')
+    const buffer = Buffer.from(clean, 'hex')
+    return buffer.toString('latin1')
 }
 
 export interface StarknetArgs {
@@ -61,12 +51,12 @@ export async function sendStarknet({
 }: StarknetArgs): Promise<SendResult> {
     assertStarknetEid(srcEid)
 
-    const providerFactory = createConnectionFactory()
+    // Use createRpcUrlFactory() to read from environment variables (RPC_URL_STARKNET)
+    const providerFactory = createConnectionFactory(createRpcUrlFactory())
     const provider = await providerFactory(srcEid)
     const account = await getStarknetAccountFromEnv(srcEid)
 
-    const oftContract = await getOftMintBurnAdapterContract(oftAddress, provider)
-    oftContract.connect(account)
+    const oftContract = await getOftMintBurnAdapterContract(oftAddress, account)
 
     const amountUnits = parseDecimalToUnits(amount, tokenDecimals)
     const minAmountUnits = minAmount ? parseDecimalToUnits(minAmount, tokenDecimals) : amountUnits
@@ -76,9 +66,9 @@ export async function sendStarknet({
         to: { value: BigInt(to) },
         amount_ld: amountUnits,
         min_amount_ld: minAmountUnits,
-        extra_options: toCairoByteArray(extraOptions),
-        compose_msg: toCairoByteArray(composeMsg),
-        oft_cmd: toCairoByteArray(),
+        extra_options: hexToString(extraOptions),
+        compose_msg: hexToString(composeMsg),
+        oft_cmd: hexToString(),
     }
 
     const feeQuote = await oftContract.quote_send(sendParam, false)
@@ -103,35 +93,17 @@ export async function sendStarknet({
 }
 
 function getOftMintBurnAdapterAbi(): unknown {
-    const require = createRequire(import.meta.url)
-    const pkgRoot = path.dirname(require.resolve('@layerzerolabs/oft-mint-burn-starknet/package.json'))
-    const candidates = [
-        'dist/generated/abi/o-f-t-mint-burn-adapter.cjs',
-        'dist/generated/abi/o-f-t-mint-burn-adapter.js',
-        'contracts/oft_mint_burn/target/release/oft_mint_burn_OFTMintBurnAdapter.contract_class.json',
-        'contracts/oft_mint_burn/target/dev/oft_mint_burn_OFTMintBurnAdapter.contract_class.json',
-        'contracts/oft_mint_burn/target/release/oft_mint_burn_OFTMintBurnAdapter.compiled_contract_class.json',
-        'contracts/oft_mint_burn/target/dev/oft_mint_burn_OFTMintBurnAdapter.compiled_contract_class.json',
-    ]
-
-    for (const relPath of candidates) {
-        const fullPath = path.join(pkgRoot, relPath)
-        if (fs.existsSync(fullPath)) {
-            if (fullPath.endsWith('.js') || fullPath.endsWith('.cjs')) {
-                return require(fullPath)
-            }
-            const json = JSON.parse(fs.readFileSync(fullPath, 'utf8'))
-            return json.abi ?? json
-        }
+    // Load the ABI from the package's main export
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require('@layerzerolabs/oft-mint-burn-starknet')
+    const abi = pkg.abi?.oFTMintBurnAdapter
+    if (!abi) {
+        throw new Error('Unable to locate OFTMintBurnAdapter ABI in @layerzerolabs/oft-mint-burn-starknet')
     }
-
-    throw new Error('Unable to locate OFTMintBurnAdapter ABI in @layerzerolabs/oft-mint-burn-starknet')
+    return abi
 }
 
-async function getOftMintBurnAdapterContract(
-    address: string,
-    provider: ReturnType<typeof createConnectionFactory> extends () => Promise<infer T> ? T : never
-) {
+async function getOftMintBurnAdapterContract(address: string, providerOrAccount: any) {
     const abi = getOftMintBurnAdapterAbi()
-    return new Contract({ abi: abi as any, address, providerOrAccount: provider as any })
+    return new Contract({ abi: abi as any, address, providerOrAccount })
 }

examples/oft-main/tasks/starknet/utils.ts

@@ -1,7 +1,7 @@
 import { Account } from 'starknet'
 
 import { formatEid } from '@layerzerolabs/devtools'
-import { createConnectionFactory } from '@layerzerolabs/devtools-starknet'
+import { createConnectionFactory, createRpcUrlFactory } from '@layerzerolabs/devtools-starknet'
 import { ChainType, EndpointId, Stage, endpointIdToChainType, endpointIdToStage } from '@layerzerolabs/lz-definitions'
 
 export function assertStarknetEid(eid: EndpointId) {
@@ -23,6 +23,9 @@ export async function getStarknetAccountFromEnv(eid: EndpointId): Promise<Accoun
         throw new Error('STARKNET_ACCOUNT_ADDRESS and STARKNET_PRIVATE_KEY are required')
     }
 
-    const providerFactory = createConnectionFactory()
-    return new Account(await providerFactory(eid), address, privateKey)
+    // Use createRpcUrlFactory() to read from environment variables (RPC_URL_STARKNET)
+    const providerFactory = createConnectionFactory(createRpcUrlFactory())
+    const provider = await providerFactory(eid)
+    // starknet.js v8+ uses an options object for Account constructor
+    return new Account({ provider, address, signer: privateKey })
 }

packages/devtools/src/common/bytes.ts

@@ -134,7 +134,6 @@ export const denormalizePeer = (bytes: Uint8Array | null | undefined, eid: Endpo
         case ChainType.APTOS:
         case ChainType.SUI:
         case ChainType.STARKNET:
-
             return toHex(toBytes32(bytes))
 
         case ChainType.EVM:
@@ -197,10 +196,18 @@ export const toHex = (bytes: Uint8Array): string => `0x${Buffer.from(bytes).toSt
 /**
  * Helper utility to convert a hex string (with or without leading `0x`) to `UInt8Array`
  *
+ * Note: Buffer.from(str, 'hex') silently truncates the last character if the string
+ * has odd length. We pad with a leading '0' to prevent data loss.
+ *
  * @param {string} hex
  * @returns {Uint8Array}
  */
-export const fromHex = (hex: string): Uint8Array => Uint8Array.from(Buffer.from(hex.replace(/^0x/, ''), 'hex'))
+export const fromHex = (hex: string): Uint8Array => {
+    const stripped = hex.replace(/^0x/, '')
+    // Pad with leading '0' if odd length to prevent Buffer.from truncation
+    const padded = stripped.length % 2 === 1 ? '0' + stripped : stripped
+    return Uint8Array.from(Buffer.from(padded, 'hex'))
+}
 
 /**
  * Helper utility that returns the leftmost bytes after removing the rightmost `length` bytes from a UInt8Array.