@autonomys/auto-consensus 1.5.2 → 1.5.4

package/dist/staking.d.ts

@@ -1,13 +1,318 @@
 import { Api } from '@autonomys/auto-utils';
 import type { NominateOperatorParams, RegisterOperatorParams, StakingParams, StringNumberOrBigInt, WithdrawStakeParams } from './types/staking';
+/**
+ * Retrieves all registered operators on the network.
+ *
+ * This function queries the blockchain to get information about all operators
+ * that have been registered across all domains. Operators are entities that
+ * process transactions and maintain domain chains.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to an array of Operator objects
+ * @throws Error if the operators query fails
+ *
+ * @example
+ * ```typescript
+ * import { operators } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const allOperators = await operators(api)
+ *
+ * allOperators.forEach(op => {
+ *   console.log(`Operator ${op.operatorId}: Domain ${op.operatorDetails.currentDomainId}`)
+ *   console.log(`Total Stake: ${op.operatorDetails.currentTotalStake}`)
+ * })
+ * ```
+ */
 export declare const operators: (api: Api) => Promise<import("./types/staking").Operator[]>;
+/**
+ * Retrieves detailed information about a specific operator.
+ *
+ * This function queries information about a single operator including their
+ * signing key, domain assignment, stake amounts, and operational status.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query
+ * @returns Promise that resolves to OperatorDetails object
+ * @throws Error if the operator query fails or operator doesn't exist
+ *
+ * @example
+ * ```typescript
+ * import { operator } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const operatorInfo = await operator(api, '1')
+ *
+ * console.log(`Domain: ${operatorInfo.currentDomainId}`)
+ * console.log(`Total Stake: ${operatorInfo.currentTotalStake}`)
+ * console.log(`Minimum Nominator Stake: ${operatorInfo.minimumNominatorStake}`)
+ * console.log(`Nomination Tax: ${operatorInfo.nominationTax}%`)
+ * ```
+ */
 export declare const operator: (api: Api, operatorId: StringNumberOrBigInt) => Promise<import("./types/staking").OperatorDetails>;
+/**
+ * Retrieves deposit information for an operator.
+ *
+ * This function queries all deposits (stakes) made to a specific operator.
+ * It can optionally filter deposits by a specific account address.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query deposits for
+ * @param account - Optional account address to filter deposits by
+ * @returns Promise that resolves to an array of Deposit objects
+ * @throws Error if the deposits query fails
+ *
+ * @example
+ * ```typescript
+ * import { deposits } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get all deposits for operator
+ * const allDeposits = await deposits(api, '1')
+ *
+ * // Get deposits for specific account
+ * const accountDeposits = await deposits(api, '1', 'account_address')
+ *
+ * allDeposits.forEach(deposit => {
+ *   console.log(`Account: ${deposit.account}, Shares: ${deposit.shares}`)
+ * })
+ * ```
+ */
 export declare const deposits: (api: Api, operatorId: StringNumberOrBigInt, account?: string | undefined) => Promise<import("./types/staking").Deposit[]>;
+/**
+ * Retrieves withdrawal information for an operator.
+ *
+ * This function queries all pending withdrawals for a specific operator.
+ * Withdrawals are stakes that have been requested to be unstaked but are
+ * still in the withdrawal period. Can optionally filter by account.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query withdrawals for
+ * @param account - Optional account address to filter withdrawals by
+ * @returns Promise that resolves to an array of Withdrawal objects
+ * @throws Error if the withdrawals query fails
+ *
+ * @example
+ * ```typescript
+ * import { withdrawals } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get all withdrawals for operator
+ * const allWithdrawals = await withdrawals(api, '1')
+ *
+ * // Get withdrawals for specific account
+ * const accountWithdrawals = await withdrawals(api, '1', 'account_address')
+ *
+ * allWithdrawals.forEach(withdrawal => {
+ *   console.log(`Account: ${withdrawal.account}`)
+ *   console.log(`Total Withdrawal: ${withdrawal.totalWithdrawalAmount}`)
+ * })
+ * ```
+ */
 export declare const withdrawals: (api: Api, operatorId: StringNumberOrBigInt, account?: string | undefined) => Promise<import("./types/staking").Withdrawal[]>;
+/**
+ * Creates a transaction to register a new operator.
+ *
+ * This function creates a transaction to register a new operator on a specific domain.
+ * The operator will be able to process transactions and earn rewards. Requires
+ * initial stake, minimum nominator stake, and nomination tax settings.
+ *
+ * @param params - RegisterOperatorParams containing all registration parameters
+ * @param params.api - The connected API promise instance
+ * @param params.domainId - The domain ID where the operator will be registered
+ * @param params.amountToStake - Initial amount to stake (in smallest token units)
+ * @param params.minimumNominatorStake - Minimum stake required from nominators
+ * @param params.nominationTax - Percentage fee charged to nominators
+ * @param params.signingKey - Optional signing key (derived from publicKey if not provided)
+ * @param params.publicKey - Optional public key (used to derive signingKey if needed)
+ * @returns A submittable operator registration transaction
+ * @throws Error if signing key/public key not provided or transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { registerOperator } from '@autonomys/auto-consensus'
+ * import { activate, activateWallet, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const { accounts } = await activateWallet({ networkId: 'gemini-3h', mnemonic })
+ *
+ * const registerTx = registerOperator({
+ *   api,
+ *   domainId: '0',
+ *   amountToStake: '100000000000000000000', // 100 AI3
+ *   minimumNominatorStake: '1000000000000000000', // 1 AI3
+ *   nominationTax: '10', // 10%
+ *   publicKey: accounts[0].publicKey
+ * })
+ *
+ * await signAndSendTx(accounts[0], registerTx)
+ * ```
+ */
 export declare const registerOperator: (params: RegisterOperatorParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
+/**
+ * Creates a transaction to nominate (stake to) an existing operator.
+ *
+ * This function creates a transaction to stake tokens to an existing operator.
+ * Nominators earn rewards proportional to their stake, minus the operator's
+ * nomination tax. The stake helps secure the network and the specific domain.
+ *
+ * @param params - NominateOperatorParams containing nomination parameters
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to nominate
+ * @param params.amountToStake - Amount to stake (in smallest token units)
+ * @returns A submittable operator nomination transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { nominateOperator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const nominateTx = nominateOperator({
+ *   api,
+ *   operatorId: '1',
+ *   amountToStake: '50000000000000000000' // 50 AI3
+ * })
+ *
+ * await signAndSendTx(nominator, nominateTx)
+ * ```
+ */
 export declare const nominateOperator: (params: NominateOperatorParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
+/**
+ * Creates a transaction to withdraw stake from an operator.
+ *
+ * This function creates a transaction to withdraw staked tokens from an operator.
+ * Supports different withdrawal modes: all stake, by percentage, by specific amount,
+ * or by number of shares. Withdrawn stake enters a withdrawal period before being available.
+ *
+ * @param params - WithdrawStakeParams containing withdrawal parameters
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to withdraw stake from
+ * @param params.all - Optional: withdraw all stake (boolean)
+ * @param params.percent - Optional: withdraw by percentage (string/number)
+ * @param params.stake - Optional: withdraw specific stake amount
+ * @param params.shares - Optional: withdraw specific number of shares
+ * @returns A submittable stake withdrawal transaction
+ * @throws Error if no withdrawal method specified or transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { withdrawStake } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Withdraw all stake
+ * const withdrawAllTx = withdrawStake({ api, operatorId: '1', all: true })
+ *
+ * // Withdraw 50% of stake
+ * const withdrawPercentTx = withdrawStake({ api, operatorId: '1', percent: '50' })
+ *
+ * // Withdraw specific amount
+ * const withdrawAmountTx = withdrawStake({
+ *   api,
+ *   operatorId: '1',
+ *   stake: '25000000000000000000'
+ * })
+ *
+ * await signAndSendTx(staker, withdrawAllTx)
+ * ```
+ */
 export declare const withdrawStake: (params: WithdrawStakeParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
+/**
+ * Creates a transaction to deregister an operator.
+ *
+ * This function creates a transaction to deregister an operator, removing them
+ * from active service. The operator will no longer process transactions or earn
+ * rewards. All stakes will enter the withdrawal period.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to deregister
+ * @returns A submittable operator deregistration transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { deregisterOperator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const deregisterTx = deregisterOperator({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(operatorOwner, deregisterTx)
+ * ```
+ */
 export declare const deregisterOperator: (params: StakingParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
+/**
+ * Creates a transaction to unlock funds from an operator.
+ *
+ * This function creates a transaction to unlock funds that have completed
+ * their withdrawal period. These are funds that were previously withdrawn
+ * and have now passed the required waiting period.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to unlock funds from
+ * @returns A submittable unlock funds transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { unlockFunds } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const unlockTx = unlockFunds({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(account, unlockTx)
+ * ```
+ */
 export declare const unlockFunds: (params: StakingParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
+/**
+ * Creates a transaction to unlock a nominator from an operator.
+ *
+ * This function creates a transaction to unlock a nominator's position,
+ * allowing them to withdraw their stake after the withdrawal period.
+ * This is typically used when a nominator wants to completely exit their
+ * position with an operator.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to unlock nominator from
+ * @returns A submittable unlock nominator transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { unlockNominator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const unlockNominatorTx = unlockNominator({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(nominator, unlockNominatorTx)
+ * ```
+ */
 export declare const unlockNominator: (params: StakingParams) => import("@autonomys/auto-utils").SubmittableExtrinsic<"promise", import("@autonomys/auto-utils").ISubmittableResult>;
 //# sourceMappingURL=staking.d.ts.map

package/dist/staking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staking.d.ts","sourceRoot":"","sources":["../src/staking.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,GAAG,EAOJ,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AASxB,eAAO,MAAM,SAAS,GAAU,KAAK,GAAG,kDAQvC,CAAA;AAED,eAAO,MAAM,QAAQ,GAAU,KAAK,GAAG,EAAE,YAAY,oBAAoB,uDAQxE,CAAA;AAED,eAAO,MAAM,QAAQ,GACnB,KAAK,GAAG,EACR,YAAY,oBAAoB,EAChC,UAAS,MAAM,GAAG,SAAqB,iDAgBxC,CAAA;AAED,eAAO,MAAM,WAAW,GACtB,KAAK,GAAG,EACR,YAAY,oBAAoB,EAChC,UAAS,MAAM,GAAG,SAAqB,oDAkBxC,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,wHAmB9D,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,wHAS9D,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,QAAQ,mBAAmB,wHAmBxD,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,QAAQ,aAAa,wHASvD,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,wHAShD,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,QAAQ,aAAa,wHASpD,CAAA"}
+{"version":3,"file":"staking.d.ts","sourceRoot":"","sources":["../src/staking.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,GAAG,EAOJ,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,iBAAiB,CAAA;AASxB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,GAAU,KAAK,GAAG,kDAQvC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,QAAQ,GAAU,KAAK,GAAG,EAAE,YAAY,oBAAoB,uDAQxE,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ,GACnB,KAAK,GAAG,EACR,YAAY,oBAAoB,EAChC,UAAS,MAAM,GAAG,SAAqB,iDAgBxC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,WAAW,GACtB,KAAK,GAAG,EACR,YAAY,oBAAoB,EAChC,UAAS,MAAM,GAAG,SAAqB,oDAkBxC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,wHAmB9D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,wHAS9D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,mBAAmB,wHAmBxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,aAAa,wHASvD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,aAAa,wHAShD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,aAAa,wHASpD,CAAA"}

package/dist/staking.js

@@ -13,6 +13,31 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.unlockNominator = exports.unlockFunds = exports.deregisterOperator = exports.withdrawStake = exports.nominateOperator = exports.registerOperator = exports.withdrawals = exports.deposits = exports.operator = exports.operators = void 0;
 const auto_utils_1 = require("@autonomys/auto-utils");
 const parse_1 = require("./utils/parse");
+/**
+ * Retrieves all registered operators on the network.
+ *
+ * This function queries the blockchain to get information about all operators
+ * that have been registered across all domains. Operators are entities that
+ * process transactions and maintain domain chains.
+ *
+ * @param api - The connected API instance
+ * @returns Promise that resolves to an array of Operator objects
+ * @throws Error if the operators query fails
+ *
+ * @example
+ * ```typescript
+ * import { operators } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const allOperators = await operators(api)
+ *
+ * allOperators.forEach(op => {
+ *   console.log(`Operator ${op.operatorId}: Domain ${op.operatorDetails.currentDomainId}`)
+ *   console.log(`Total Stake: ${op.operatorDetails.currentTotalStake}`)
+ * })
+ * ```
+ */
 const operators = (api) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const _operators = yield api.query.domains.operators.entries();
@@ -24,6 +49,31 @@ const operators = (api) => __awaiter(void 0, void 0, void 0, function* () {
     }
 });
 exports.operators = operators;
+/**
+ * Retrieves detailed information about a specific operator.
+ *
+ * This function queries information about a single operator including their
+ * signing key, domain assignment, stake amounts, and operational status.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query
+ * @returns Promise that resolves to OperatorDetails object
+ * @throws Error if the operator query fails or operator doesn't exist
+ *
+ * @example
+ * ```typescript
+ * import { operator } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const operatorInfo = await operator(api, '1')
+ *
+ * console.log(`Domain: ${operatorInfo.currentDomainId}`)
+ * console.log(`Total Stake: ${operatorInfo.currentTotalStake}`)
+ * console.log(`Minimum Nominator Stake: ${operatorInfo.minimumNominatorStake}`)
+ * console.log(`Nomination Tax: ${operatorInfo.nominationTax}%`)
+ * ```
+ */
 const operator = (api, operatorId) => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const _operator = yield api.query.domains.operators((0, parse_1.parseString)(operatorId));
@@ -35,6 +85,36 @@ const operator = (api, operatorId) => __awaiter(void 0, void 0, void 0, function
     }
 });
 exports.operator = operator;
+/**
+ * Retrieves deposit information for an operator.
+ *
+ * This function queries all deposits (stakes) made to a specific operator.
+ * It can optionally filter deposits by a specific account address.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query deposits for
+ * @param account - Optional account address to filter deposits by
+ * @returns Promise that resolves to an array of Deposit objects
+ * @throws Error if the deposits query fails
+ *
+ * @example
+ * ```typescript
+ * import { deposits } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get all deposits for operator
+ * const allDeposits = await deposits(api, '1')
+ *
+ * // Get deposits for specific account
+ * const accountDeposits = await deposits(api, '1', 'account_address')
+ *
+ * allDeposits.forEach(deposit => {
+ *   console.log(`Account: ${deposit.account}, Shares: ${deposit.shares}`)
+ * })
+ * ```
+ */
 const deposits = (api_1, operatorId_1, ...args_1) => __awaiter(void 0, [api_1, operatorId_1, ...args_1], void 0, function* (api, operatorId, account = undefined) {
     try {
         if (account) {
@@ -54,6 +134,38 @@ const deposits = (api_1, operatorId_1, ...args_1) => __awaiter(void 0, [api_1, o
     }
 });
 exports.deposits = deposits;
+/**
+ * Retrieves withdrawal information for an operator.
+ *
+ * This function queries all pending withdrawals for a specific operator.
+ * Withdrawals are stakes that have been requested to be unstaked but are
+ * still in the withdrawal period. Can optionally filter by account.
+ *
+ * @param api - The connected API instance
+ * @param operatorId - The ID of the operator to query withdrawals for
+ * @param account - Optional account address to filter withdrawals by
+ * @returns Promise that resolves to an array of Withdrawal objects
+ * @throws Error if the withdrawals query fails
+ *
+ * @example
+ * ```typescript
+ * import { withdrawals } from '@autonomys/auto-consensus'
+ * import { activate } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Get all withdrawals for operator
+ * const allWithdrawals = await withdrawals(api, '1')
+ *
+ * // Get withdrawals for specific account
+ * const accountWithdrawals = await withdrawals(api, '1', 'account_address')
+ *
+ * allWithdrawals.forEach(withdrawal => {
+ *   console.log(`Account: ${withdrawal.account}`)
+ *   console.log(`Total Withdrawal: ${withdrawal.totalWithdrawalAmount}`)
+ * })
+ * ```
+ */
 const withdrawals = (api_1, operatorId_1, ...args_1) => __awaiter(void 0, [api_1, operatorId_1, ...args_1], void 0, function* (api, operatorId, account = undefined) {
     try {
         if (account) {
@@ -75,6 +187,44 @@ const withdrawals = (api_1, operatorId_1, ...args_1) => __awaiter(void 0, [api_1
     }
 });
 exports.withdrawals = withdrawals;
+/**
+ * Creates a transaction to register a new operator.
+ *
+ * This function creates a transaction to register a new operator on a specific domain.
+ * The operator will be able to process transactions and earn rewards. Requires
+ * initial stake, minimum nominator stake, and nomination tax settings.
+ *
+ * @param params - RegisterOperatorParams containing all registration parameters
+ * @param params.api - The connected API promise instance
+ * @param params.domainId - The domain ID where the operator will be registered
+ * @param params.amountToStake - Initial amount to stake (in smallest token units)
+ * @param params.minimumNominatorStake - Minimum stake required from nominators
+ * @param params.nominationTax - Percentage fee charged to nominators
+ * @param params.signingKey - Optional signing key (derived from publicKey if not provided)
+ * @param params.publicKey - Optional public key (used to derive signingKey if needed)
+ * @returns A submittable operator registration transaction
+ * @throws Error if signing key/public key not provided or transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { registerOperator } from '@autonomys/auto-consensus'
+ * import { activate, activateWallet, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ * const { accounts } = await activateWallet({ networkId: 'gemini-3h', mnemonic })
+ *
+ * const registerTx = registerOperator({
+ *   api,
+ *   domainId: '0',
+ *   amountToStake: '100000000000000000000', // 100 AI3
+ *   minimumNominatorStake: '1000000000000000000', // 1 AI3
+ *   nominationTax: '10', // 10%
+ *   publicKey: accounts[0].publicKey
+ * })
+ *
+ * await signAndSendTx(accounts[0], registerTx)
+ * ```
+ */
 const registerOperator = (params) => {
     try {
         const { api, domainId, amountToStake, minimumNominatorStake, nominationTax, publicKey } = params;
@@ -97,6 +247,36 @@ const registerOperator = (params) => {
     }
 };
 exports.registerOperator = registerOperator;
+/**
+ * Creates a transaction to nominate (stake to) an existing operator.
+ *
+ * This function creates a transaction to stake tokens to an existing operator.
+ * Nominators earn rewards proportional to their stake, minus the operator's
+ * nomination tax. The stake helps secure the network and the specific domain.
+ *
+ * @param params - NominateOperatorParams containing nomination parameters
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to nominate
+ * @param params.amountToStake - Amount to stake (in smallest token units)
+ * @returns A submittable operator nomination transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { nominateOperator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const nominateTx = nominateOperator({
+ *   api,
+ *   operatorId: '1',
+ *   amountToStake: '50000000000000000000' // 50 AI3
+ * })
+ *
+ * await signAndSendTx(nominator, nominateTx)
+ * ```
+ */
 const nominateOperator = (params) => {
     try {
         const { api, operatorId, amountToStake } = params;
@@ -108,6 +288,46 @@ const nominateOperator = (params) => {
     }
 };
 exports.nominateOperator = nominateOperator;
+/**
+ * Creates a transaction to withdraw stake from an operator.
+ *
+ * This function creates a transaction to withdraw staked tokens from an operator.
+ * Supports different withdrawal modes: all stake, by percentage, by specific amount,
+ * or by number of shares. Withdrawn stake enters a withdrawal period before being available.
+ *
+ * @param params - WithdrawStakeParams containing withdrawal parameters
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to withdraw stake from
+ * @param params.all - Optional: withdraw all stake (boolean)
+ * @param params.percent - Optional: withdraw by percentage (string/number)
+ * @param params.stake - Optional: withdraw specific stake amount
+ * @param params.shares - Optional: withdraw specific number of shares
+ * @returns A submittable stake withdrawal transaction
+ * @throws Error if no withdrawal method specified or transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { withdrawStake } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * // Withdraw all stake
+ * const withdrawAllTx = withdrawStake({ api, operatorId: '1', all: true })
+ *
+ * // Withdraw 50% of stake
+ * const withdrawPercentTx = withdrawStake({ api, operatorId: '1', percent: '50' })
+ *
+ * // Withdraw specific amount
+ * const withdrawAmountTx = withdrawStake({
+ *   api,
+ *   operatorId: '1',
+ *   stake: '25000000000000000000'
+ * })
+ *
+ * await signAndSendTx(staker, withdrawAllTx)
+ * ```
+ */
 const withdrawStake = (params) => {
     try {
         const { api, operatorId } = params;
@@ -130,6 +350,34 @@ const withdrawStake = (params) => {
     }
 };
 exports.withdrawStake = withdrawStake;
+/**
+ * Creates a transaction to deregister an operator.
+ *
+ * This function creates a transaction to deregister an operator, removing them
+ * from active service. The operator will no longer process transactions or earn
+ * rewards. All stakes will enter the withdrawal period.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to deregister
+ * @returns A submittable operator deregistration transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { deregisterOperator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const deregisterTx = deregisterOperator({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(operatorOwner, deregisterTx)
+ * ```
+ */
 const deregisterOperator = (params) => {
     try {
         const { api, operatorId } = params;
@@ -141,6 +389,34 @@ const deregisterOperator = (params) => {
     }
 };
 exports.deregisterOperator = deregisterOperator;
+/**
+ * Creates a transaction to unlock funds from an operator.
+ *
+ * This function creates a transaction to unlock funds that have completed
+ * their withdrawal period. These are funds that were previously withdrawn
+ * and have now passed the required waiting period.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to unlock funds from
+ * @returns A submittable unlock funds transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { unlockFunds } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const unlockTx = unlockFunds({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(account, unlockTx)
+ * ```
+ */
 const unlockFunds = (params) => {
     try {
         const { api, operatorId } = params;
@@ -152,6 +428,35 @@ const unlockFunds = (params) => {
     }
 };
 exports.unlockFunds = unlockFunds;
+/**
+ * Creates a transaction to unlock a nominator from an operator.
+ *
+ * This function creates a transaction to unlock a nominator's position,
+ * allowing them to withdraw their stake after the withdrawal period.
+ * This is typically used when a nominator wants to completely exit their
+ * position with an operator.
+ *
+ * @param params - StakingParams containing the operator information
+ * @param params.api - The connected API promise instance
+ * @param params.operatorId - The ID of the operator to unlock nominator from
+ * @returns A submittable unlock nominator transaction
+ * @throws Error if transaction creation fails
+ *
+ * @example
+ * ```typescript
+ * import { unlockNominator } from '@autonomys/auto-consensus'
+ * import { activate, signAndSendTx } from '@autonomys/auto-utils'
+ *
+ * const api = await activate({ networkId: 'gemini-3h' })
+ *
+ * const unlockNominatorTx = unlockNominator({
+ *   api,
+ *   operatorId: '1'
+ * })
+ *
+ * await signAndSendTx(nominator, unlockNominatorTx)
+ * ```
+ */
 const unlockNominator = (params) => {
     try {
         const { api, operatorId } = params;