@ocap/client 1.25.2 → 1.25.4

package/docs/how-to-guides-manage-tokens.md

@@ -0,0 +1,179 @@
+# Manage Tokens
+
+This guide provides step-by-step instructions for managing fungible tokens using the OCAP Client. You will learn how to set up a token factory, which acts as a blueprint for your token, and then use it to mint (create new tokens) and burn (destroy existing tokens). These operations are fundamental to creating and managing custom economies within your application.
+
+Once you have minted tokens, you can transfer them between accounts. For more details on that process, please see the [Transfer Tokens and NFTs](./how-to-guides-transfer-tokens-and-nfts.md) guide.
+
+## Create a Token Factory
+
+A token factory is a smart contract that defines the properties and rules of a fungible token, such as its name, symbol, and supply mechanics. It also governs the process of minting and burning. Creating a factory is the first step before any new tokens can be brought into circulation.
+
+The `createTokenFactory` method deploys a new token factory to the blockchain.
+
+### Parameters
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet object of the factory owner, used to sign the transaction."></x-field>
+  <x-field data-name="token" data-type="object" data-required="true" data-desc="An object defining the properties of the token to be created.">
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="The full name of the token (e.g., 'My Awesome Token')."></x-field>
+    <x-field data-name="symbol" data-type="string" data-required="true" data-desc="The token's ticker symbol (e.g., 'MAT')."></x-field>
+    <x-field data-name="decimal" data-type="number" data-required="true" data-desc="The number of decimal places the token supports."></x-field>
+    <x-field data-name="description" data-type="string" data-required="false" data-desc="A brief description of the token."></x-field>
+    <x-field data-name="icon" data-type="string" data-required="false" data-desc="URL to an icon for the token."></x-field>
+    <x-field data-name="maxTotalSupply" data-type="number" data-required="false" data-desc="The maximum total supply that can ever be minted."></x-field>
+  </x-field>
+  <x-field data-name="curve" data-type="object" data-required="false" data-desc="Configuration for a bonding curve, which programmatically controls the token's price. If omitted, minting/burning is not tied to a reserve token.">
+    <x-field data-name="basePrice" data-type="number" data-required="false" data-desc="The base price for the token in the reserve currency."></x-field>
+    <x-field data-name="fixedPrice" data-type="number" data-required="false" data-desc="A fixed price for the token, if not using a dynamic curve."></x-field>
+    <x-field data-name="slope" data-type="number" data-required="false" data-desc="The slope of the bonding curve, determining its steepness."></x-field>
+  </x-field>
+  <x-field data-name="feeRate" data-type="number" data-default="0" data-required="false" data-desc="The fee rate (in basis points) for minting and burning operations."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional custom data to attach to the token factory."></x-field>
+</x-field-group>
+
+### Returns
+
+Returns a promise that resolves to an array containing the transaction hash and the address of the newly created token factory.
+
+<x-field-group>
+  <x-field data-name="[0]" data-type="string" data-desc="The transaction hash for the factory creation."></x-field>
+  <x-field data-name="[1]" data-type="string" data-desc="The address of the new token factory."></x-field>
+</x-field-group>
+
+### Example
+
+```javascript Create a Token Factory icon=logos:javascript
+import Client from '@ocap/client';
+import Wallet from '@ocap/wallet';
+
+const endpoint = 'https://beta.abtnetwork.io/api';
+const client = new Client(endpoint);
+const wallet = Wallet.fromRandom();
+
+// First, ensure the wallet has funds. You can get test tokens from a faucet:
+// https://faucet.abtnetwork.io/
+
+async function createFactory() {
+  try {
+    const [hash, factoryAddress] = await client.createTokenFactory({
+      wallet,
+      token: {
+        name: 'My Game Coin',
+        symbol: 'MGC',
+        decimal: 18,
+        description: 'The official currency for My Awesome Game.',
+        maxTotalSupply: 1000000,
+      },
+      feeRate: 100, // 1% fee
+    });
+
+    console.log('Token factory created successfully!');
+    console.log('Transaction Hash:', hash);
+    console.log('Factory Address:', factoryAddress);
+    return factoryAddress;
+  } catch (error) {
+    console.error('Error creating token factory:', error);
+  }
+}
+
+createFactory();
+```
+
+## Mint Tokens
+
+Minting is the process of creating new tokens and adding them to the total supply. This is done through a token factory. If the factory was configured with a bonding curve, minting will require a payment in the reserve token.
+
+The `mintToken` method initiates a transaction to mint a specified amount of tokens from a factory.
+
+### Parameters
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet funding the mint operation and signing the transaction."></x-field>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="The address of the token factory to mint from."></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="The quantity of 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 the reserve token the wallet is willing to spend. This acts as a slippage protection mechanism."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional custom data to attach to the mint transaction."></x-field>
+</x-field-group>
+
+### Returns
+
+Returns a promise that resolves to the transaction hash.
+
+<x-field data-name="hash" data-type="string" data-desc="The transaction hash for the mint operation."></x-field>
+
+### Example
+
+```javascript Mint Tokens from a Factory icon=logos:javascript
+async function mintNewTokens(factoryAddress) {
+  try {
+    const hash = await client.mintToken({
+      wallet,
+      tokenFactory: factoryAddress,
+      amount: 5000,
+      receiver: wallet.address, // Mint tokens to our own wallet
+      maxReserve: 10, // Max reserve token to pay. Adjust based on bonding curve price.
+    });
+
+    console.log('Tokens minted successfully!');
+    console.log('Transaction Hash:', hash);
+  } catch (error) {
+    console.error('Error minting tokens:', error);
+  }
+}
+
+// Assuming `factoryAddress` is available from the createFactory example
+// const factoryAddress = '...'; 
+// mintNewTokens(factoryAddress);
+```
+
+## Burn Tokens
+
+Burning is the opposite of minting; it permanently removes tokens from circulation. If the token factory uses a bonding curve, burning tokens will return a proportional amount of the reserve currency to the user.
+
+The `burnToken` method initiates this process.
+
+### Parameters
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet that holds the tokens to be burned and will sign the transaction."></x-field>
+  <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 quantity 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 in return."></x-field>
+  <x-field data-name="minReserve" data-type="number" data-required="true" data-desc="The minimum amount of the reserve token the wallet expects to receive. This protects against price slippage."></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="Optional custom data to attach to the burn transaction."></x-field>
+</x-field-group>
+
+### Returns
+
+Returns a promise that resolves to the transaction hash.
+
+<x-field data-name="hash" data-type="string" data-desc="The transaction hash for the burn operation."></x-field>
+
+### Example
+
+```javascript Burn Tokens icon=logos:javascript
+async function burnExistingTokens(factoryAddress) {
+  try {
+    const hash = await client.burnToken({
+      wallet,
+      tokenFactory: factoryAddress,
+      amount: 1000,
+      receiver: wallet.address, // Receive reserve tokens back to our own wallet
+      minReserve: 1, // Min reserve token to receive. Adjust based on bonding curve price.
+    });
+
+    console.log('Tokens burned successfully!');
+    console.log('Transaction Hash:', hash);
+  } catch (error) {
+    console.error('Error burning tokens:', error);
+  }
+}
+
+// Assuming `factoryAddress` is available from the createFactory example
+// const factoryAddress = '...'; 
+// burnExistingTokens(factoryAddress);
+```
+
+## Summary
+
+In this guide, you've learned the complete lifecycle for managing fungible tokens: creating a factory, minting new tokens into existence, and burning them to reduce the supply. These powerful primitives allow you to build sophisticated economic systems on the OCAP platform.
+
+Now that you know how to create tokens, the next logical step is to learn how to move them around. Head over to the [Transfer Tokens and NFTs](./how-to-guides-transfer-tokens-and-nfts.md) guide to see how it's done.

package/docs/how-to-guides-manage-tokens.zh.md

@@ -0,0 +1,179 @@
+# 管理代币
+
+本指南提供了使用 OCAP Client 管理同质化代幣的详细步骤。你将学习如何设置代币工厂（作为代币的蓝图），并使用它来铸造（创建新代币）和销毁（销毁现有代币）。这些操作是在你的应用程序中创建和管理自定义经济体系的基础。
+
+铸造代币后，你可以在账户之间进行转移。有关该过程的更多详细信息，请参阅[转移代币和 NFT](./how-to-guides-transfer-tokens-and-nfts.md)指南。
+
+## 创建代币工厂
+
+代币工厂是一种智能合约，用于定义同质化代幣的属性和规则，例如其名称、符号和供应机制。它还管理铸造和销毁的过程。创建工厂是将任何新代币投入流通的第一步。
+
+`createTokenFactory` 方法将一个新的代币工厂部署到区块链上。
+
+### 参数
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="工厂所有者的钱包对象，用于签署交易。"></x-field>
+  <x-field data-name="token" data-type="object" data-required="true" data-desc="一个定义待创建代币属性的对象。">
+    <x-field data-name="name" data-type="string" data-required="true" data-desc="代币的全名（例如，'My Awesome Token'）。"></x-field>
+    <x-field data-name="symbol" data-type="string" data-required="true" data-desc="代币的股票代码符号（例如，'MAT'）。"></x-field>
+    <x-field data-name="decimal" data-type="number" data-required="true" data-desc="代币支持的小数位数。"></x-field>
+    <x-field data-name="description" data-type="string" data-required="false" data-desc="代币的简要描述。"></x-field>
+    <x-field data-name="icon" data-type="string" data-required="false" data-desc="代币图标的 URL。"></x-field>
+    <x-field data-name="maxTotalSupply" data-type="number" data-required="false" data-desc="可铸造的最大总供应量。"></x-field>
+  </x-field>
+  <x-field data-name="curve" data-type="object" data-required="false" data-desc="联合曲线的配置，以编程方式控制代币价格。如果省略，铸造/销毁将不与储备代币挂钩。">
+    <x-field data-name="basePrice" data-type="number" data-required="false" data-desc="以储备货币计价的代币基础价格。"></x-field>
+    <x-field data-name="fixedPrice" data-type="number" data-required="false" data-desc="代币的固定价格，如果不使用动态曲线。"></x-field>
+    <x-field data-name="slope" data-type="number" data-required="false" data-desc="联合曲线的斜率，决定其陡峭程度。"></x-field>
+  </x-field>
+  <x-field data-name="feeRate" data-type="number" data-default="0" data-required="false" data-desc="铸造和销毁操作的费率（以基点为单位）。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="附加到代币工厂的可选自定义数据。"></x-field>
+</x-field-group>
+
+### 返回值
+
+返回一个 promise，该 promise 解析为一个数组，其中包含交易哈希和新创建的代币工厂的地址。
+
+<x-field-group>
+  <x-field data-name="[0]" data-type="string" data-desc="创建工厂的交易哈希。"></x-field>
+  <x-field data-name="[1]" data-type="string" data-desc="新代币工厂的地址。"></x-field>
+</x-field-group>
+
+### 示例
+
+```javascript Create a Token Factory icon=logos:javascript
+import Client from '@ocap/client';
+import Wallet from '@ocap/wallet';
+
+const endpoint = 'https://beta.abtnetwork.io/api';
+const client = new Client(endpoint);
+const wallet = Wallet.fromRandom();
+
+// 首先，确保钱包中有资金。你可以从水龙头获取测试代币：
+// https://faucet.abtnetwork.io/
+
+async function createFactory() {
+  try {
+    const [hash, factoryAddress] = await client.createTokenFactory({
+      wallet,
+      token: {
+        name: 'My Game Coin',
+        symbol: 'MGC',
+        decimal: 18,
+        description: 'The official currency for My Awesome Game.',
+        maxTotalSupply: 1000000,
+      },
+      feeRate: 100, // 1% 的费用
+    });
+
+    console.log('代币工厂创建成功！');
+    console.log('交易哈希：', hash);
+    console.log('工厂地址：', factoryAddress);
+    return factoryAddress;
+  } catch (error) {
+    console.error('创建代币工厂时出错：', error);
+  }
+}
+
+createFactory();
+```
+
+## 铸造代币
+
+铸造是创建新代币并将其添加到总供应量中的过程。这是通过代币工厂完成的。如果工厂配置了联合曲线，铸造将需要使用储备代币进行支付。
+
+`mintToken` 方法会启动一个交易，从工厂铸造指定数量的代币。
+
+### 参数
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="为铸造操作提供资金并签署交易的钱包。"></x-field>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="要从中铸造代币的代币工厂的地址。"></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="要铸造的代币数量。"></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="将接收新铸造代币的地址。"></x-field>
+  <x-field data-name="maxReserve" data-type="number" data-required="true" data-desc="钱包愿意花费的储备代币的最大数量。这可以作为一种滑点保护机制。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="附加到铸造交易的可选自定义数据。"></x-field>
+</x-field-group>
+
+### 返回值
+
+返回一个 promise，该 promise 解析为交易哈希。
+
+<x-field data-name="hash" data-type="string" data-desc="铸造操作的交易哈希。"></x-field>
+
+### 示例
+
+```javascript Mint Tokens from a Factory icon=logos:javascript
+async function mintNewTokens(factoryAddress) {
+  try {
+    const hash = await client.mintToken({
+      wallet,
+      tokenFactory: factoryAddress,
+      amount: 5000,
+      receiver: wallet.address, // 将代币铸造到我们自己的钱包
+      maxReserve: 10, // 支付的最大储备代币。根据联合曲线价格进行调整。
+    });
+
+    console.log('代币铸造成功！');
+    console.log('交易哈希：', hash);
+  } catch (error) {
+    console.error('铸造代币时出错：', error);
+  }
+}
+
+// 假设 `factoryAddress` 可从 createFactory 示例中获得
+// const factoryAddress = '...'; 
+// mintNewTokens(factoryAddress);
+```
+
+## 销毁代币
+
+销毁与铸造相反；它会永久地将代币从流通中移除。如果代币工厂使用联合曲线，销毁代币将向用户返回相应比例的储备货币。
+
+`burnToken` 方法会启动此过程。
+
+### 参数
+<x-field-group>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="持有待销毁代币并将签署交易的钱包。"></x-field>
+  <x-field data-name="tokenFactory" data-type="string" data-required="true" data-desc="代币工厂的地址。"></x-field>
+  <x-field data-name="amount" data-type="number" data-required="true" data-desc="要销毁的代币数量。"></x-field>
+  <x-field data-name="receiver" data-type="string" data-required="true" data-desc="将接收返还的储备代币的地址。"></x-field>
+  <x-field data-name="minReserve" data-type="number" data-required="true" data-desc="钱包期望收到的储备代币的最低数量。这可以防止价格滑点。"></x-field>
+  <x-field data-name="data" data-type="object" data-required="false" data-desc="附加到销毁交易的可选自定义数据。"></x-field>
+</x-field-group>
+
+### 返回值
+
+返回一个 promise，该 promise 解析为交易哈希。
+
+<x-field data-name="hash" data-type="string" data-desc="销毁操作的交易哈希。"></x-field>
+
+### 示例
+
+```javascript Burn Tokens icon=logos:javascript
+async function burnExistingTokens(factoryAddress) {
+  try {
+    const hash = await client.burnToken({
+      wallet,
+      tokenFactory: factoryAddress,
+      amount: 1000,
+      receiver: wallet.address, // 将储备代币接收回我们自己的钱包
+      minReserve: 1, // 接收的最低储备代币。根据联合曲线价格进行调整。
+    });
+
+    console.log('代币销毁成功！');
+    console.log('交易哈希：', hash);
+  } catch (error) {
+    console.error('销毁代币时出错：', error);
+  }
+}
+
+// 假设 `factoryAddress` 可从 createFactory 示例中获得
+// const factoryAddress = '...'; 
+// burnExistingTokens(factoryAddress);
+```
+
+## 总结
+
+在本指南中，你学习了管理同质化代幣的完整生命周期：创建工厂、铸造新代币以及销毁代币以减少供应。这些强大的原语使你能够在 OCAP 平台上构建复杂的经济系统。
+
+现在你已经知道如何创建代币，下一个合乎逻辑的步骤是学习如何转移它们。请前往[转移代币和 NFT](./how-to-guides-transfer-tokens-and-nfts.md)指南查看具体操作方法。

package/docs/how-to-guides-stake-tokens-and-assets.md

@@ -0,0 +1,205 @@
+# Stake Tokens and Assets
+
+Staking is the process of locking up tokens or assets (NFTs) to a specific receiver, often to secure a network, participate in governance, or earn rewards. This guide provides a step-by-step walkthrough of the entire staking lifecycle using the OCAP Client, including creating a stake, revoking it, claiming the assets back, and slashing a stake for punitive reasons.
+
+This process involves a few key methods:
+- `stake()`: To create a new stake.
+- `revokeStake()`: To initiate the process of withdrawing your staked items.
+- `claimStake()`: To finalize the withdrawal and return the items to your account.
+- `slashStake()`: To allow authorized parties to penalize a staker.
+
+## How to Stake
+
+To begin, you use the `stake` method to lock your tokens or assets. This action creates a new, unique stake address on the chain that holds your staked items and the rules governing them.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="to" data-type="string" data-required="true" data-desc="The DID address of the account that will receive the stake."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses (NFTs) to be staked."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of token objects to be staked.">
+    <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the token contract."></x-field>
+    <x-field data-name="value" data-type="number" data-required="true" data-desc="The amount of tokens to stake."></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet object of the staker."></x-field>
+  <x-field data-name="locked" data-type="boolean" data-default="false" data-required="false" data-desc="A boolean indicating if the stake is locked upon creation."></x-field>
+  <x-field data-name="slashers" data-type="string[]" data-required="false" data-desc="An array of DID addresses permitted to slash this stake. Defaults to the receiver's address if not provided."></x-field>
+  <x-field data-name="message" data-type="string" data-required="false" data-desc="An optional note or message for the stake."></x-field>
+  <x-field data-name="nonce" data-type="string" data-required="false" data-desc="An optional nonce to ensure the stake address is unique."></x-field>
+</x-field-group>
+
+### Example
+
+```javascript Staking Tokens and an Asset icon=logos:javascript
+// Assume 'client' is an initialized GraphQLClient instance
+// and 'stakerWallet' is a valid wallet object.
+const receiverAddress = 'z29d5852576b8a8b6f3a8b4b74a3f4a3e2e1d'; // The address of the stake receiver
+
+async function createStake() {
+  try {
+    const [txHash, stakeAddress] = await client.stake({
+      to: receiverAddress,
+      tokens: [{
+        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E', // Address of the token to stake
+        value: 100, // Amount of tokens to stake
+      }],
+      assets: ['zNKtA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6'], // Address of the asset/NFT to stake
+      message: 'Staking for validator rewards',
+      wallet: stakerWallet,
+    });
+
+    console.log('Stake transaction sent:', txHash);
+    console.log('New stake address created:', stakeAddress);
+    return stakeAddress;
+  } catch (error) {
+    console.error('Error creating stake:', error);
+  }
+}
+```
+
+### Return Value
+
+The `stake` method returns a tuple containing the transaction hash and the newly created `stakeAddress`. This address is crucial for all future interactions with this specific stake, such as revoking or slashing.
+
+---
+
+## How to Revoke a Stake
+
+Revoking a stake is the process initiated by the staker to retrieve their locked tokens and assets. This transaction does not immediately return the funds; instead, it marks them as available for claiming, subject to any on-chain lock-up periods.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake to be revoked (obtained from the 'stake' call)."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses to revoke from the stake."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of token objects to revoke.">
+    <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the token contract."></x-field>
+    <x-field data-name="value" data-type="number" data-required="true" data-desc="The amount of tokens to revoke."></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The staker's wallet object, which must be the original creator of the stake."></x-field>
+</x-field-group>
+
+### Example
+
+```javascript Revoking a Stake icon=logos:javascript
+// Assume 'stakeAddress' is the address returned from the previous step
+// and 'stakerWallet' is the same wallet used to create the stake.
+
+async function revokeExistingStake(stakeAddress) {
+  try {
+    const revokeTxHash = await client.revokeStake({
+      from: stakeAddress,
+      tokens: [{
+        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E',
+        value: 100,
+      }],
+      assets: ['zNKtA1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6'],
+      wallet: stakerWallet,
+    });
+
+    console.log('Revoke stake transaction sent:', revokeTxHash);
+    console.log('IMPORTANT: Save this hash to claim your stake later.');
+    return revokeTxHash;
+  } catch (error) {
+    console.error('Error revoking stake:', error);
+  }
+}
+```
+
+### Return Value
+
+This function returns the transaction hash of the revoke operation. This hash serves as evidence and is **required** for the final step of claiming the stake.
+
+---
+
+## How to Claim a Revoked Stake
+
+After a stake has been successfully revoked, the staker must send a `claimStake` transaction to move the tokens and assets back into their account. This finalizes the withdrawal process.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake."></x-field>
+  <x-field data-name="evidence" data-type="string" data-required="true" data-desc="The transaction hash from the 'revokeStake' call, which serves as proof of revocation."></x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The staker's wallet object."></x-field>
+</x-field-group>
+
+### Example
+
+```javascript Claiming Staked Items icon=logos:javascript
+// Assume 'stakeAddress' and 'revokeTxHash' are from the previous steps,
+// and 'stakerWallet' is the staker's wallet.
+
+async function claimRevokedStake(stakeAddress, revokeTxHash) {
+  try {
+    const claimTxHash = await client.claimStake({
+      from: stakeAddress,
+      evidence: revokeTxHash,
+      wallet: stakerWallet,
+    });
+
+    console.log('Claim stake transaction sent:', claimTxHash);
+    console.log('Your tokens and assets have been returned to your account.');
+  } catch (error) {
+    console.error('Error claiming stake:', error);
+  }
+}
+```
+
+### Return Value
+
+The method returns the final transaction hash. Once this transaction is confirmed on the chain, the staked items are returned to the `wallet`'s address.
+
+---
+
+## How to Slash a Stake
+
+Slashing is a punitive action that can be taken by a designated `slasher` (usually the stake receiver) against a staker. This typically happens if the staker violates certain rules. The slashed tokens or assets are removed from the stake and sent to a designated vault.
+
+### Parameters
+
+<x-field-group>
+  <x-field data-name="from" data-type="string" data-required="true" data-desc="The address of the stake to be slashed."></x-field>
+  <x-field data-name="reason" data-type="string" data-required="true" data-desc="A mandatory message explaining why the slash is occurring."></x-field>
+  <x-field data-name="assets" data-type="string[]" data-required="false" data-desc="An array of asset addresses to be slashed from the stake."></x-field>
+  <x-field data-name="tokens" data-type="object[]" data-required="false" data-desc="An array of token objects to be slashed.">
+    <x-field data-name="address" data-type="string" data-required="true" data-desc="The address of the token contract."></x-field>
+    <x-field data-name="value" data-type="number" data-required="true" data-desc="The amount of tokens to slash."></x-field>
+  </x-field>
+  <x-field data-name="wallet" data-type="WalletObject" data-required="true" data-desc="The wallet object of an authorized slasher."></x-field>
+</x-field-group>
+
+### Example
+
+```javascript Slashing a Stake icon=logos:javascript
+// Assume 'stakeAddress' is the address of the stake to be slashed,
+// and 'slasherWallet' is the wallet of an authorized slasher.
+
+async function slashExistingStake(stakeAddress) {
+  try {
+    const slashTxHash = await client.slashStake({
+      from: stakeAddress,
+      reason: 'Validator missed signing 10 consecutive blocks.',
+      tokens: [{
+        address: 'z35n6aTUTK8h5nAF43h21A1g84g3C3D7B5E',
+        value: 10, // Slashing 10 tokens as a penalty
+      }],
+      wallet: slasherWallet,
+    });
+
+    console.log('Slash stake transaction sent:', slashTxHash);
+  } catch (error) {
+    console.error('Error slashing stake:', error);
+  }
+}
+```
+
+### Return Value
+
+This method returns the transaction hash for the slashing operation.
+
+## Summary
+
+You've now learned the complete lifecycle of staking on the OCAP blockchain: creating a stake with `stake`, retrieving funds with `revokeStake` and `claimStake`, and penalizing bad actors with `slashStake`. This powerful mechanism is fundamental to many decentralized applications.
+
+To learn more about the items you can stake, see the [Manage Tokens](./how-to-guides-manage-tokens.md) and [Manage Assets (NFTs)](./how-to-guides-manage-assets.md) guides.