@ocap/client 1.25.3 → 1.25.5

package/docs/api-reference-transaction-helpers.md

@@ -0,0 +1,649 @@
+# High-level API
+
+Transaction helpers are high-level functions built into the OCAP Client that abstract away the complexity of creating and signing common transactions. Instead of manually constructing transaction objects, you can use these convenient methods for workflows like creating assets, transferring tokens, staking, and performing atomic swaps. These helpers ensure that the transaction structure is correct and simplify the development process significantly.
+
+For a deeper understanding of the underlying transaction lifecycle, see [Core Concepts: Transaction Lifecycle](./core-concepts-transaction-lifecycle.md).
+
+---
+
+## Account Management
+
+### migrateAccount
+
+Migrates the ownership of an account to a new key pair. This is useful for key rotation or account recovery.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="The wallet object of the account to migrate from."></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="The wallet object of the account to migrate to."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send an AccountMigrateTx icon=logos:javascript
+const txHash = await client.migrateAccount({
+  from: oldWallet,
+  to: newWallet,
+});
+console.log('Migration transaction hash:', txHash);
+```
+
+### delegate
+
+Authorizes another account (the delegatee) to send specific types of transactions on behalf of the delegator. This is a powerful feature for creating secure, sandboxed permissions.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="The delegator's wallet, who is granting the privilege."></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="The delegatee's wallet, who is receiving the privilege."></x-field>
+  <x-field data-name="privileges" data-type="array" data-required="true" data-desc="An array of privilege objects specifying the allowed actions.">
+    <x-field data-name="typeUrl" data-type="string" data-required="true" data-desc="The type URL of the transaction being permitted (e.g., 'fg:t:transfer_v2')."></x-field>
+    <x-field data-name="limit" data-type="object" data-required="false" data-desc="Optional limits on the delegation.">
+      <x-field data-name="tokens" data-type="array" data-desc="Limits on specific fungible tokens."></x-field>
+      <x-field data-name="assets" data-type="array" data-desc="Limits on specific assets (NFTs)."></x-field>
+    </x-field>
+  </x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="An array containing the transaction hash and the newly created delegate address."></x-field>
+
+**Example**
+
+```javascript Send a DelegateTx icon=logos:javascript
+const [txHash, delegateAddress] = await client.delegate({
+  from: userWallet,
+  to: appWallet,
+  privileges: [
+    {
+      typeUrl: 'fg:t:transfer_v2',
+    },
+  ],
+});
+console.log('Delegation tx hash:', txHash);
+console.log('Delegate address:', delegateAddress);
+```
+
+### revokeDelegate
+
+Revokes previously granted permissions from a delegatee.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="WalletObject" data-required="true" data-desc="The delegator's wallet."></x-field>
+  <x-field data-name="to" data-type="WalletObject" data-required="true" data-desc="The delegatee's wallet."></x-field>
+  <x-field data-name="privileges" data-type="array" data-required="true" data-desc="An array of privilege objects specifying the permissions to revoke.">
+     <x-field data-name="typeUrl" data-type="string" data-required="true" data-desc="The type URL of the transaction to revoke (e.g., 'fg:t:transfer_v2')."></x-field>
+  </x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a RevokeDelegateTx icon=logos:javascript
+const txHash = await client.revokeDelegate({
+  from: userWallet,
+  to: appWallet,
+  privileges: ['fg:t:transfer_v2'],
+});
+console.log('Revocation tx hash:', txHash);
+```
+
+---
+
+## Asset (NFT) Management
+
+### createAsset
+
+Creates a new asset (Non-Fungible Token) on the blockchain.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="moniker" data-type="string" data-required="true" data-desc="A short, human-readable name for the asset."></x-field>
+  <x-field data-name="data" data-type="object" data-required="true" data-desc="A JSON object containing the asset's metadata."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the asset's initial owner."></x-field>
+  <x-field data-name="parent" data-type="string" data-required="false" data-desc="The address of a parent asset, establishing a hierarchical link."></x-field>
+  <x-field data-name="ttl" data-type="number" data-required="false" data-default="0" data-desc="Time-to-live in seconds after the first consumption."></x-field>
+  <x-field data-name="readonly" data-type="boolean" data-required="false" data-default="false" data-desc="If true, the asset cannot be updated after creation."></x-field>
+  <x-field data-name="transferrable" data-type="boolean" data-required="false" data-default="true" data-desc="If true, the asset can be transferred to another account."></x-field>
+  <x-field data-name="display" data-type="object" data-required="false" data-desc="Object for asset display metadata."></x-field>
+  <x-field data-name="endpoint" data-type="object" data-required="false" data-desc="Object for asset endpoint metadata."></x-field>
+  <x-field data-name="tags" data-type="string[]" data-required="false" data-desc="An array of tags for categorization."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the delegator, if the transaction is sent by a delegatee."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="An array containing the transaction hash and the address of the newly created asset."></x-field>
+
+**Example**
+
+```javascript Send a CreateAssetTx icon=logos:javascript
+const [txHash, assetAddress] = await client.createAsset({
+  moniker: 'My First NFT',
+  data: {
+    typeUrl: 'json',
+    value: { name: 'Digital Collectible', description: 'A unique item.' },
+  },
+  wallet: userWallet,
+});
+console.log('Create asset tx hash:', txHash);
+console.log('New asset address:', assetAddress);
+```
+
+### updateAsset
+
+Updates the `moniker` and `data` fields of an existing, non-readonly asset.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the asset to update."></x-field>
+  <x-field data-name="moniker" data-type="string" data-required="true" data-desc="The new moniker for the asset."></x-field>
+  <x-field data-name="data" data-type="object" data-required="true" data-desc="The new JSON data object for the asset."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the asset's current owner."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send an UpdateAssetTx icon=logos:javascript
+const txHash = await client.updateAsset({
+  address: 'z3g...',
+  moniker: 'Updated NFT Name',
+  data: {
+    typeUrl: 'json',
+    value: { name: 'Updated Collectible', description: 'Now with more features!' },
+  },
+  wallet: userWallet,
+});
+console.log('Update asset tx hash:', txHash);
+```
+
+### createAssetFactory
+
+Creates an asset factory, which acts as a template for minting multiple new assets with a consistent structure.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="factory" data-type="object" data-required="true" data-desc="An object containing the factory's configuration.">
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="Name of the factory."></x-field>
+    <x-field data-name="description" data-type="string" data-required="true" data-desc="Description of the factory."></x-field>
+    <x-field data-name="limit" data-type="number" data-required="false" data-default="0" data-desc="The maximum number of assets that can be minted (0 for unlimited)."></x-field>
+    <x-field data-name="trustedIssuers" data-type="string[]" data-required="false" data-desc="A list of wallet addresses allowed to mint from this factory."></x-field>
+    <x-field data-name="input" data-type="object" data-required="true" data-desc="Defines the inputs required for minting."></x-field>
+    <x-field data-name="output" data-type="object" data-required="true" data-desc="Defines the structure of the minted asset, often using templates."></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet to own the factory."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="An array containing the transaction hash and the address of the newly created factory."></x-field>
+
+**Example**
+
+```javascript Send a CreateFactoryTx icon=logos:javascript
+const factoryConfig = {
+  name: 'Ticket Factory',
+  description: 'Mints event tickets',
+  limit: 1000,
+  input: { ... },
+  output: { ... },
+};
+
+const [txHash, factoryAddress] = await client.createAssetFactory({
+  factory: factoryConfig,
+  wallet: eventCreatorWallet,
+});
+console.log('Create factory tx hash:', txHash);
+console.log('New factory address:', factoryAddress);
+```
+
+### acquireAsset
+
+Acquires (mints) a new asset from an existing asset factory. This is typically initiated by the end-user who will own the asset.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="itx" data-type="AcquireAssetV2Tx" data-required="true" data-desc="The inner transaction object, often prepared using a helper like `preMintAsset`."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the user acquiring the asset."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The address of the delegator, if applicable."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send an AcquireAssetV2Tx icon=logos:javascript
+// First, prepare the minting transaction (e.g., on the server)
+const itx = await client.preMintAsset({
+  factory: factoryAddress,
+  owner: userWallet.address,
+  wallet: issuerWallet,
+});
+
+// Then, the user sends the transaction
+const txHash = await client.acquireAsset({ itx, wallet: userWallet });
+console.log('Acquire asset tx hash:', txHash);
+```
+
+### mintAsset
+
+This is the issuer-side counterpart to `acquireAsset`. It allows a trusted issuer to mint an asset from a factory and assign it to a specified owner.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="itx" data-type="MintAssetTx" data-required="true" data-desc="The inner transaction object, often prepared using `preMintAsset`."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the trusted issuer."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a MintAssetTx icon=logos:javascript
+const itx = await client.preMintAsset({
+  factory: factoryAddress,
+  owner: userWallet.address,
+  wallet: issuerWallet,
+});
+
+const txHash = await client.mintAsset({ itx, wallet: issuerWallet });
+console.log('Mint asset tx hash:', txHash);
+```
+
+---
+
+## Token Management
+
+### createTokenFactory
+
+Creates a new factory for minting and burning a specific fungible token, often based on a bonding curve pricing model.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="feeRate" data-type="number" data-required="false" data-default="0" data-desc="The fee rate for minting and burning operations."></x-field>
+  <x-field data-name="curve" data-type="object" data-required="true" data-desc="The bonding curve configuration for pricing."></x-field>
+  <x-field data-name="token" data-type="object" data-required="true">
+    <x-field-desc markdown>The configuration for the token to be created. This includes properties like `name`, `symbol`, `decimal`, and `maxTotalSupply`.</x-field-desc>
+  </x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional metadata for the token factory."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the factory's owner."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="An array containing the transaction hash and the address of the newly created token factory."></x-field>
+
+**Example**
+
+```javascript Send a CreateTokenFactoryTx icon=logos:javascript
+const [txHash, factoryAddress] = await client.createTokenFactory({
+  feeRate: 100, // 1%
+  curve: { fixedPrice: '1' }, // 1 native token per new token
+  token: {
+    name: 'My Community Token',
+    symbol: 'MCT',
+    decimal: 18,
+    maxTotalSupply: '1000000',
+  },
+  wallet: creatorWallet,
+});
+console.log('Create token factory tx hash:', txHash);
+console.log('New token factory address:', factoryAddress);
+```
+
+### updateTokenFactory
+
+Updates the `feeRate` and `data` for an existing token factory.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the token factory to update."></x-field>
+  <x-field data-name="feeRate" data-type="number" data-required="false" data-desc="The new fee rate for minting and burning."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="New metadata for the token factory."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the factory's owner."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send an UpdateTokenFactoryTx icon=logos:javascript
+const txHash = await client.updateTokenFactory({
+  address: 'z2f...',
+  feeRate: 50, // 0.5%
+  wallet: ownerWallet,
+});
+console.log('Update token factory tx hash:', txHash);
+```
+
+### mintToken
+
+Mints new tokens from a token factory in exchange for the reserve token (usually the native chain token). The cost is determined by the factory's bonding curve.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="The address of the token factory."></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="The amount of new tokens to mint."></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="The address that will receive the newly minted tokens."></x-field>
+  <x-field data-name="maxReserve" data-type="number" data-required="true" data-desc="The maximum amount of reserve tokens the user is willing to pay. This acts as slippage protection."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional metadata for the transaction."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet initiating the mint."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a MintTokenTx icon=logos:javascript
+const txHash = await client.mintToken({
+  tokenFactory: 'z2f...',
+  amount: 100,
+  receiver: userWallet.address,
+  maxReserve: 105, // Willing to pay up to 105 native tokens
+  wallet: userWallet,
+});
+console.log('Mint token tx hash:', txHash);
+```
+
+### burnToken
+
+Burns existing tokens at a factory to receive the underlying reserve token in return. The amount of reserve token received is determined by the factory's bonding curve.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="The address of the token factory."></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="The amount of tokens to burn."></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="The address that will receive the reserve tokens."></x-field>
+  <x-field data-name="minReserve" data-type="number" data-required="true" data-desc="The minimum amount of reserve tokens the user expects to receive. This acts as slippage protection."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional metadata for the transaction."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet initiating the burn."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a BurnTokenTx icon=logos:javascript
+const txHash = await client.burnToken({
+  tokenFactory: 'z2f...',
+  amount: 50,
+  receiver: userWallet.address,
+  minReserve: 48, // Expecting to receive at least 48 native tokens
+  wallet: userWallet,
+});
+console.log('Burn token tx hash:', txHash);
+```
+
+---
+
+## Transfer & Exchange
+
+### transfer
+
+Transfers native tokens, custom fungible tokens, and/or assets (NFTs) to another account in a single transaction.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="to" data-type="string" data-required="true" data-desc="The address of the recipient."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The sender's wallet."></x-field>
+  <x-field data-name="token" data-type="number" data-required="false" data-default="0" data-desc="The amount of the chain's native token to transfer."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses (NFTs) to transfer."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of custom fungible token objects to transfer.">
+    <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the custom token contract."></x-field>
+    <x-field data-name="value" data-type="number" data-required="true" data-desc="The amount of the custom token to transfer."></x-field>
+  </x-field>
+  <x-field data-name="memo" data-type="string" data-required="false" data-desc="An optional note for the transaction."></x-field>
+  <x-field data-name="delegator" data-type="string" data-required="false" data-desc="The delegator's address, if applicable."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a TransferV2Tx icon=logos:javascript
+const txHash = await client.transfer({
+  to: 'z1sb...',
+  token: 1.5, // 1.5 of the native chain token
+  assets: ['z3g...'], // An NFT
+  tokens: [{ address: 'z2t...', value: 100 }], // 100 of a custom token
+  memo: 'Payment for services',
+  wallet: senderWallet,
+});
+console.log('Transfer tx hash:', txHash);
+```
+
+### prepareExchange
+
+Prepares the sender's half of an atomic swap (exchange) transaction. It signs the sender's offer and returns a transaction object that can be passed to the receiver.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="The address of the other party in the exchange."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the user making the offer."></x-field>
+  <x-field data-name="offerToken" data-type="number" data-required="false" data-desc="Amount of native token offered."></x-field>
+  <x-field data-name="offerAssets" data-type="string[]" data-required="false" data-desc="Array of asset addresses offered."></x-field>
+  <x-field data-name="offerTokens" data-type="object[]" data-required="false" data-desc="Array of custom fungible tokens offered."></x-field>
+  <x-field data-name="demandToken" data-type="number" data-required="false" data-desc="Amount of native token demanded in return."></x-field>
+  <x-field data-name="demandAssets" data-type="string[]" data-required="false" data-desc="Array of asset addresses demanded in return."></x-field>
+  <x-field data-name="demandTokens" data-type="object[]" data-required="false" data-desc="Array of custom fungible tokens demanded."></x-field>
+  <x-field data-name="memo" data-type="string" data-required="false" data-desc="An optional note for the transaction."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionObject" data-type="Promise<object>" data-desc="The partially signed transaction object."></x-field>
+
+### finalizeExchange
+
+Finalizes the receiver's half of an atomic swap. It takes the partially signed transaction from `prepareExchange`, adds the receiver's signature, and returns the fully signed transaction object.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="The transaction object returned from `prepareExchange`."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the user accepting the offer."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Extra data in the multi-signature."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionObject" data-type="Promise<object>" data-desc="The fully signed, multi-signature transaction object."></x-field>
+
+### exchange
+
+Sends the fully signed exchange transaction to the blockchain. This can be called by either party after `finalizeExchange` is complete.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="tx" data-type="object" data-required="true" data-desc="The transaction object returned from `finalizeExchange`."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the user submitting the transaction."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example (Full Exchange Flow)**
+
+```javascript Perform an atomic swap icon=logos:javascript
+// 1. Offerer prepares the transaction
+const offerTx = await client.prepareExchange({
+  receiver: receiverWallet.address,
+  offerAssets: ['z3g...'], // Offer an NFT
+  demandToken: 10, // Demand 10 native tokens
+  wallet: offererWallet,
+});
+
+// 2. Receiver finalizes the transaction
+const finalTx = await client.finalizeExchange({
+  tx: offerTx,
+  wallet: receiverWallet,
+});
+
+// 3. Either party can send the finalized transaction
+const txHash = await client.exchange({ tx: finalTx, wallet: offererWallet });
+console.log('Exchange tx hash:', txHash);
+```
+
+---
+
+## Staking
+
+### stake
+
+Stakes tokens and/or assets to a receiver address. Staking locks up resources, often in exchange for rewards or to provide security.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="to" data-type="string" data-required="true" data-desc="The address of the stake receiver."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the staker."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses to stake."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of fungible token objects to stake."></x-field>
+  <x-field data-name="locked" data-type="boolean" data-required="false" data-default="false" data-desc="Whether the stake is locked upon creation."></x-field>
+  <x-field data-name="slashers" data-type="string[]" data-required="false" data-desc="A list of addresses that are permitted to slash this stake."></x-field>
+  <x-field data-name="message" data-type="string" data-required="false" data-desc="An optional note for the stake."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="result" data-type="Promise<[string, string]>" data-desc="An array containing the transaction hash and the address of the newly created stake."></x-field>
+
+**Example**
+
+```javascript Send a StakeTx icon=logos:javascript
+const [txHash, stakeAddress] = await client.stake({
+  to: 'z1v...',
+  tokens: [{ address: 'z2t...', value: 5000 }],
+  message: 'Staking for validator rewards',
+  wallet: userWallet,
+});
+console.log('Stake tx hash:', txHash);
+console.log('New stake address:', stakeAddress);
+```
+
+### revokeStake
+
+Revokes previously staked tokens and/or assets, initiating the process to return them to the owner. Note that there may be an unbonding period before the assets can be claimed.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake to revoke from."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the stake owner."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses to revoke."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of fungible token objects to revoke."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a RevokeStakeTx icon=logos:javascript
+const txHash = await client.revokeStake({
+  from: 'z6s...',
+  tokens: [{ address: 'z2t...', value: 1000 }],
+  wallet: userWallet,
+});
+console.log('Revoke stake tx hash:', txHash);
+```
+
+### claimStake
+
+Claims items from a stake that have been successfully revoked and have passed their unbonding period.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake to claim from."></x-field>
+  <x-field data-name="evidence" data-type="string" data-required="true" data-desc="The transaction hash of the `revokeStake` transaction."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the stake owner."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a ClaimStakeTx icon=logos:javascript
+const revokeTxHash = '0x123...abc';
+const txHash = await client.claimStake({
+  from: 'z6s...',
+  evidence: revokeTxHash,
+  wallet: userWallet,
+});
+console.log('Claim stake tx hash:', txHash);
+```
+
+### slashStake
+
+Allows a designated slasher to penalize a stake, typically for misbehavior. The slashed assets are transferred to a designated vault address.
+
+**Parameters**
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake to slash."></x-field>
+  <x-field data-name="reason" data-type="string" data-required="true" data-desc="A message explaining the reason for slashing."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet of the designated slasher."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses to slash."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of fungible token objects to slash."></x-field>
+</x-field-group>
+
+**Returns**
+
+<x-field data-name="transactionHash" data-type="Promise<string>" data-desc="The hash of the submitted transaction."></x-field>
+
+**Example**
+
+```javascript Send a SlashStakeTx icon=logos:javascript
+const txHash = await client.slashStake({
+  from: 'z6s...',
+  reason: 'Validator downtime',
+  tokens: [{ address: 'z2t...', value: 500 }],
+  wallet: slasherWallet,
+});
+console.log('Slash stake tx hash:', txHash);
+```