Merge pull request #22 from ora-io/dev

Dev

Author: murongg

.github/ISSUE_TEMPLATE/1-bug-report.yml

@@ -0,0 +1,43 @@
+name: 🐞 Bug report
+description: Report an issue that should be fixed
+labels: [triage]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting a bug report. It helps make our project better.
+
+        Please try to include as much information as possible.
+  - type: input
+    attributes:
+      label: What version of the project are you using?
+      placeholder: 0.0.0
+    validations:
+      required: true
+  - type: dropdown
+    id: package-manager
+    attributes:
+      label: Used Package Manager
+      description: Select the used package manager
+      options:
+        - npm
+        - yarn
+        - pnpm
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What steps can reproduce the bug?
+      description: Explain the bug and provide a code snippet that can reproduce it.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: What is the expected behavior?
+  - type: textarea
+    attributes:
+      label: What do you see instead?
+  - type: textarea
+    attributes:
+      label: Additional information
+      description: Is there anything else you think we should know?

.github/ISSUE_TEMPLATE/2-feature-request.yml

@@ -0,0 +1,32 @@
+name: 🚀 Feature Request
+description: Suggest an idea, feature, or enhancement
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for submitting an idea. It helps make our project better.
+
+  - type: textarea
+    attributes:
+      label: What is the feature you are proposing?
+      description: A clear description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: suggested-solution
+    attributes:
+      label: Suggested solution
+      description: 'In module [xy] we could provide following implementation...'
+    validations:
+      required: true
+  - type: textarea
+    id: alternative
+    attributes:
+      label: Alternative
+      description: Clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional context
+      description: Any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/3-general-questions.yml

@@ -0,0 +1,20 @@
+name: ❓ General Question
+description: Ask any general questions or inquiries
+labels: [question]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reaching out with your question. Please provide as much detail as possible to help us assist you better.
+
+  - type: textarea
+    attributes:
+      label: What is your question?
+      description: Please describe your question or inquiry in detail.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Additional context
+      description: If applicable, provide any additional context or details that might help us understand your question better.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

README.md

@@ -1,3 +1,16 @@
+
+<p align="center">
+  <a href="https://www.ora.io" target="_blank" rel="noopener noreferrer">
+    <img width="180" src="https://raw.githubusercontent.com/ora-io/media-kit/f0595ccc0b2c867614379c009de1fa81db794db5/Logo/logo_type_blue_solid.svg" alt="HyperOracle logo">
+  </a>
+</p>
+<br/>
+<p align="center">
+  <a href="https://npmjs.com/package/@ora-io/orap"><img src="https://img.shields.io/npm/v/@ora-io/orap/latest.svg" alt="npm package"></a>
+  <a href="https://www.npmjs.com/package/@ora-io/orap"><img src="https://img.shields.io/npm/d18m/%40ora-io%2Forap" alt="build status"></a>
+  <a href="https://www.npmjs.com/package/@ora-io/orap"><img src="https://img.shields.io/npm/l/%40ora-io%2Forap" alt="build status"></a>
+</p>
+
 # ORA STACK
 
 ## What is ORA STACK
@@ -13,4 +26,4 @@ Comming soon:
 
 ## Template License
 
-[MIT](./LICENSE) License © 2022 [ORA Protocol](https://ora.io)
+[MIT](./LICENSE) License © 2022 [ORA Protocol](https://ora.io)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ora-stack",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": true,
   "packageManager": "[email protected]",
   "description": "",
@@ -62,6 +62,7 @@
     "@rollup/plugin-node-resolve": "^15.2.3",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.1.0",
+    "@types/prompts": "^2.4.9",
     "bumpp": "^9.4.2",
     "consola": "^3.2.3",
     "dotenv": "^16.4.5",
@@ -70,8 +71,10 @@
     "ethers": "^6.13.2",
     "fast-glob": "^3.3.2",
     "fs-extra": "^11.2.0",
+    "kolorist": "^1.8.0",
     "lint-staged": "^15.2.8",
     "pnpm": "^9.7.0",
+    "prompts": "^2.4.2",
     "rimraf": "^5.0.10",
     "rollup": "^4.20.0",
     "rollup-plugin-dts": "^6.1.1",

packages/orap/README.md

@@ -66,7 +66,8 @@ Note the following already includes using Redis as the store to cache tasks, all
 
 ```ts
 import { ethers } from 'ethers'
-import { Orap, StoreManager } from '@orap-io/orap'
+import type { NextFunction, TaskRaplized } from '@orap-io/orap'
+import { Orap, StoreManager, getMiddlewareContext } from '@orap-io/orap'
 import { Logger, redisStore } from '@ora-io/utils'
 
 // new orap
@@ -76,12 +77,18 @@ const orap = new Orap()
 const store = redisStore()
 const sm = new StoreManager(store)
 
-// use a logger
-const logger = new Logger('info', '[orap-raplize-sample]')
-
-const handle1 = (...args: any) => { logger.log('handle task 1', args); return true }
+// example event: erc20 transfer
+const handle1 = (from: string, to: string, amount: number, event: ContractEventPayload, task: TaskRaplized, next: NextFunction) => {
+  console.log(`handle task 1: from ${from} to ${to} amount ${amount} task ${task}`)
+  next()
+}
 
-const handle2 = (...args: any) => { logger.log('handle task 2', args); return true }
+// when you don't know the specific parameters, you can use `getMiddlewareContext` fn get `next` and `task` object.
+const handle2 = (...args: any[]) => {
+  const { task, next } = getMiddlewareContext(...args)
+  console.log('handle task 2', args, task)
+  next()
+}
 
 // define event signal with crosscheck, and customized cacheable tasks
 // note: use redis as the cache layer
@@ -162,6 +169,7 @@ Each `.task(...)` starts a `Task Flow`
   - ~~`return true` to identify handle success, and entering `onSuccess`~~
   - ~~`return false` to identify handle failed, and entering `onFailed`~~
 - It will automatically detect success and failed and call the `onSuccess` and `onFailed` hooks
+- this fn is essentially a middleware, so it has all the features of middleware
 
 **.cache(sm: StoreManager)**
 - set the store to cache the tasks
@@ -181,6 +189,7 @@ Each `.task(...)` starts a `Task Flow`
 
 **.key(toKey: ToKeyFn)**
 - defines the primary key of a task based on the event values (i.e. log topics)
+- `ToKeyFn` will callback with the event values, and should return a string as the key
 - default: random hex string
 
 **.success(onSuccess: HandleResultFn)**
@@ -198,16 +207,194 @@ Each `.task(...)` starts a `Task Flow`
 - back to the parent `Event Flow`, so that it can add another `.task`
 - e.g. `orap.event(...).task().another().task()`
 
-### Middlewares
+## Middlewares
+
+The middlewares are used in the `Task Flow` to handle the task processing, it's a chain of functions that can be called in order. 
 
-The middlewares are used in the `Task Flow` to handle the task processing, it's a chain of functions that can be called in order.
+You can define `use` to add a middleware to the task flow.  
 
-#### Features
+NOTE: handle is a middleware that can be flexibly placed at any position within the middleware chain, and it will be called in order.
+
+> Middleware is only applicable to task flow, not event flow.
+
+### Features
 
 - the last parameter of the handler is the `next` fn, so you have to call it to continue the next handler.
 - the penultimate parameter is the `TaskRaplized` object, which contains the task info.
 - you can pass parameters to the next handler by calling `next(param1, param2, ...)`, it will be passed to the next handler as arguments, note: you cannot pass `TaskRaplized` object and `next` fn to the next handler, it will pass the next handler with the `TaskRaplized` object and `next` fn automatically.
 
+### Usage
+
+#### create a middleware for check transaction status 
+
+1. create `CheckTransactionStatusMiddleware.js` file
+
+2. define `CheckTransactionStatusMiddleware` function
+
+   ```js
+   // Since it is a general middleware, we don't know the specific parameters of the event, so we need to use rest params.
+   export function CheckTransactionStatusMiddleware(...args) {}
+   ```
+
+3. get middleware context for get `next` fn and `task` object
+
+   ```js
+   // Since it is a general middleware, we don't know the specific parameters of the event, so we need to use rest params.
+   export function CheckTransactionStatusMiddleware(...args) {
+     // get middleware context for get `next` fn and `task` object
+     const { next, task } = getMiddlewareContext(...args)
+   }
+   ```
+
+
+4. write the check transaction status logic,
+
+   since we need to use the provider to check transaction status, we need the user to actively pass in the provider
+
+   ```js
+   // Since it is a general middleware, we don't know the specific parameters of the event, so we need to use rest params.
+   export function CheckTransactionStatusMiddleware(provider) {
+     return (...args) => {
+       // get middleware context for get `next` fn and `task` object
+       const { next, task } = getMiddlewareContext(...args)
+       // get contract event payload
+       const contractEventPayload = args.at(-3) as ContractEventPayload
+       // check transaction status
+       if (contractEventPayload instanceof ContractEventPayload) {
+         const tx = await provider.getTransactionReceipt(contractEventPayload.log.transactionHash)
+         if (!tx || tx?.status === 0) {
+           // it will be caught by the error handler, and terminate the execution of the entire middlewares chain
+           throw new Error('Transaction failed')
+         }
+         await next()
+       }
+       else {
+         // throw error if the contract event payload is invalid, it will be caught by the error handler, and terminate the execution of the entire middlewares chain
+         throw new TypeError('Invalid contract event payload')
+       }
+     }
+   }
+   ```
+
+
+5. use middleware in task flow, take erc20 transfer event as an example
+
+   ```js
+   import { Orap, StoreManager, getMiddlewareContext } from '@ora-io/orap'
+   import ethers from 'ethers'
+   import { CheckTransactionStatusMiddleware } from './CheckTransactionStatusMiddleware.js'
+   
+   const orap = new Orap()
+   
+   const store = redisStore()
+   const sm = new StoreManager(store)
+   
+   const MAINNET_USDT_ADDR = '0xdAC17F958D2ee523a2206206994597C13D831ec7'
+   const TRANSFER_EVENT_NAME = 'Transfer'
+   
+   const eventSignalParam = {
+     address: MAINNET_USDT_ADDR,
+     abi: ['event Transfer(address indexed from, address indexed to, uint256 amount)'],
+     eventName: TRANSFER_EVENT_NAME,
+   }
+   
+   const providers = {
+     wsProvider: new ethers.WebSocketProvider('wss://127.0.0.1'),
+     httpProvider: new ethers.JsonRpcProvider('http://127.0.0.1')
+   }
+   
+   orap.event(eventSignalParam)
+     // add a task
+     .task()
+     .cache(sm)
+     .prefix('ora-stack:orap:demo:TransferTask:', 'ora-stack:orap:demo:Done-TransferTask:')
+     .ttl({ taskTtl: 120000, doneTtl: 60000 })
+     .use(CheckTransactionStatus(providers.wsProvider))
+     .handle(handleTask)
+   
+   // start signal listener
+   orap.listen(
+     providers,
+     () => { logger.log('listening on provider.network') },
+   )
+   
+   async function handleTask(from, to, amount, event, task, next) {
+     logger.log('[+] handleTask: from =', from, 'to =', to, 'amount =', amount)
+     // do something ...
+     await next()
+   }
+   
+   ```
+
+### Execution order
+
+The middleware will be executed in the order you define it.
+
+```js
+import { Orap, StoreManager, getMiddlewareContext } from '@ora-io/orap'
+import ethers from 'ethers'
+
+const orap = new Orap()
+
+const store = redisStore()
+const sm = new StoreManager(store)
+
+const MAINNET_USDT_ADDR = '0xdAC17F958D2ee523a2206206994597C13D831ec7'
+const TRANSFER_EVENT_NAME = 'Transfer'
+
+const eventSignalParam = {
+  address: MAINNET_USDT_ADDR,
+  abi: ['event Transfer(address indexed from, address indexed to, uint256 amount)'],
+  eventName: TRANSFER_EVENT_NAME,
+}
+
+const providers = {
+  wsProvider: new ethers.WebSocketProvider('wss://127.0.0.1'),
+  httpProvider: new ethers.JsonRpcProvider('http://127.0.0.1')
+}
+
+orap.event(eventSignalParam)
+// add a task
+  .task()
+  .cache(sm)
+  .prefix('ora-stack:orap:demo:TransferTask:', 'ora-stack:orap:demo:Done-TransferTask:')
+  .ttl({ taskTtl: 120000, doneTtl: 60000 })
+  .use(async (...args) => {
+    const { next } = getMiddlewareContext(...args)
+    console.log(1)
+    await next()
+  })
+  .handle(handleTask)
+  .use(async (...args) => {
+    const { next } = getMiddlewareContext(...args)
+    console.log(3)
+    await next()
+  })
+  .use(async (...args) => {
+    const { next } = getMiddlewareContext(...args)
+    console.log(4)
+  })
+  .use(async (...args) => {
+    const { next } = getMiddlewareContext(...args)
+    console.log(5)
+  })
+// start signal listener
+orap.listen(
+  providers,
+  () => { logger.log('listening on provider.network') },
+)
+
+async function handleTask(from, to, amount, event, task, next) {
+  console.log(2)
+  // do something ...
+  await next()
+}
+```
+
+```bash
+output: 1 2 3 4
+```
+Since 4th middleware does not call `next`, 5th middleware will not be executed
 
 ### OO Style (Basic)