@zuhaibnoor/zigchain-sdk 1.1.0 → 1.1.1

package/docs/circuit.md

@@ -1,7 +1,50 @@
 # Circuit Module
 
-The **ChainCircuitApi** lets you query **account-level transaction permissions** for the circuit module.
-It is mainly used to check which accounts are **blocked or restricted** from sending transactions on the chain.
+## What is the Circuit Module?
+
+The **Circuit module** provides a **transaction permission and circuit breaker** system for ZigChain.
+
+It allows designated super-admin accounts to selectively disable specific message types on the chain — acting as an emergency brake. This is a governance and safety mechanism, not something that affects normal users under typical chain operation.
+
+---
+
+## Important Terminology
+
+### Circuit Breaker
+
+A **circuit breaker** is a safety mechanism that allows authorized accounts to disable specific transaction types on the chain without requiring a full governance vote. This is used in emergency situations — for example, if a vulnerability is discovered in a particular module.
+
+---
+
+### Permission Level
+
+Each account in the circuit module is assigned a **permission level** that defines what authority they have over circuit controls.
+
+| Level               | Description                                                                 |
+| ------------------- | --------------------------------------------------------------------------- |
+| `LEVEL_NONE_UNSPECIFIED` | No circuit permissions — standard account                             |
+| `LEVEL_SOME_MSGS`   | Can disable a specific limited set of message types only                    |
+| `LEVEL_ALL_MSGS`    | Can disable any message type on the chain                                   |
+| `LEVEL_SUPER_ADMIN` | Full control — can disable messages and grant/revoke permissions to others  |
+
+---
+
+### Limit Type URLs
+
+When a permission level is `LEVEL_SOME_MSGS`, the `limit_type_urls` field specifies exactly which message types that account is authorized to circuit-break.
+
+An empty `limit_type_urls` combined with `LEVEL_SUPER_ADMIN` means the account has **unrestricted** circuit breaker authority — no specific limits apply.
+
+Example of a type URL:
+```
+/cosmos.bank.v1beta1.MsgSend
+```
+
+---
+
+### Disabled List
+
+The set of message type URLs that are currently disabled (circuit-broken) on the chain. Any transaction containing a disabled message type will be rejected until the circuit is reset.
 
 ---
 
@@ -16,78 +59,164 @@ import {
 
 const endpoints = getNetworkEndpoints(Network.Testnet)
 const circuitApi = new ChainCircuitApi(endpoints)
+
+const address = 'zig15yk64u7zc9g9k2yr2wmzeva5qgwxps6y8c2amk'
 ```
 
 ---
 
-## `getAccountPermissions`
+# 1️⃣ getAccountPermissions
 
-Fetch the **circuit permissions for a specific account**.
+## Method
+
+```ts
+async getAccountPermissions(address: string)
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query circuit account <address>
 ```
 
-**Method**
+## Description
+
+Fetches the **circuit breaker permissions** assigned to a specific account.
+
+This tells you what level of circuit authority an account holds and, if applicable, which message types they are restricted to controlling. Most regular accounts will have no circuit permissions at all — only specifically designated addresses will appear in the circuit module with elevated levels.
+
+## Parameters
+
+| Name    | Type   | Description                                           |
+| ------- | ------ | ----------------------------------------------------- |
+| address | string | Bech32 address of the account to query permissions for |
+
+## Usage Example
 
 ```ts
-getAccountPermissions(address: string)
+const account = await circuitApi.getAccountPermissions(address)
+console.dir(account, { depth: null })
 ```
 
-**Parameters**
+## Example Response
 
-* `address: string` – The account address to query.
+```json
+{
+  "permission": {
+    "level": "LEVEL_SUPER_ADMIN",
+    "limit_type_urls": []
+  }
+}
+```
 
-**Returns**
+## Response Field Explanation
 
-* `CircuitAccountResponse` – Contains whether the account is blocked or restricted.
+### `permission`
 
-**Example**
+| Field            | Description                                                                       |
+| ---------------- | --------------------------------------------------------------------------------- |
+| level            | Permission level assigned to this account                                         |
+| limit_type_urls  | Specific message type URLs this account can circuit-break. Empty if unrestricted  |
 
-```ts
-const address = 'zig1svkn4sqrlz8r6krq96ty6kze54n2ec03u0vat5'
-const permissions = await circuitApi.getAccountPermissions(address)
-console.log(`Circuit permissions for ${address}:`)
-console.dir(permissions, { depth: null })
-```
+### Permission Level Values
+
+| Value                    | Meaning                                                              |
+| ------------------------ | -------------------------------------------------------------------- |
+| `LEVEL_NONE_UNSPECIFIED` | No circuit permissions                                               |
+| `LEVEL_SOME_MSGS`        | Can only circuit-break the specific types listed in `limit_type_urls` |
+| `LEVEL_ALL_MSGS`         | Can circuit-break any message type                                   |
+| `LEVEL_SUPER_ADMIN`      | Full authority — can circuit-break messages and manage permissions   |
+
+> In the example above, `LEVEL_SUPER_ADMIN` with an empty `limit_type_urls` means this account has unrestricted circuit breaker authority over the entire chain.
+
+## When to Use
+
+* Verifying whether a specific address holds circuit breaker authority
+* Auditing which accounts can perform emergency interventions
+* Security reviews of chain admin key holders
+* Building governance monitoring tools
 
 ---
 
-## `getAllAccountPermissions`
+# 2️⃣ getAllAccountPermissions
+
+## Method
 
-Fetch **all accounts with circuit restrictions or permissions**.
+```ts
+async getAllAccountPermissions()
+```
 
-**CLI equivalent**
+## CLI Equivalent
 
 ```bash
 zigchaind query circuit accounts
 ```
 
-**Method**
+## Description
 
-```ts
-getAllAccountPermissions()
-```
+Fetches **all accounts** that have been assigned circuit breaker permissions on the chain.
+
+On ZigChain testnet, only one account currently holds circuit permissions (`LEVEL_SUPER_ADMIN`). This reflects the typical setup where circuit authority is granted to a small number of trusted admin addresses for emergency use.
 
-**Returns**
+## Parameters
 
-* `CircuitAccountsResponse` – Contains a list of all accounts and their circuit permission status.
+None.
 
-**Example**
+## Usage Example
 
 ```ts
-const allPermissions = await circuitApi.getAllAccountPermissions()
-console.log('All accounts with circuit permissions:')
-console.dir(allPermissions, { depth: null })
+const accounts = await circuitApi.getAllAccountPermissions()
+console.dir(accounts, { depth: null })
 ```
 
----
+## Example Response
+
+```json
+{
+  "accounts": [
+    {
+      "address": "zig15yk64u7zc9g9k2yr2wmzeva5qgwxps6y8c2amk",
+      "permissions": {
+        "level": "LEVEL_SUPER_ADMIN",
+        "limit_type_urls": []
+      }
+    }
+  ],
+  "pagination": {
+    "next_key": null,
+    "total": "1"
+  }
+}
+```
+
+## Response Field Explanation
 
-## Notes
+### `accounts`
 
-* Useful for **auditing and monitoring** restricted accounts.
-* The `getAllAccountPermissions` method may return large datasets if many accounts are restricted.
+Array of all accounts holding circuit breaker permissions.
 
+Each entry contains:
 
+| Field                       | Description                                                              |
+| --------------------------- | ------------------------------------------------------------------------ |
+| address                     | Bech32 address of the account with circuit permissions                   |
+| permissions.level           | Permission level assigned to this account                                |
+| permissions.limit_type_urls | Message types this account can control. Empty if unrestricted            |
+
+### `pagination`
+
+| Field    | Description                                                          |
+| -------- | -------------------------------------------------------------------- |
+| next_key | Cursor for next page. `null` if all results are returned             |
+| total    | Total number of accounts with circuit permissions on the chain       |
+
+> On ZigChain testnet, `total` is `"1"` — only one super admin account exists. A healthy, normally-operating chain will typically have a very small number of circuit-permissioned accounts.
+
+## When to Use
+
+* Full audit of all accounts with emergency chain intervention authority
+* Verifying the complete set of circuit admins
+* Chain governance and security dashboards
+* Monitoring for unexpected changes to the circuit permission list
+
+---