genlayer-js 0.24.0 → 0.26.0

package/README.md

@@ -152,6 +152,22 @@ console.log(childTxIds);
 // ["0xabc...", "0xdef..."]
 ```
 
+### Debugging transaction execution
+
+Use `debugTraceTransaction` to inspect the full execution trace of a transaction, including return data, errors, and GenVM logs:
+
+```typescript
+const trace = await client.debugTraceTransaction({
+  hash: txHash,
+  round: 0, // optional, defaults to 0
+});
+
+console.log(trace.result_code);  // 0=success, 1=user error, 2=VM error
+console.log(trace.return_data);  // hex-encoded contract return data
+console.log(trace.stderr);       // standard error output
+console.log(trace.genvm_log);    // detailed GenVM execution logs
+```
+
 ### Staking Operations
 
 The SDK provides staking functionality for validators and delegators on testnet-bradbury (and testnet-asimov).

package/dist/{index-BJI82mwC.d.cts → index-BVTLJo0j.d.cts}

@@ -150,6 +150,18 @@ type DecodedCallData = {
     leaderOnly?: boolean;
     type: TransactionType;
 };
+type DebugTraceResult = {
+    transaction_id: string;
+    result_code: number;
+    return_data: string;
+    stdout: string;
+    stderr: string;
+    genvm_log: Record<string, unknown>[];
+    storage_proof: string;
+    run_time: string;
+    eq_outputs: string[];
+    stored_at?: string;
+};
 interface LeaderReceipt {
     calldata: string;
     class_name: string;
@@ -2886,4 +2898,4 @@ type GenLayerClient<TGenLayerChain extends GenLayerChain> = Omit<Client<Transpor
     }) => Promise<bigint>;
 } & StakingActions;
 
-export { type ValidatorExitOptions as $, type StakingContract as A, type ValidatorView as B, type CalldataEncodable as C, type DecodedDeployData as D, ExecutionResult as E, type ValidatorIdentity as F, type GenLayerClient as G, type Hash as H, type ValidatorInfo as I, type PendingWithdrawal as J, type BannedValidatorInfo as K, type LeaderReceipt as L, type MethodDescription as M, type Network as N, type StakeInfo as O, type PendingDeposit as P, type EpochData as Q, type EpochInfo as R, STAKING_ABI as S, type TransactionDataElement as T, type StakingTransactionResult as U, VALIDATOR_WALLET_ABI as V, type WithdrawalCommit as W, type ValidatorJoinResult as X, type DelegatorJoinResult as Y, type ValidatorJoinOptions as Z, type ValidatorDepositOptions as _, type DecodedCallData as a, type ValidatorClaimOptions as a0, type ValidatorPrimeOptions as a1, type SetOperatorOptions as a2, type SetIdentityOptions as a3, type DelegatorJoinOptions as a4, type DelegatorExitOptions as a5, type DelegatorClaimOptions as a6, type StakingActions as a7, type GenLayerRawTransaction as b, type GenLayerTransaction as c, type ContractSchema as d, CalldataAddress as e, type GenLayerMethod as f, type ContractParamsArraySchemaElement as g, type ContractParamsSchema as h, type ContractMethodBase as i, type ContractMethod as j, type TransactionHash as k, TransactionStatus as l, TransactionResult as m, transactionsStatusNameToNumber as n, DECIDED_STATES as o, isDecidedState as p, transactionResultNumberToName as q, TransactionResultNameToNumber as r, executionResultNumberToName as s, transactionsStatusNumberToName as t, VoteType as u, voteTypeNumberToName as v, voteTypeNameToNumber as w, type TransactionType as x, TransactionHashVariant as y, type SnapSource as z };
+export { type ValidatorDepositOptions as $, type SnapSource as A, type StakingContract as B, type CalldataEncodable as C, type DecodedDeployData as D, ExecutionResult as E, type ValidatorView as F, type GenLayerClient as G, type Hash as H, type ValidatorIdentity as I, type ValidatorInfo as J, type PendingWithdrawal as K, type LeaderReceipt as L, type MethodDescription as M, type Network as N, type BannedValidatorInfo as O, type PendingDeposit as P, type StakeInfo as Q, type EpochData as R, STAKING_ABI as S, type TransactionDataElement as T, type EpochInfo as U, VALIDATOR_WALLET_ABI as V, type WithdrawalCommit as W, type StakingTransactionResult as X, type ValidatorJoinResult as Y, type DelegatorJoinResult as Z, type ValidatorJoinOptions as _, type DecodedCallData as a, type ValidatorExitOptions as a0, type ValidatorClaimOptions as a1, type ValidatorPrimeOptions as a2, type SetOperatorOptions as a3, type SetIdentityOptions as a4, type DelegatorJoinOptions as a5, type DelegatorExitOptions as a6, type DelegatorClaimOptions as a7, type StakingActions as a8, type GenLayerRawTransaction as b, type GenLayerTransaction as c, type ContractSchema as d, CalldataAddress as e, type GenLayerMethod as f, type ContractParamsArraySchemaElement as g, type ContractParamsSchema as h, type ContractMethodBase as i, type ContractMethod as j, type TransactionHash as k, TransactionStatus as l, TransactionResult as m, transactionsStatusNameToNumber as n, DECIDED_STATES as o, isDecidedState as p, transactionResultNumberToName as q, TransactionResultNameToNumber as r, executionResultNumberToName as s, transactionsStatusNumberToName as t, VoteType as u, voteTypeNumberToName as v, voteTypeNameToNumber as w, type TransactionType as x, TransactionHashVariant as y, type DebugTraceResult as z };

package/dist/{index-DEWwFm0_.d.ts → index-Dc8L54mZ.d.ts}

@@ -150,6 +150,18 @@ type DecodedCallData = {
     leaderOnly?: boolean;
     type: TransactionType;
 };
+type DebugTraceResult = {
+    transaction_id: string;
+    result_code: number;
+    return_data: string;
+    stdout: string;
+    stderr: string;
+    genvm_log: Record<string, unknown>[];
+    storage_proof: string;
+    run_time: string;
+    eq_outputs: string[];
+    stored_at?: string;
+};
 interface LeaderReceipt {
     calldata: string;
     class_name: string;
@@ -2886,4 +2898,4 @@ type GenLayerClient<TGenLayerChain extends GenLayerChain> = Omit<Client<Transpor
     }) => Promise<bigint>;
 } & StakingActions;
 
-export { type ValidatorExitOptions as $, type StakingContract as A, type ValidatorView as B, type CalldataEncodable as C, type DecodedDeployData as D, ExecutionResult as E, type ValidatorIdentity as F, type GenLayerClient as G, type Hash as H, type ValidatorInfo as I, type PendingWithdrawal as J, type BannedValidatorInfo as K, type LeaderReceipt as L, type MethodDescription as M, type Network as N, type StakeInfo as O, type PendingDeposit as P, type EpochData as Q, type EpochInfo as R, STAKING_ABI as S, type TransactionDataElement as T, type StakingTransactionResult as U, VALIDATOR_WALLET_ABI as V, type WithdrawalCommit as W, type ValidatorJoinResult as X, type DelegatorJoinResult as Y, type ValidatorJoinOptions as Z, type ValidatorDepositOptions as _, type DecodedCallData as a, type ValidatorClaimOptions as a0, type ValidatorPrimeOptions as a1, type SetOperatorOptions as a2, type SetIdentityOptions as a3, type DelegatorJoinOptions as a4, type DelegatorExitOptions as a5, type DelegatorClaimOptions as a6, type StakingActions as a7, type GenLayerRawTransaction as b, type GenLayerTransaction as c, type ContractSchema as d, CalldataAddress as e, type GenLayerMethod as f, type ContractParamsArraySchemaElement as g, type ContractParamsSchema as h, type ContractMethodBase as i, type ContractMethod as j, type TransactionHash as k, TransactionStatus as l, TransactionResult as m, transactionsStatusNameToNumber as n, DECIDED_STATES as o, isDecidedState as p, transactionResultNumberToName as q, TransactionResultNameToNumber as r, executionResultNumberToName as s, transactionsStatusNumberToName as t, VoteType as u, voteTypeNumberToName as v, voteTypeNameToNumber as w, type TransactionType as x, TransactionHashVariant as y, type SnapSource as z };
+export { type ValidatorDepositOptions as $, type SnapSource as A, type StakingContract as B, type CalldataEncodable as C, type DecodedDeployData as D, ExecutionResult as E, type ValidatorView as F, type GenLayerClient as G, type Hash as H, type ValidatorIdentity as I, type ValidatorInfo as J, type PendingWithdrawal as K, type LeaderReceipt as L, type MethodDescription as M, type Network as N, type BannedValidatorInfo as O, type PendingDeposit as P, type StakeInfo as Q, type EpochData as R, STAKING_ABI as S, type TransactionDataElement as T, type EpochInfo as U, VALIDATOR_WALLET_ABI as V, type WithdrawalCommit as W, type StakingTransactionResult as X, type ValidatorJoinResult as Y, type DelegatorJoinResult as Z, type ValidatorJoinOptions as _, type DecodedCallData as a, type ValidatorExitOptions as a0, type ValidatorClaimOptions as a1, type ValidatorPrimeOptions as a2, type SetOperatorOptions as a3, type SetIdentityOptions as a4, type DelegatorJoinOptions as a5, type DelegatorExitOptions as a6, type DelegatorClaimOptions as a7, type StakingActions as a8, type GenLayerRawTransaction as b, type GenLayerTransaction as c, type ContractSchema as d, CalldataAddress as e, type GenLayerMethod as f, type ContractParamsArraySchemaElement as g, type ContractParamsSchema as h, type ContractMethodBase as i, type ContractMethod as j, type TransactionHash as k, TransactionStatus as l, TransactionResult as m, transactionsStatusNameToNumber as n, DECIDED_STATES as o, isDecidedState as p, transactionResultNumberToName as q, TransactionResultNameToNumber as r, executionResultNumberToName as s, transactionsStatusNumberToName as t, VoteType as u, voteTypeNumberToName as v, voteTypeNameToNumber as w, type TransactionType as x, TransactionHashVariant as y, type DebugTraceResult as z };

package/dist/index.cjs

@@ -530,6 +530,7 @@ function extractGenCallResult(result) {
 }
 var contractActions = (client, publicClient) => {
   return {
+    /** Retrieves the source code of a deployed contract. Localnet only. */
     getContractCode: async (address) => {
       if (client.chain.id !== _chunkNOMVZBCRcjs.localnet.id) {
         throw new Error("Getting contract code is not supported on this network");
@@ -541,6 +542,7 @@ var contractActions = (client, publicClient) => {
       const codeBytes = b64ToArray(result);
       return new TextDecoder().decode(codeBytes);
     },
+    /** Gets the schema (methods and constructor) of a deployed contract. Localnet only. */
     getContractSchema: async (address) => {
       if (client.chain.id !== _chunkNOMVZBCRcjs.localnet.id) {
         throw new Error("Contract schema is not supported on this network");
@@ -551,6 +553,7 @@ var contractActions = (client, publicClient) => {
       });
       return schema;
     },
+    /** Generates a schema for contract code without deploying it. Localnet only. */
     getContractSchemaForCode: async (contractCode) => {
       if (client.chain.id !== _chunkNOMVZBCRcjs.localnet.id) {
         throw new Error("Contract schema is not supported on this network");
@@ -561,6 +564,7 @@ var contractActions = (client, publicClient) => {
       });
       return schema;
     },
+    /** Executes a read-only contract call without modifying state. */
     readContract: async (args) => {
       const {
         account,
@@ -597,6 +601,7 @@ var contractActions = (client, publicClient) => {
       }
       return toJsonSafeDeep(decoded);
     },
+    /** Simulates a state-modifying contract call without executing on-chain. */
     simulateWriteContract: async (args) => {
       const {
         account,
@@ -628,6 +633,7 @@ var contractActions = (client, publicClient) => {
       const resultBinary = _viem.fromHex.call(void 0, prefixedResult, "bytes");
       return decode(resultBinary);
     },
+    /** Executes a state-modifying function on a contract through consensus. Returns the transaction hash. */
     writeContract: async (args) => {
       const {
         account,
@@ -658,6 +664,7 @@ var contractActions = (client, publicClient) => {
         value
       });
     },
+    /** Deploys a new intelligent contract to GenLayer. Returns the transaction hash. */
     deployContract: async (args) => {
       const {
         account,
@@ -689,6 +696,7 @@ var contractActions = (client, publicClient) => {
         senderAccount
       });
     },
+    /** Calculates the minimum bond required to appeal a transaction. */
     getMinAppealBond: async (args) => {
       const { txId } = args;
       if (!_optionalChain([client, 'access', _11 => _11.chain, 'access', _12 => _12.feeManagerContract, 'optionalAccess', _13 => _13.address]) || !_optionalChain([client, 'access', _14 => _14.chain, 'access', _15 => _15.roundsStorageContract, 'optionalAccess', _16 => _16.address])) {
@@ -710,6 +718,7 @@ var contractActions = (client, publicClient) => {
       });
       return minBond;
     },
+    /** Appeals a consensus transaction to trigger a new round of validation. */
     appealTransaction: async (args) => {
       const { account, txId } = args;
       let { value } = args;
@@ -1235,6 +1244,7 @@ var decodeLocalnetTransaction = (tx) => {
 
 // src/transactions/actions.ts
 var receiptActions = (client, publicClient) => ({
+  /** Polls until a transaction reaches the specified status. Returns the transaction receipt. */
   waitForTransactionReceipt: async ({
     hash,
     status = "ACCEPTED" /* ACCEPTED */,
@@ -1274,6 +1284,7 @@ var receiptActions = (client, publicClient) => ({
   }
 });
 var transactionActions = (client, publicClient) => ({
+  /** Fetches transaction data including status, execution result, and consensus details. */
   getTransaction: async ({ hash }) => {
     if (client.chain.isStudio) {
       const transaction2 = await client.getTransaction({ hash });
@@ -1306,6 +1317,7 @@ var transactionActions = (client, publicClient) => ({
     };
     return decodeTransaction(transaction);
   },
+  /** Returns transaction IDs of child transactions created from emitted messages. */
   getTriggeredTransactionIds: async ({ hash }) => {
     if (client.chain.isStudio) {
       const tx2 = await client.getTransaction({ hash });
@@ -1328,6 +1340,15 @@ var transactionActions = (client, publicClient) => ({
     });
     return logs.map((log) => log.topics[1]).filter(Boolean);
   },
+  /** Fetches the full execution trace including return data, stdout, stderr, and GenVM logs. */
+  debugTraceTransaction: async ({ hash, round = 0 }) => {
+    const result = await client.request({
+      method: "gen_dbg_traceTransaction",
+      params: [{ txID: hash, round }]
+    });
+    return result;
+  },
+  /** Cancels a pending transaction. Studio networks only. */
   cancelTransaction: async ({ hash }) => {
     if (!client.chain.isStudio) {
       throw new Error("cancelTransaction is only available on studio-based chains (localnet/studionet)");
@@ -1355,6 +1376,7 @@ var transactionActions = (client, publicClient) => ({
       params: [hash, signature]
     });
   },
+  /** Estimates gas required for a transaction. */
   estimateTransactionGas: async (transactionParams) => {
     const formattedParams = {
       from: transactionParams.from || _optionalChain([client, 'access', _108 => _108.account, 'optionalAccess', _109 => _109.address]),
@@ -1642,6 +1664,7 @@ var stakingActions = (client, publicClient) => {
     });
   };
   return {
+    /** Joins as a validator with the specified stake amount. */
     validatorJoin: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const stakingAddress = getStakingAddress();
@@ -1683,6 +1706,7 @@ var stakingActions = (client, publicClient) => {
         amountRaw: amount
       };
     },
+    /** Adds additional self-stake to an active validator position. */
     validatorDeposit: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const data = _viem.encodeFunctionData.call(void 0, {
@@ -1691,6 +1715,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data, value: amount });
     },
+    /** Exits a validator position by burning the specified shares. */
     validatorExit: async (options) => {
       const shares = typeof options.shares === "string" ? BigInt(options.shares) : options.shares;
       const data = _viem.encodeFunctionData.call(void 0, {
@@ -1700,6 +1725,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Claims pending validator withdrawals. */
     validatorClaim: async (options) => {
       if (!_optionalChain([options, 'optionalAccess', _124 => _124.validator]) && !client.account) {
         throw new Error("Either provide validator address or initialize client with an account");
@@ -1713,6 +1739,7 @@ var stakingActions = (client, publicClient) => {
       const result = await executeWrite({ to: getStakingAddress(), data });
       return { ...result, claimedAmount: 0n };
     },
+    /** Primes a validator for participation in the next epoch. */
     validatorPrime: async (options) => {
       const data = _viem.encodeFunctionData.call(void 0, {
         abi: _chunkNOMVZBCRcjs.STAKING_ABI,
@@ -1721,6 +1748,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Sets the operator address for a validator wallet. */
     setOperator: async (options) => {
       const data = _viem.encodeFunctionData.call(void 0, {
         abi: _chunkNOMVZBCRcjs.VALIDATOR_WALLET_ABI,
@@ -1729,6 +1757,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: options.validator, data });
     },
+    /** Sets validator identity information (name, website, social links). */
     setIdentity: async (options) => {
       let extraCidBytes = "0x";
       if (options.extraCid) {
@@ -1755,6 +1784,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: options.validator, data });
     },
+    /** Delegates stake to a validator. */
     delegatorJoin: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const data = _viem.encodeFunctionData.call(void 0, {
@@ -1771,6 +1801,7 @@ var stakingActions = (client, publicClient) => {
         amountRaw: amount
       };
     },
+    /** Exits a delegation by burning the specified shares. */
     delegatorExit: async (options) => {
       const shares = typeof options.shares === "string" ? BigInt(options.shares) : options.shares;
       const data = _viem.encodeFunctionData.call(void 0, {
@@ -1780,6 +1811,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Claims pending delegator withdrawals. */
     delegatorClaim: async (options) => {
       if (!options.delegator && !client.account) {
         throw new Error("Either provide delegator address or initialize client with an account");
@@ -1792,10 +1824,12 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Checks if an address is an active validator. */
     isValidator: async (address) => {
       const contract = getReadOnlyStakingContract();
       return contract.read.isValidator([address]);
     },
+    /** Returns comprehensive information about a validator including stake, identity, and status. */
     getValidatorInfo: async (validator) => {
       const contract = getReadOnlyStakingContract();
       const isVal = await contract.read.isValidator([validator]);
@@ -1875,6 +1909,7 @@ var stakingActions = (client, publicClient) => {
         pendingWithdrawals
       };
     },
+    /** Returns delegation stake information for a delegator-validator pair. */
     getStakeInfo: async (delegator, validator) => {
       const contract = getReadOnlyStakingContract();
       const shares = await contract.read.sharesOf([delegator, validator]);
@@ -1928,6 +1963,7 @@ var stakingActions = (client, publicClient) => {
         pendingWithdrawals
       };
     },
+    /** Returns current epoch information including timing, stake requirements, and inflation data. */
     getEpochInfo: async () => {
       const contract = getReadOnlyStakingContract();
       const [
@@ -1984,6 +2020,7 @@ var stakingActions = (client, publicClient) => {
         delegatorMinStakeRaw: delMinStake
       };
     },
+    /** Returns detailed data for a specific epoch. */
     getEpochData: async (epochNumber) => {
       const contract = getReadOnlyStakingContract();
       const [currentEpoch, epochOdd, epochEven] = await Promise.all([
@@ -2012,19 +2049,23 @@ var stakingActions = (client, publicClient) => {
         slashed: raw[10]
       };
     },
+    /** Returns addresses of all currently active validators. */
     getActiveValidators: async () => {
       const contract = getReadOnlyStakingContract();
       const validators = await contract.read.activeValidators();
       return validators.filter((v) => v !== "0x0000000000000000000000000000000000000000");
     },
+    /** Returns the count of active validators. */
     getActiveValidatorsCount: async () => {
       const contract = getReadOnlyStakingContract();
       return contract.read.activeValidatorsCount();
     },
+    /** Returns addresses of validators currently in quarantine. */
     getQuarantinedValidators: async () => {
       const contract = getReadOnlyStakingContract();
       return contract.read.getValidatorQuarantineList();
     },
+    /** Returns banned validators with ban duration and permanent ban status. */
     getBannedValidators: async (startIndex = 0n, size = 100n) => {
       const contract = getReadOnlyStakingContract();
       const result = await contract.read.getAllBannedValidators([startIndex, size]);
@@ -2034,6 +2075,7 @@ var stakingActions = (client, publicClient) => {
         permanentlyBanned: v.permanentlyBanned
       }));
     },
+    /** Returns detailed quarantine information with pagination. */
     getQuarantinedValidatorsDetailed: async (startIndex = 0n, size = 100n) => {
       const contract = getReadOnlyStakingContract();
       const result = await contract.read.getAllQuarantinedValidators([startIndex, size]);

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as viem from 'viem';
 import { Account, Address, Hex } from 'viem';
 import { G as GenLayerChain } from './chains-DqSbucSW.cjs';
-import { G as GenLayerClient, D as DecodedDeployData, a as DecodedCallData, b as GenLayerRawTransaction, c as GenLayerTransaction, C as CalldataEncodable, T as TransactionDataElement, S as STAKING_ABI, V as VALIDATOR_WALLET_ABI, d as ContractSchema } from './index-BJI82mwC.cjs';
+import { G as GenLayerClient, D as DecodedDeployData, a as DecodedCallData, b as GenLayerRawTransaction, c as GenLayerTransaction, C as CalldataEncodable, T as TransactionDataElement, S as STAKING_ABI, V as VALIDATOR_WALLET_ABI, d as ContractSchema } from './index-BVTLJo0j.cjs';
 import * as abitype from 'abitype';
 import * as viem__types_types_authorization from 'viem/_types/types/authorization';
 import * as viem_accounts from 'viem/accounts';
@@ -32,6 +32,16 @@ interface ClientConfig {
     account?: Account | Address;
     provider?: EthereumProvider;
 }
+/**
+ * Creates a GenLayer client instance for interacting with the network.
+ *
+ * @param config - Client configuration options
+ * @param config.chain - Chain to connect to (localnet, testnetBradbury, etc.)
+ * @param config.endpoint - Custom RPC endpoint URL
+ * @param config.account - Account or address for signing transactions
+ * @param config.provider - EthereumProvider for wallet integration
+ * @returns Configured client with contract, transaction, and staking methods
+ */
 declare const createClient: (config?: ClientConfig) => GenLayerClient<GenLayerChain>;
 
 declare const generatePrivateKey: () => `0x${string}`;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as viem from 'viem';
 import { Account, Address, Hex } from 'viem';
 import { G as GenLayerChain } from './chains-DqSbucSW.js';
-import { G as GenLayerClient, D as DecodedDeployData, a as DecodedCallData, b as GenLayerRawTransaction, c as GenLayerTransaction, C as CalldataEncodable, T as TransactionDataElement, S as STAKING_ABI, V as VALIDATOR_WALLET_ABI, d as ContractSchema } from './index-DEWwFm0_.js';
+import { G as GenLayerClient, D as DecodedDeployData, a as DecodedCallData, b as GenLayerRawTransaction, c as GenLayerTransaction, C as CalldataEncodable, T as TransactionDataElement, S as STAKING_ABI, V as VALIDATOR_WALLET_ABI, d as ContractSchema } from './index-Dc8L54mZ.js';
 import * as abitype from 'abitype';
 import * as viem__types_types_authorization from 'viem/_types/types/authorization';
 import * as viem_accounts from 'viem/accounts';
@@ -32,6 +32,16 @@ interface ClientConfig {
     account?: Account | Address;
     provider?: EthereumProvider;
 }
+/**
+ * Creates a GenLayer client instance for interacting with the network.
+ *
+ * @param config - Client configuration options
+ * @param config.chain - Chain to connect to (localnet, testnetBradbury, etc.)
+ * @param config.endpoint - Custom RPC endpoint URL
+ * @param config.account - Account or address for signing transactions
+ * @param config.provider - EthereumProvider for wallet integration
+ * @returns Configured client with contract, transaction, and staking methods
+ */
 declare const createClient: (config?: ClientConfig) => GenLayerClient<GenLayerChain>;
 
 declare const generatePrivateKey: () => `0x${string}`;

package/dist/index.js

@@ -530,6 +530,7 @@ function extractGenCallResult(result) {
 }
 var contractActions = (client, publicClient) => {
   return {
+    /** Retrieves the source code of a deployed contract. Localnet only. */
     getContractCode: async (address) => {
       if (client.chain.id !== localnet.id) {
         throw new Error("Getting contract code is not supported on this network");
@@ -541,6 +542,7 @@ var contractActions = (client, publicClient) => {
       const codeBytes = b64ToArray(result);
       return new TextDecoder().decode(codeBytes);
     },
+    /** Gets the schema (methods and constructor) of a deployed contract. Localnet only. */
     getContractSchema: async (address) => {
       if (client.chain.id !== localnet.id) {
         throw new Error("Contract schema is not supported on this network");
@@ -551,6 +553,7 @@ var contractActions = (client, publicClient) => {
       });
       return schema;
     },
+    /** Generates a schema for contract code without deploying it. Localnet only. */
     getContractSchemaForCode: async (contractCode) => {
       if (client.chain.id !== localnet.id) {
         throw new Error("Contract schema is not supported on this network");
@@ -561,6 +564,7 @@ var contractActions = (client, publicClient) => {
       });
       return schema;
     },
+    /** Executes a read-only contract call without modifying state. */
     readContract: async (args) => {
       const {
         account,
@@ -597,6 +601,7 @@ var contractActions = (client, publicClient) => {
       }
       return toJsonSafeDeep(decoded);
     },
+    /** Simulates a state-modifying contract call without executing on-chain. */
     simulateWriteContract: async (args) => {
       const {
         account,
@@ -628,6 +633,7 @@ var contractActions = (client, publicClient) => {
       const resultBinary = fromHex(prefixedResult, "bytes");
       return decode(resultBinary);
     },
+    /** Executes a state-modifying function on a contract through consensus. Returns the transaction hash. */
     writeContract: async (args) => {
       const {
         account,
@@ -658,6 +664,7 @@ var contractActions = (client, publicClient) => {
         value
       });
     },
+    /** Deploys a new intelligent contract to GenLayer. Returns the transaction hash. */
     deployContract: async (args) => {
       const {
         account,
@@ -689,6 +696,7 @@ var contractActions = (client, publicClient) => {
         senderAccount
       });
     },
+    /** Calculates the minimum bond required to appeal a transaction. */
     getMinAppealBond: async (args) => {
       const { txId } = args;
       if (!client.chain.feeManagerContract?.address || !client.chain.roundsStorageContract?.address) {
@@ -710,6 +718,7 @@ var contractActions = (client, publicClient) => {
       });
       return minBond;
     },
+    /** Appeals a consensus transaction to trigger a new round of validation. */
     appealTransaction: async (args) => {
       const { account, txId } = args;
       let { value } = args;
@@ -1235,6 +1244,7 @@ var decodeLocalnetTransaction = (tx) => {
 
 // src/transactions/actions.ts
 var receiptActions = (client, publicClient) => ({
+  /** Polls until a transaction reaches the specified status. Returns the transaction receipt. */
   waitForTransactionReceipt: async ({
     hash,
     status = "ACCEPTED" /* ACCEPTED */,
@@ -1274,6 +1284,7 @@ var receiptActions = (client, publicClient) => ({
   }
 });
 var transactionActions = (client, publicClient) => ({
+  /** Fetches transaction data including status, execution result, and consensus details. */
   getTransaction: async ({ hash }) => {
     if (client.chain.isStudio) {
       const transaction2 = await client.getTransaction({ hash });
@@ -1306,6 +1317,7 @@ var transactionActions = (client, publicClient) => ({
     };
     return decodeTransaction(transaction);
   },
+  /** Returns transaction IDs of child transactions created from emitted messages. */
   getTriggeredTransactionIds: async ({ hash }) => {
     if (client.chain.isStudio) {
       const tx2 = await client.getTransaction({ hash });
@@ -1328,6 +1340,15 @@ var transactionActions = (client, publicClient) => ({
     });
     return logs.map((log) => log.topics[1]).filter(Boolean);
   },
+  /** Fetches the full execution trace including return data, stdout, stderr, and GenVM logs. */
+  debugTraceTransaction: async ({ hash, round = 0 }) => {
+    const result = await client.request({
+      method: "gen_dbg_traceTransaction",
+      params: [{ txID: hash, round }]
+    });
+    return result;
+  },
+  /** Cancels a pending transaction. Studio networks only. */
   cancelTransaction: async ({ hash }) => {
     if (!client.chain.isStudio) {
       throw new Error("cancelTransaction is only available on studio-based chains (localnet/studionet)");
@@ -1355,6 +1376,7 @@ var transactionActions = (client, publicClient) => ({
       params: [hash, signature]
     });
   },
+  /** Estimates gas required for a transaction. */
   estimateTransactionGas: async (transactionParams) => {
     const formattedParams = {
       from: transactionParams.from || client.account?.address,
@@ -1642,6 +1664,7 @@ var stakingActions = (client, publicClient) => {
     });
   };
   return {
+    /** Joins as a validator with the specified stake amount. */
     validatorJoin: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const stakingAddress = getStakingAddress();
@@ -1683,6 +1706,7 @@ var stakingActions = (client, publicClient) => {
         amountRaw: amount
       };
     },
+    /** Adds additional self-stake to an active validator position. */
     validatorDeposit: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const data = encodeFunctionData2({
@@ -1691,6 +1715,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data, value: amount });
     },
+    /** Exits a validator position by burning the specified shares. */
     validatorExit: async (options) => {
       const shares = typeof options.shares === "string" ? BigInt(options.shares) : options.shares;
       const data = encodeFunctionData2({
@@ -1700,6 +1725,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Claims pending validator withdrawals. */
     validatorClaim: async (options) => {
       if (!options?.validator && !client.account) {
         throw new Error("Either provide validator address or initialize client with an account");
@@ -1713,6 +1739,7 @@ var stakingActions = (client, publicClient) => {
       const result = await executeWrite({ to: getStakingAddress(), data });
       return { ...result, claimedAmount: 0n };
     },
+    /** Primes a validator for participation in the next epoch. */
     validatorPrime: async (options) => {
       const data = encodeFunctionData2({
         abi: STAKING_ABI,
@@ -1721,6 +1748,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Sets the operator address for a validator wallet. */
     setOperator: async (options) => {
       const data = encodeFunctionData2({
         abi: VALIDATOR_WALLET_ABI,
@@ -1729,6 +1757,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: options.validator, data });
     },
+    /** Sets validator identity information (name, website, social links). */
     setIdentity: async (options) => {
       let extraCidBytes = "0x";
       if (options.extraCid) {
@@ -1755,6 +1784,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: options.validator, data });
     },
+    /** Delegates stake to a validator. */
     delegatorJoin: async (options) => {
       const amount = parseStakingAmount(options.amount);
       const data = encodeFunctionData2({
@@ -1771,6 +1801,7 @@ var stakingActions = (client, publicClient) => {
         amountRaw: amount
       };
     },
+    /** Exits a delegation by burning the specified shares. */
     delegatorExit: async (options) => {
       const shares = typeof options.shares === "string" ? BigInt(options.shares) : options.shares;
       const data = encodeFunctionData2({
@@ -1780,6 +1811,7 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Claims pending delegator withdrawals. */
     delegatorClaim: async (options) => {
       if (!options.delegator && !client.account) {
         throw new Error("Either provide delegator address or initialize client with an account");
@@ -1792,10 +1824,12 @@ var stakingActions = (client, publicClient) => {
       });
       return executeWrite({ to: getStakingAddress(), data });
     },
+    /** Checks if an address is an active validator. */
     isValidator: async (address) => {
       const contract = getReadOnlyStakingContract();
       return contract.read.isValidator([address]);
     },
+    /** Returns comprehensive information about a validator including stake, identity, and status. */
     getValidatorInfo: async (validator) => {
       const contract = getReadOnlyStakingContract();
       const isVal = await contract.read.isValidator([validator]);
@@ -1875,6 +1909,7 @@ var stakingActions = (client, publicClient) => {
         pendingWithdrawals
       };
     },
+    /** Returns delegation stake information for a delegator-validator pair. */
     getStakeInfo: async (delegator, validator) => {
       const contract = getReadOnlyStakingContract();
       const shares = await contract.read.sharesOf([delegator, validator]);
@@ -1928,6 +1963,7 @@ var stakingActions = (client, publicClient) => {
         pendingWithdrawals
       };
     },
+    /** Returns current epoch information including timing, stake requirements, and inflation data. */
     getEpochInfo: async () => {
       const contract = getReadOnlyStakingContract();
       const [
@@ -1984,6 +2020,7 @@ var stakingActions = (client, publicClient) => {
         delegatorMinStakeRaw: delMinStake
       };
     },
+    /** Returns detailed data for a specific epoch. */
     getEpochData: async (epochNumber) => {
       const contract = getReadOnlyStakingContract();
       const [currentEpoch, epochOdd, epochEven] = await Promise.all([
@@ -2012,19 +2049,23 @@ var stakingActions = (client, publicClient) => {
         slashed: raw[10]
       };
     },
+    /** Returns addresses of all currently active validators. */
     getActiveValidators: async () => {
       const contract = getReadOnlyStakingContract();
       const validators = await contract.read.activeValidators();
       return validators.filter((v) => v !== "0x0000000000000000000000000000000000000000");
     },
+    /** Returns the count of active validators. */
     getActiveValidatorsCount: async () => {
       const contract = getReadOnlyStakingContract();
       return contract.read.activeValidatorsCount();
     },
+    /** Returns addresses of validators currently in quarantine. */
     getQuarantinedValidators: async () => {
       const contract = getReadOnlyStakingContract();
       return contract.read.getValidatorQuarantineList();
     },
+    /** Returns banned validators with ban duration and permanent ban status. */
     getBannedValidators: async (startIndex = 0n, size = 100n) => {
       const contract = getReadOnlyStakingContract();
       const result = await contract.read.getAllBannedValidators([startIndex, size]);
@@ -2034,6 +2075,7 @@ var stakingActions = (client, publicClient) => {
         permanentlyBanned: v.permanentlyBanned
       }));
     },
+    /** Returns detailed quarantine information with pagination. */
     getQuarantinedValidatorsDetailed: async (startIndex = 0n, size = 100n) => {
       const contract = getReadOnlyStakingContract();
       const result = await contract.read.getAllQuarantinedValidators([startIndex, size]);

package/dist/types/index.d.cts

@@ -1,3 +1,3 @@
 export { Account, Address } from 'viem';
-export { K as BannedValidatorInfo, e as CalldataAddress, C as CalldataEncodable, j as ContractMethod, i as ContractMethodBase, g as ContractParamsArraySchemaElement, h as ContractParamsSchema, d as ContractSchema, o as DECIDED_STATES, a as DecodedCallData, D as DecodedDeployData, a6 as DelegatorClaimOptions, a5 as DelegatorExitOptions, a4 as DelegatorJoinOptions, Y as DelegatorJoinResult, Q as EpochData, R as EpochInfo, E as ExecutionResult, G as GenLayerClient, f as GenLayerMethod, b as GenLayerRawTransaction, c as GenLayerTransaction, H as Hash, L as LeaderReceipt, M as MethodDescription, N as Network, P as PendingDeposit, J as PendingWithdrawal, a3 as SetIdentityOptions, a2 as SetOperatorOptions, z as SnapSource, O as StakeInfo, a7 as StakingActions, A as StakingContract, U as StakingTransactionResult, k as TransactionHash, y as TransactionHashVariant, m as TransactionResult, r as TransactionResultNameToNumber, l as TransactionStatus, x as TransactionType, a0 as ValidatorClaimOptions, _ as ValidatorDepositOptions, $ as ValidatorExitOptions, F as ValidatorIdentity, I as ValidatorInfo, Z as ValidatorJoinOptions, X as ValidatorJoinResult, a1 as ValidatorPrimeOptions, B as ValidatorView, u as VoteType, W as WithdrawalCommit, s as executionResultNumberToName, p as isDecidedState, q as transactionResultNumberToName, n as transactionsStatusNameToNumber, t as transactionsStatusNumberToName, w as voteTypeNameToNumber, v as voteTypeNumberToName } from '../index-BJI82mwC.cjs';
+export { O as BannedValidatorInfo, e as CalldataAddress, C as CalldataEncodable, j as ContractMethod, i as ContractMethodBase, g as ContractParamsArraySchemaElement, h as ContractParamsSchema, d as ContractSchema, o as DECIDED_STATES, z as DebugTraceResult, a as DecodedCallData, D as DecodedDeployData, a7 as DelegatorClaimOptions, a6 as DelegatorExitOptions, a5 as DelegatorJoinOptions, Z as DelegatorJoinResult, R as EpochData, U as EpochInfo, E as ExecutionResult, G as GenLayerClient, f as GenLayerMethod, b as GenLayerRawTransaction, c as GenLayerTransaction, H as Hash, L as LeaderReceipt, M as MethodDescription, N as Network, P as PendingDeposit, K as PendingWithdrawal, a4 as SetIdentityOptions, a3 as SetOperatorOptions, A as SnapSource, Q as StakeInfo, a8 as StakingActions, B as StakingContract, X as StakingTransactionResult, k as TransactionHash, y as TransactionHashVariant, m as TransactionResult, r as TransactionResultNameToNumber, l as TransactionStatus, x as TransactionType, a1 as ValidatorClaimOptions, $ as ValidatorDepositOptions, a0 as ValidatorExitOptions, I as ValidatorIdentity, J as ValidatorInfo, _ as ValidatorJoinOptions, Y as ValidatorJoinResult, a2 as ValidatorPrimeOptions, F as ValidatorView, u as VoteType, W as WithdrawalCommit, s as executionResultNumberToName, p as isDecidedState, q as transactionResultNumberToName, n as transactionsStatusNameToNumber, t as transactionsStatusNumberToName, w as voteTypeNameToNumber, v as voteTypeNumberToName } from '../index-BVTLJo0j.cjs';
 export { G as GenLayerChain } from '../chains-DqSbucSW.cjs';

package/dist/types/index.d.ts

@@ -1,3 +1,3 @@
 export { Account, Address } from 'viem';
-export { K as BannedValidatorInfo, e as CalldataAddress, C as CalldataEncodable, j as ContractMethod, i as ContractMethodBase, g as ContractParamsArraySchemaElement, h as ContractParamsSchema, d as ContractSchema, o as DECIDED_STATES, a as DecodedCallData, D as DecodedDeployData, a6 as DelegatorClaimOptions, a5 as DelegatorExitOptions, a4 as DelegatorJoinOptions, Y as DelegatorJoinResult, Q as EpochData, R as EpochInfo, E as ExecutionResult, G as GenLayerClient, f as GenLayerMethod, b as GenLayerRawTransaction, c as GenLayerTransaction, H as Hash, L as LeaderReceipt, M as MethodDescription, N as Network, P as PendingDeposit, J as PendingWithdrawal, a3 as SetIdentityOptions, a2 as SetOperatorOptions, z as SnapSource, O as StakeInfo, a7 as StakingActions, A as StakingContract, U as StakingTransactionResult, k as TransactionHash, y as TransactionHashVariant, m as TransactionResult, r as TransactionResultNameToNumber, l as TransactionStatus, x as TransactionType, a0 as ValidatorClaimOptions, _ as ValidatorDepositOptions, $ as ValidatorExitOptions, F as ValidatorIdentity, I as ValidatorInfo, Z as ValidatorJoinOptions, X as ValidatorJoinResult, a1 as ValidatorPrimeOptions, B as ValidatorView, u as VoteType, W as WithdrawalCommit, s as executionResultNumberToName, p as isDecidedState, q as transactionResultNumberToName, n as transactionsStatusNameToNumber, t as transactionsStatusNumberToName, w as voteTypeNameToNumber, v as voteTypeNumberToName } from '../index-DEWwFm0_.js';
+export { O as BannedValidatorInfo, e as CalldataAddress, C as CalldataEncodable, j as ContractMethod, i as ContractMethodBase, g as ContractParamsArraySchemaElement, h as ContractParamsSchema, d as ContractSchema, o as DECIDED_STATES, z as DebugTraceResult, a as DecodedCallData, D as DecodedDeployData, a7 as DelegatorClaimOptions, a6 as DelegatorExitOptions, a5 as DelegatorJoinOptions, Z as DelegatorJoinResult, R as EpochData, U as EpochInfo, E as ExecutionResult, G as GenLayerClient, f as GenLayerMethod, b as GenLayerRawTransaction, c as GenLayerTransaction, H as Hash, L as LeaderReceipt, M as MethodDescription, N as Network, P as PendingDeposit, K as PendingWithdrawal, a4 as SetIdentityOptions, a3 as SetOperatorOptions, A as SnapSource, Q as StakeInfo, a8 as StakingActions, B as StakingContract, X as StakingTransactionResult, k as TransactionHash, y as TransactionHashVariant, m as TransactionResult, r as TransactionResultNameToNumber, l as TransactionStatus, x as TransactionType, a1 as ValidatorClaimOptions, $ as ValidatorDepositOptions, a0 as ValidatorExitOptions, I as ValidatorIdentity, J as ValidatorInfo, _ as ValidatorJoinOptions, Y as ValidatorJoinResult, a2 as ValidatorPrimeOptions, F as ValidatorView, u as VoteType, W as WithdrawalCommit, s as executionResultNumberToName, p as isDecidedState, q as transactionResultNumberToName, n as transactionsStatusNameToNumber, t as transactionsStatusNumberToName, w as voteTypeNameToNumber, v as voteTypeNumberToName } from '../index-Dc8L54mZ.js';
 export { G as GenLayerChain } from '../chains-DqSbucSW.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "genlayer-js",
   "type": "module",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "GenLayer JavaScript SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,8 @@
     "test:smoke": "vitest run --config vitest.smoke.config.ts",
     "test:watch": "vitest --watch",
     "lint": "eslint . --fix --ext .ts",
-    "release": "release-it --ci"
+    "release": "release-it --ci",
+    "docs": "typedoc"
   },
   "exports": {
     ".": {
@@ -55,6 +56,8 @@
     "release-it": "^17.6.0",
     "ts-node": "^10.9.2",
     "tsup": "^8.2.4",
+    "typedoc": "^0.28.18",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.6.2",
     "vitest": "^2.1.1"
   },