Skip to content

Prometheus: Add README for tools #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HermanKoii wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Prometheus: Add README for tools #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 97 additions & 86 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,101 +1,112 @@
# Koii JavaScript SDK
# @_koii/sdk - Koii Network SDK

The Koii.js library enables node.js and javascript/typescript applications to easily interact with the open Koi network.
## Project Overview

## Steps to Interact with the SDK in your Project
The @_koii/sdk is a comprehensive TypeScript library that provides developers with powerful tools and utilities for interacting with the Koii Network. This SDK simplifies blockchain development by offering cross-platform support, robust state management, and seamless integration with multiple blockchain technologies.

1. Add the sdk to your project
### Key Features
- 🌐 Multi-Blockchain Support: Works with Ethereum, Solana, and Koii networks
- 🔒 Secure Wallet and Key Management
- 🚀 Easy Contract State Retrieval
- 💾 Redis Integration for Caching and Data Storage
- 🔍 Advanced State Querying Capabilities
- 🧩 Flexible and Extensible Architecture

You can use either npm or yarn
## Installation

```
npm i @_koii/sdk
yarn add @_koii/sdk
```
Install the SDK using npm:

2. Add the Koi-tools module to your script and then initialize the koi class.

```
import * as kweb from "@_koii/sdk/web.js";
const tools = new kweb.Web();
```

or with CommonJS

```
const kweb = require("@_koii/sdk/web");
const tools = new kweb.Web();
```

or using the bundle

```
<script src="koi_tools.js"></script>
...
const kweb = koi_tools.koi_web;
const tools = new kweb.Web();
```

Note: This library changes often, so if `npm i @_koii/sdk` does not work, check for beta releases on NPM under the versions section or manually build the package (See [#Build](#Build) section below).

3. Optional - Add the Arweave module to your project if your app plans to directly transact with the permaweb outside of using the Koi-tools library

```
const Arweave = require("arweave");
const arweave = Arweave.init({
host: "arweave.net",
port: 443,
protocol: "https"
});
```

4. Create an RSA Wallet Key

Note that the wallet address should not be held inside of your project when you check the project into GitHub

```
var walletKeyLocation = "path/to/wallet.json";
```


5. Define a function to bootstrap your app and utilize the koi-tools `loadWallet`.

```
async function main() {
const jwk = await tools.loadFile(walletPath);
await tools.loadWallet(jwk);

}

main();
```

If you are just testing with a local bundler, you can also use `await tools.generateWallet()` to create a custom key file just for that runtime.
```bash
npm install @_koii/sdk
```

6. Check out the test folder for examples of how to interact with koi-tools.
### Prerequisites
- Node.js (v14.0.0 or later)
- TypeScript (optional, but recommended)

## Build
## API Reference

### NPM
### Node Class

#### Constructor
```typescript
const node = new Node(options?: NodeOptions)
```
yarn install
yarn build
yarn publish dist
```

For beta releases

- append `-beta.N` to `dist/package.json` version where N is the beta version
- use `yarn publish dist --tag beta`

Test with `yarn test`
#### Methods

##### State Management
- `getState(txId: string)`: Retrieve contract state with intelligent caching
```typescript
const state = await node.getState('contractTxId')
```

- `getStateAwait(txId: string)`: Force retrieve latest contract state
```typescript
const freshState = await node.getStateAwait('contractTxId')
```

##### File and Wallet Management
- `loadFile(filePath: string)`: Load JSON file asynchronously
```typescript
const walletData = await node.loadFile('/path/to/wallet.json')
```

##### Redis Integration
- `loadRedisClient(config?: RedisConfig)`: Initialize Redis connection
```typescript
node.loadRedisClient({
redis_ip: 'localhost',
redis_port: 6379,
redis_password: 'optional_password'
})
```

- `redisSetAsync(key: string, value: string)`: Store data in Redis
- `redisGetAsync(key: string)`: Retrieve data from Redis
- `redisDelAsync(key: string)`: Delete Redis key

### Web Class
(Refer to source code for detailed Web class methods)

### Constants
- `URL_GATEWAY_LOGS`: Gateway logs URL for Koii Network

## Repository Structure
- `src/`: TypeScript source files
- `common.ts`: Common utilities and base classes
- `node.ts`: Node-specific implementations
- `web.ts`: Web-specific implementations
- `ethereum.ts`: Ethereum blockchain interactions
- `solana.ts`: Solana blockchain interactions
- `test/`: Unit and integration tests
- `docs/`: Documentation files

## Configuration

### Environment Variables
- `NODE_MODE`: Set to "service" for enhanced caching
- `REDIS_IP`: Redis server IP
- `REDIS_PORT`: Redis server port
- `REDIS_PASSWORD`: Redis authentication password

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

### Running Tests
```bash
npm test
```

### Webpack
## License
Distributed under the ISC License. See `LICENSE` file for more information.

```
yarn install
yarn bundle
```
## Contact
Koii Network - [Official Website](https://www.koii.network)

Test with `yarn test-bundle`
Project Link: [https://github.com/koii-network/tools](https://github.com/koii-network/tools)