Add examples and docs (#7)

* update: add example and docs guide * chore: generalize the docs using oraichain common * chore: update README * chore: add image to readme * chore: update license --------- Co-authored-by: ducphamle2 <[email protected]>
oraichain · Aug 1, 2024 · c912204 · c912204
1 parent f1b196e
commit c912204
Show file tree

Hide file tree

Showing 8 changed files with 1,459 additions and 213 deletions.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,11 +1,71 @@
 # Cosmos-sync
 
-Synchronize Cosmos-based transactions based on a set of query tags using Tendermint RPC
+<p align="center" width="100%">
+    <img height="90" src="https://user-images.githubusercontent.com/545047/190171475-b416f99e-2831-4786-9ba3-a7ff4d95b0d3.svg" />
+</p>
+<p align="center" width="100%">
+   <a href="https://github.com/oraichain/cosmos-sync/blob/master/LICENSE"><img height="20" src="https://img.shields.io/badge/License-GNU%20GPL-blue.svg"></a>
+</p>
 
-# Build and publish
+:information_desk_person: This repository provides an SDK designed to streamline the synchronization of Cosmos-based transactions using Tendermint RPC. It facilitates this process by leveraging a set of query tags.
 
+## 📦 Packages
+
+| Name                                                                                        | Version                                  | Description                              |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------------ |
+| [@oraichain/cosmos-rpc-sync](https://github.com/oraichain/cosmos-sync/tree/master/packages/rpc-sync) | <a href="https://www.npmjs.com/package/@oraichain/common"><img height="20" src="https://img.shields.io/github/package-json/v/oraichain/cosmos-sync?filename=packages%2Frpc-sync%2Fpackage.json"></a> |  Synchronize transaction using rpc. |
+| [@oraichain/cosmos-lcd-sync](https://github.com/oraichain/cosmos-sync/tree/master/packages/lcd-sync) | <a href="https://www.npmjs.com/package/@oraichain/common"><img height="20" src="https://img.shields.io/github/package-json/v/oraichain/cosmos-sync?filename=packages%2Flcd-sync%2Fpackage.json"></a> | Synchronize transaction using lcd. |
+
+## Installation
+The npm package for the Oraichain [Cosmos-sync SDK](https://github.com/oraichain/cosmos-sync)
+
+```bash
+yarn add @oraichain/cosmos-rpc-sync
+yarn add @oraichain/cosmos-lcd-sync
+```
+
+## Quick start
+Please refer to [examples](./packages//examples/README.md) to get start with our SDK.
+
+## 🛠 Developing
+
+Checkout the repository and bootstrap the yarn workspace:
+
+```bash
+# Clone the repo.
+git clone https://github.com/oraichain/cosmos-sync.git
+cd cosmos-sync
+yarn
+```
+
+### Testing
+```bash
+# Run all tests
+yarn test
+```
+
+### Building
 ```sh
 yarn build packages/rpc-sync
+yarn build packages/lcd-sync
+```
 
+### Publishing
+```bash
 yarn deploy packages/rpc-sync
-```
+yarn deploy packages/lcd-sync
+```
+
+## Credits
+
+🛠 Built by Oraichain Labs — if you like our tools, please consider delegating to [OWallet validators ⚛️](https://owallet.dev/validators)
+
+## 🪪 License
+
+All packages are [GPL 3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) licensed.
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.
diff --git a/package.json b/package.json
@@ -11,6 +11,7 @@
     "deploy": "yarn publish --access public"
   },
   "devDependencies": {
+    "@keplr-wallet/types": "^0.12.118",
     "@types/jest": "^29.5.12",
     "@types/node": "^18.15.8",
     "jest": "^29.7.0",
@@ -21,8 +22,8 @@
     "typescript": "^4.8.3"
   },
   "dependencies": {
-    "@cosmjs/tendermint-rpc": "0.31.3",
     "@cosmjs/stargate": "0.31.3",
+    "@cosmjs/tendermint-rpc": "0.31.3",
     "cosmjs-types": "0.9.0"
   },
   "packageManager": "[email protected]+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"

diff --git a/packages/examples/README.md b/packages/examples/README.md
@@ -0,0 +1,107 @@
+# Cosmos-sync Examples
+
+| A collection of examples on how to interact with the Oraichain network using Cosmos-sync SDK. |
+| --------------------------------------------------------------------------------------------- |
+
+## Basic listening for transactions of smart contract
+
+```ts
+import { SyncData } from '@oraichain/cosmos-rpc-sync';
+import { COSMOS_CHAIN_IDS, ORAI_TOKEN_CONTRACTS, OraiCommon } from '@oraichain/common';
+import { StargateClient } from '@cosmjs/stargate';
+
+const LIMIT = 4000;
+
+const genQueryTagContract = (contractAddress: string) => {
+  return [
+    {
+      key: 'wasm._contract_address',
+      value: contractAddress
+    }
+  ];
+};
+
+const main = async () => {
+  const common = await OraiCommon.initializeFromGitRaw({ chainIds: [COSMOS_CHAIN_IDS.ORAICHAIN] });
+  const rpc = common.chainInfos.cosmosChains.find((chain) => chain.chainId === COSMOS_CHAIN_IDS.ORAICHAIN).rpc;
+  const client = await StargateClient.connect(rpc);
+  const latestBlock = await client.getHeight();
+  // const latestBlock =
+  const syncData = new SyncData({
+    queryTags: genQueryTagContract(ORAI_TOKEN_CONTRACTS.USDC),
+    rpcUrl: rpc,
+    offset: latestBlock,
+    interval: 1000,
+    limit: LIMIT
+  });
+
+  await syncData.start();
+
+  syncData.on('data', (data) => {
+    console.log('data: ', data);
+  });
+};
+
+main();
+```
+
+Here you can listen for transaction of a smart contract by using cosmos-sync.
+
+At this example, we are going to listen for transactions of CW20 USDC smart contract. The key here is what `queryTags` you defined to query blockchain states and `params` you pass to initiate `SyncData` instance.
+
+We define `queryTags` with key is `wasm._contract_address` and value is USDC contract address. Other `params` for initiating `SyncData` are:
+```ts
+/**
+ * @rpcUrl: rpc url to query blockchain states
+ * @offset: block height that start to query
+ * @limit: total blocks to query states at one time
+ * @interval: time interval to query
+ * @timeoutSleep: time sleep to reduce rpc traffic load
+ * @maxThreadLevel: thread level to query parallel
+ */
+```
+
+The results will be handled by listen to event `data`, here we just basically log it out.
+
+## Basic listening for transactions of an address
+
+```ts
+
+import { SyncData } from '@oraichain/cosmos-rpc-sync';
+import { COSMOS_CHAIN_IDS, ORAI_TOKEN_CONTRACTS, OraiCommon } from '@oraichain/common';
+import { StargateClient } from '@cosmjs/stargate';
+
+const LIMIT = 4000;
+
+const main = async () => {
+  const common = await OraiCommon.initializeFromGitRaw({ chainIds: [COSMOS_CHAIN_IDS.ORAICHAIN] });
+  const rpc = common.chainInfos.cosmosChains.find((chain) => chain.chainId === COSMOS_CHAIN_IDS.ORAICHAIN).rpc;
+  const client = await StargateClient.connect(rpc);
+  const latestBlock = await client.getHeight();
+  // const latestBlock =
+  const syncData = new SyncData({
+    queryTags: queryTags: [
+      {
+        key: 'message.sender',
+        value: "orai1lwuqpj9teef8j0rjy2l4c5ay9yddw26m03tlem"
+      }
+    ],
+    rpcUrl: rpc,
+    offset: latestBlock,
+    interval: 1000,
+    limit: LIMIT
+  });
+
+  await syncData.start();
+
+  syncData.on('data', (data) => {
+    console.log('data: ', data);
+  });
+};
+
+main();
+```
+
+Here we listen for transactions that executed by an address.
+
+At this example, we define queryTags that key is `message.sender` and value is an address. The results is still just logged out.
diff --git a/packages/examples/package.json b/packages/examples/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@oraichain/cosmos-sync-examples",
+  "version": "1.0.0",
+  "main": "build/index.js",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "files": [
+    "build/"
+  ],
+  "dependencies": {
+    "@oraichain/common": "^1.0.3",
+    "@oraichain/cosmos-rpc-sync": "^1.0.11"
+  }
+}
diff --git a/packages/examples/src/rpc-sync/txListen.ts b/packages/examples/src/rpc-sync/txListen.ts
@@ -0,0 +1,46 @@
+import { SyncData } from '@oraichain/cosmos-rpc-sync';
+import { COSMOS_CHAIN_IDS, ORAI_TOKEN_CONTRACTS, OraiCommon } from '@oraichain/common';
+import { StargateClient } from '@cosmjs/stargate';
+
+const LIMIT = 4000;
+
+const genQueryTagContract = (contractAddress: string) => {
+  return [
+    {
+      key: 'wasm._contract_address',
+      value: contractAddress
+    }
+  ];
+};
+
+const genQueryTagAddress = (address: string) => {
+  return [
+    {
+      key: 'message.sender',
+      value: address
+    }
+  ];
+};
+
+const main = async () => {
+  const common = await OraiCommon.initializeFromGitRaw({ chainIds: [COSMOS_CHAIN_IDS.ORAICHAIN] });
+  const rpc = common.chainInfos.cosmosChains.find((chain) => chain.chainId === COSMOS_CHAIN_IDS.ORAICHAIN).rpc;
+  const client = await StargateClient.connect(rpc);
+  const latestBlock = await client.getHeight();
+  // const latestBlock =
+  const syncData = new SyncData({
+    queryTags: genQueryTagContract(ORAI_TOKEN_CONTRACTS.USDC),
+    rpcUrl: rpc,
+    offset: latestBlock,
+    interval: 1000,
+    limit: 10
+  });
+
+  await syncData.start();
+
+  syncData.on('data', (data) => {
+    console.log('data: ', data);
+  });
+};
+
+main();
diff --git a/packages/examples/tsconfig.json b/packages/examples/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "outDir": "build",
+    "declaration": true,
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules/"]
+}