@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/interchain-accounts.md

@@ -0,0 +1,223 @@
+# Interchain Accounts
+
+## What are Interchain Accounts?
+
+The **Interchain Accounts (ICA)** allow one blockchain to control an account on another blockchain using IBC.
+
+This enables:
+
+* Remote account creation
+* Cross-chain transaction execution
+
+Instead of bridging tokens, ICA lets one chain execute transactions on another chain as if it owned an account there.
+
+---
+
+# Important Terminology
+
+Before documenting functions, let’s define key terms.
+
+### Controller Chain
+
+The chain that initiates and controls an interchain account.
+
+It:
+
+* Creates the remote account
+* Sends transactions
+* Manages execution logic
+
+### Host Chain
+
+The chain that hosts the interchain account.
+
+It:
+
+* Creates the account
+* Executes transactions
+* Applies local validation rules
+
+### Interchain Account
+
+A special account on the **host chain** that is controlled by a **controller chain** via IBC.
+
+It behaves like a normal account but is operated remotely.
+
+### ICA Controller Module
+
+Submodule responsible for:
+
+* Registering interchain accounts
+* Sending transaction packets
+* Managing remote execution
+
+### ICA Host Module
+
+Submodule responsible for:
+
+* Creating accounts for controllers
+* Executing received transactions
+* Defining which messages are allowed
+
+---
+
+# Functions Documentation
+
+## Setup
+
+```ts
+import {
+  ChainInterchainAccountsApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const icaApi = new ChainInterchainAccountsApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchControllerParams
+
+## Method
+
+```ts
+async fetchControllerParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query interchain-accounts controller params
+```
+
+## Description
+
+Fetches the **ICA Controller module parameters**.
+
+These parameters define whether the chain is allowed to:
+
+* Create interchain accounts
+* Send remote execution transactions
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const controllerParams = await icaApi.fetchControllerParams()
+console.dir(controllerParams, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "controller_enabled": true
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field              | Description                                                             |
+| ------------------ | ----------------------------------------------------------------------- |
+| controller_enabled | Indicates whether ICA controller functionality is enabled on this chain |
+
+If `false`, the chain cannot initiate interchain accounts.
+
+## When to Use
+
+* Checking if ICA controller is active
+* Validating cross-chain automation availability
+* Governance audits
+* Chain status dashboards
+
+---
+
+# 2️⃣ fetchHostParams
+
+## Method
+
+```ts
+async fetchHostParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query interchain-accounts host params
+```
+
+## Description
+
+Fetches the **ICA Host module parameters**.
+
+These parameters define:
+
+* Whether the chain can host interchain accounts
+* Which message types remote controllers are allowed to execute
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const hostParams = await icaApi.fetchHostParams()
+console.dir(hostParams, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "host_enabled": true,
+    "allow_messages": ["*"]
+  }
+}
+```
+
+## Response Field Explanation
+
+### `params`
+
+| Field          | Description                                                  |
+| -------------- | ------------------------------------------------------------ |
+| host_enabled   | Indicates whether this chain can host interchain accounts    |
+| allow_messages | List of allowed message types remote controllers may execute |
+
+If `allow_messages` contains `"*"`, all message types are allowed.
+
+If restricted, only specific message types can be executed.
+
+## When to Use
+
+* Verifying if the chain accepts ICA requests
+* Checking remote execution permissions
+* Security auditing
+---
+
+# How Interchain Accounts Work (Simple Flow)
+
+Example:
+
+* ZigChain = Controller
+* Another chain = Host
+
+1️⃣ ZigChain registers an interchain account on the host chain
+2️⃣ The host chain creates a new account
+3️⃣ ZigChain sends transaction packets
+4️⃣ The host chain executes those transactions
+
+From the host chain’s perspective, it looks like a normal account submitting transactions — but it is controlled remotely.
+
+---

package/docs/mint.md

@@ -0,0 +1,270 @@
+# Mint Module
+
+## What is the Mint Module?
+
+The **Mint module** is responsible for controlling the chain’s token inflation.
+
+It:
+
+* Mints new tokens
+* Adjusts inflation dynamically
+* Distributes newly minted tokens (usually to staking rewards)
+
+On ZigChain, this module defines how **`uzig`** is issued over time.
+
+---
+
+# Important Terminology
+
+### Inflation
+
+The annual rate at which new tokens are created.
+
+Example:
+
+```
+0.0152 → 1.52% yearly inflation
+```
+
+---
+
+### Annual Provisions
+
+The total number of tokens minted per year at the current inflation rate.
+
+---
+
+### Mint Denom
+
+The base token denomination used for minting.
+
+On ZigChain:
+
+```
+uzig
+```
+
+---
+
+### Goal Bonded
+
+Target percentage of total supply that should be staked (bonded).
+
+The inflation rate adjusts to move toward this target.
+
+---
+
+### Blocks Per Year
+
+Estimated number of blocks produced annually.
+Used to calculate per-block minting rewards.
+
+---
+
+# Setup
+
+```ts
+import {
+  ChainMintApi,
+  getNetworkEndpoints,
+  Network,
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const mintApi = new ChainMintApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchInflation
+
+## Method
+
+```ts
+async fetchInflation()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query mint inflation
+```
+
+## Description
+
+Fetches the **current annual inflation rate** of the chain.
+
+Inflation determines how many new tokens are created each year.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const inflation = await mintApi.fetchInflation()
+console.log(inflation)
+```
+
+## Example Response
+
+```json
+{
+  "inflation": "0.015253209212607990"
+}
+```
+
+## Response Field Explanation
+
+| Field     | Description                                   |
+| --------- | --------------------------------------------- |
+| inflation | Annual inflation rate (decimal string format) |
+
+In this example:
+
+```
+0.0152532 → 1.52532% annual inflation
+```
+
+---
+
+# 2️⃣ fetchAnnualProvisions
+
+## Method
+
+```ts
+async fetchAnnualProvisions()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query mint annual-provisions
+```
+
+## Description
+
+Fetches the **total amount of tokens minted per year** at the current inflation rate.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const annualProvisions = await mintApi.fetchAnnualProvisions()
+console.log(annualProvisions)
+```
+
+## Example Response
+
+```json
+{
+  "annual_provisions": "35437230683581.300264112982799590"
+}
+```
+
+## Response Field Explanation
+
+| Field             | Description                                                |
+| ----------------- | ---------------------------------------------------------- |
+| annual_provisions | Total tokens minted per year (string format for precision) |
+
+
+---
+
+# 3️⃣ fetchParams
+
+## Method
+
+```ts
+async fetchParams()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query mint params
+```
+
+## Description
+
+Fetches the **Mint module parameters** that control inflation behavior.
+
+These parameters define:
+
+* Inflation boundaries
+* Adjustment rate
+* Target staking ratio
+* Mint denomination
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const params = await mintApi.fetchParams()
+console.dir(params, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "params": {
+    "mint_denom": "uzig",
+    "inflation_rate_change": "0.020000000000000000",
+    "inflation_max": "0.020000000000000000",
+    "inflation_min": "0.009000000000000000",
+    "goal_bonded": "0.150000000000000000",
+    "blocks_per_year": "12614400"
+  }
+}
+```
+
+## Response Field Explanation
+
+| Field                 | Description                              |
+| --------------------- | ---------------------------------------- |
+| mint_denom            | Token denomination used for minting      |
+| inflation_rate_change | Maximum annual inflation adjustment rate |
+| inflation_max         | Maximum possible inflation               |
+| inflation_min         | Minimum possible inflation               |
+| goal_bonded           | Target percentage of tokens staked       |
+| blocks_per_year       | Estimated blocks produced per year       |
+
+---
+
+# Example (Full)
+
+```ts
+import {
+  ChainMintApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+async function main() {
+  const endpoints = getNetworkEndpoints(Network.Testnet)
+  const mintApi = new ChainMintApi(endpoints)
+
+  const inflation = await mintApi.fetchInflation()
+  console.log('Inflation:', inflation)
+
+  const annualProvisions = await mintApi.fetchAnnualProvisions()
+  console.log('Annual Provisions:', annualProvisions)
+
+  const params = await mintApi.fetchParams()
+  console.log('Mint Params:')
+  console.dir(params, { depth: null })
+}
+
+main()
+```
+
+---
+

package/docs/runtime.md

@@ -0,0 +1,120 @@
+# Runtime Module
+
+## What is the Runtime Module?
+
+The **Runtime module** exposes configuration details about the running ZigChain node.
+
+It does **not** return blockchain state like balances or validators.
+
+Instead, it returns **node-level configuration settings** that define how the application behaves.
+
+---
+# Setup
+
+```ts
+import {
+  ChainRuntimeApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const runtime = new ChainRuntimeApi(endpoints)
+```
+
+---
+
+# 1️⃣ fetchConfig
+
+## Method
+
+```ts
+async fetchConfig()
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query runtime config
+```
+
+## Description
+
+Fetches the **current node runtime configuration**.
+
+This includes:
+
+* Minimum gas price
+* Pruning strategy settings
+* Halt height configuration
+* Other core node parameters
+
+This is **node-level configuration**, not consensus state.
+
+## Parameters
+
+None.
+
+## Usage Example
+
+```ts
+const config = await runtime.fetchConfig()
+console.dir(config, { depth: null })
+```
+
+## Example Response
+
+```json
+{
+  "minimum_gas_price": "0.002500000000000000uzig",
+  "pruning_keep_recent": "100",
+  "pruning_interval": "10",
+  "halt_height": "0"
+}
+```
+
+## Response Field Explanation
+
+| Field               | Description                                             |
+| ------------------- | ------------------------------------------------------- |
+| minimum_gas_price   | Minimum gas price required for transactions             |
+| pruning_keep_recent | Number of recent heights to keep during pruning         |
+| pruning_interval    | Interval (in blocks) between pruning operations         |
+| halt_height         | Block height at which the node will stop (0 = disabled) |
+
+### minimum_gas_price
+
+Example:
+
+```
+0.0025uzig
+```
+
+This means transactions must pay at least this gas price to be accepted by the node.
+
+### pruning_keep_recent
+
+Defines how many recent blocks the node keeps before pruning older state.
+
+Lower values → smaller storage
+Higher values → more historical data retained
+
+### pruning_interval
+
+How often pruning is executed (in block intervals).
+
+### halt_height
+
+If set to a value greater than 0, the node will automatically stop at that block height.
+
+`0` means no automatic halt.
+
+---
+# Summary
+
+| Function        | CLI Equivalent                   | Purpose                            |
+| --------------- | -------------------------------- | ---------------------------------- |
+| `fetchConfig()` | `zigchaind query runtime config` | Returns node runtime configuration |
+
+---
+