@zuhaibnoor/zigchain-sdk 1.0.3 → 1.1.1

package/docs/txs.md

@@ -0,0 +1,447 @@
+# Transactions (TXs) Module
+
+## What is the TXs Module?
+
+The **TXs (Transactions) module** allows you to search, filter, and retrieve transactions on the ZigChain blockchain using Tendermint query syntax.
+
+This module helps you:
+
+* Find transactions by various criteria (sender, receiver, events, etc.)
+* Query transaction history
+* Build transaction explorers and analytics tools
+* Track on-chain activity
+
+---
+
+# Important Terminology
+
+Before documenting functions, let's define key terms.
+
+### Transaction (TX)
+
+A transaction is an action recorded on the blockchain that modifies state.
+
+Examples:
+* Sending coins
+* Deploying a smart contract
+* Voting on governance proposals
+* Staking tokens
+
+### Transaction Hash
+
+A unique identifier for a transaction, computed from its contents.
+
+Example:
+```
+txhash = ABC123DEF456...
+```
+
+---
+
+### Events
+
+Transactions emit **events** that record what happened during execution.
+
+Events have:
+* A **type** (e.g., `coin_sent`, `transfer`, `message`)
+* **attributes** (key-value pairs describing the event)
+
+Example event:
+```json
+{
+  "type": "transfer",
+  "attributes": [
+    { "key": "sender", "value": "zig1..." },
+    { "key": "recipient", "value": "zig1..." },
+    { "key": "amount", "value": "100uzig" }
+  ]
+}
+```
+
+---
+
+### Tendermint Query Syntax
+
+You search transactions using **Tendermint query syntax**, a special format for filtering by events.
+
+Basic syntax:
+```
+<key>=<value>
+```
+
+Operators:
+* `=` → Equals
+* `!=` → Not equals
+* `<`, `<=`, `>`, `>=` → Comparison
+* `AND`, `OR` → Logical operators
+
+Examples:
+```
+message.sender='zig1...'
+transfer.recipient='zig1...'
+transfer.amount='100uzig'
+coin_spent.spender='zig1...' AND coin_spent.amount='50uzig'
+```
+
+---
+
+# Functions Documentation
+
+Setup:
+```ts
+import {
+  ChainTxsApi,
+  getNetworkEndpoints,
+  Network
+} from '@zuhaibnoor/zigchain-sdk'
+
+const endpoints = getNetworkEndpoints(Network.Testnet)
+const txsApi = new ChainTxsApi(endpoints)
+```
+
+---
+
+# 1️⃣ searchTxs
+
+## Method
+
+```ts
+async searchTxs(events: string): Promise<TxsSearchResponse>
+```
+
+## CLI Equivalent
+
+```bash
+zigchaind query txs --events "<query>"
+```
+
+## Description
+
+Searches for transactions on the blockchain using query syntax.
+
+This returns:
+
+* Transaction metadata (hash, height, timestamp)
+* Messages contained in the transaction
+* Events emitted during execution
+* Gas usage
+
+This is the primary way to query transaction history.
+
+## Parameters
+
+| Name   | Type   | Description                                              |
+| ------ | ------ | -------------------------------------------------------- |
+| events | string | Tendermint query syntax filter (e.g., `message.sender=...`) |
+
+
+## Usage Example
+
+### Query by Sender
+
+```ts
+const result = await txsApi.searchTxs(
+  "message.sender='zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn'"
+)
+console.dir(result, { depth: null })
+```
+
+### Query by Recipient
+
+```ts
+const result = await txsApi.searchTxs(
+  "transfer.recipient='zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn'"
+)
+```
+
+### Query by Multiple Conditions
+
+```ts
+const result = await txsApi.searchTxs(
+  "message.sender='zig1...' AND transfer.amount='100uzig'"
+)
+```
+
+### Query by Event Type
+
+```ts
+const result = await txsApi.searchTxs(
+  "coin_received.receiver='zig1...'"
+)
+```
+
+## Example Response
+
+```json
+{
+  "tx": [
+    {
+      "body": {
+        "messages": [
+          {
+            "@type": "/cosmos.bank.v1beta1.MsgSend",
+            "from_address": "zig1qmy242fasznk3q5mvqzew0af9c6xz2zf09zrau",
+            "to_address": "zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn",
+            "amount": [
+              {
+                "denom": "coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                "amount": "279"
+              }
+            ]
+          }
+        ],
+        "memo": "",
+        "timeout_height": "0",
+        "extension_options": [],
+        "non_critical_extension_options": []
+      },
+      "auth_info": {
+        "signer_infos": [
+          {
+            "public_key": {
+              "@type": "/cosmos.crypto.secp256k1.PubKey",
+              "key": "..."
+            },
+            "mode_info": {
+              "single": { "mode": "SIGN_MODE_DIRECT" }
+            },
+            "sequence": "42"
+          }
+        ],
+        "fee": {
+          "amount": [
+            {
+              "denom": "uzig",
+              "amount": "5000"
+            }
+          ],
+          "gas_limit": "200000",
+          "payer": "",
+          "granter": ""
+        }
+      },
+      "signatures": ["..."]
+    }
+  ],
+  "tx_responses": [
+    {
+      "height": "1234567",
+      "txhash": "ABC123DEF456...",
+      "codespace": "",
+      "code": 0,
+      "data": "...",
+      "raw_log": "[...]",
+      "logs": [
+        {
+          "msg_index": 0,
+          "log": "",
+          "events": [
+            {
+              "type": "coin_received",
+              "attributes": [
+                {
+                  "key": "receiver",
+                  "value": "zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn",
+                  "index": true
+                },
+                {
+                  "key": "amount",
+                  "value": "279coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "msg_index",
+                  "value": "0",
+                  "index": true
+                }
+              ]
+            },
+            {
+              "type": "transfer",
+              "attributes": [
+                {
+                  "key": "recipient",
+                  "value": "zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn",
+                  "index": true
+                },
+                {
+                  "key": "sender",
+                  "value": "zig1qmy242fasznk3q5mvqzew0af9c6xz2zf09zrau",
+                  "index": true
+                },
+                {
+                  "key": "amount",
+                  "value": "279coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "msg_index",
+                  "value": "0",
+                  "index": true
+                }
+              ]
+            },
+            {
+              "type": "denom_minted_and_sent",
+              "attributes": [
+                {
+                  "key": "module",
+                  "value": "factory",
+                  "index": true
+                },
+                {
+                  "key": "denom",
+                  "value": "coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "denom_minted_and_sent",
+                  "value": "279coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "recipient",
+                  "value": "zig13f3cekcjlzw8trgpxlvedr76crs5gp4rpp74dn",
+                  "index": true
+                },
+                {
+                  "key": "total_minted",
+                  "value": "4113793175725coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "total_supply",
+                  "value": "811405700669coin.zig15jqg0hmp9n06q0as7uk3x9xkwr9k3r7yh4ww2uc0hek8zlryrgmsamk4qg.oroswaplptoken",
+                  "index": true
+                },
+                {
+                  "key": "msg_index",
+                  "value": "0",
+                  "index": true
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "info": "",
+      "gas_wanted": "200000",
+      "gas_used": "125000",
+      "tx": {
+        "@type": "/cosmos.tx.v1beta1.Tx",
+        "body": { "..." },
+        "auth_info": { "..." },
+        "signatures": ["..."]
+      },
+      "timestamp": "2024-01-15T10:30:45Z"
+    }
+  ],
+  "pagination": {
+    "next_key": "...",
+    "total": "115337"
+  }
+}
+```
+
+## Response Field Explanation
+
+### `tx`
+
+Array of full transaction objects.
+
+Each transaction contains:
+
+| Field       | Description                                  |
+| ----------- | -------------------------------------------- |
+| body        | Transaction body with messages and memo      |
+| auth_info   | Signer information and fees                  |
+| signatures  | Digital signatures proving transaction validity |
+
+### `tx_responses`
+
+Metadata and results for each transaction.
+
+| Field         | Description                                  |
+| ------------- | -------------------------------------------- |
+| height        | Block number containing the transaction      |
+| txhash        | Unique transaction identifier                |
+| code          | Execution code (0 = success)                 |
+| gas_wanted    | Gas requested for execution                  |
+| gas_used      | Actual gas consumed                          |
+| logs          | Detailed event logs from execution           |
+| timestamp     | When the transaction was included in a block |
+
+### `logs` (Event Details)
+
+Each log entry contains events emitted during message execution.
+
+| Field      | Description                      |
+| ---------- | -------------------------------- |
+| msg_index  | Index of the message in the TX   |
+| events     | Array of events emitted          |
+
+### `events` (What Happened)
+
+Each event describes something that occurred.
+
+| Field      | Description                          |
+| ---------- | ------------------------------------ |
+| type       | Event type (e.g., `transfer`)        |
+| attributes | Key-value pairs describing the event |
+
+### Common Event Types
+
+| Event Type                | Meaning                                 |
+| ------------------------- | --------------------------------------- |
+| `message`                 | Message dispatch metadata               |
+| `transfer`                | Token transfer occurred                 |
+| `coin_received`           | Recipient received coins                |
+| `coin_spent`              | Spender spent coins                     |
+| `execute`                 | Smart contract executed                 |
+| `coin_minted_and_sent`    | Token factory minting                   |
+| `instantiate`             | Contract instantiated                   |
+| `migrate`                 | Contract migrated                       |
+
+### `pagination`
+
+Pagination information for large result sets.
+
+| Field    | Description                                    |
+| -------- | ---------------------------------------------- |
+| next_key | Cursor for fetching next page (if available)   |
+| total    | Total number of matching transactions          |
+
+---
+
+## Tendermint Query Syntax Reference
+
+### Basic Queries
+
+```ts
+// By sender
+"message.sender='zig1...'"
+
+// By recipient
+"transfer.recipient='zig1...'"
+
+// By amount
+"transfer.amount='100uzig'"
+```
+
+
+### Common Searchable Fields
+
+| Field                  | Example                                   |
+| ---------------------- | ----------------------------------------- |
+| `message.sender`       | `message.sender='zig1...'`                |
+| `message.action`       | `message.action='/cosmos.bank.v1beta1.MsgSend'` |
+| `transfer.sender`      | `transfer.sender='zig1...'`               |
+| `transfer.recipient`   | `transfer.recipient='zig1...'`            |
+| `transfer.amount`      | `transfer.amount='100uzig'`               |
+| `coin_received.receiver` | `coin_received.receiver='zig1...'`      |
+| `coin_spent.spender`   | `coin_spent.spender='zig1...'`            |
+| `execute._contract_address` | `execute._contract_address='zig1...'` |
+
+---
+
+