fix type export error, rfk functions, add docs

Author: erhant

README.md

@@ -230,6 +230,19 @@ for (const validationRaw of validations) {
 }
 ```
 
+### Reading Task Events
+
+If you want to fetch `taskId`s for a given protocol, you can filter contract events with:
+
+```ts
+const events = await oracle.getTaskEvents({
+  protocol: stringToBytes32("my-protocol/0.1.0"),
+  status: TaskStatus.Completed,
+});
+```
+
+You can then use other functions with the returned `taskId`s.
+
 ## Examples
 
 We have several examples that demonstrate making a request, following it up with another request, and view an existing request!
@@ -312,4 +325,4 @@ pnpm test
 
 ## License
 
-We are using MIT license.
+We are using [MIT](./LICENSE) license.

package.json

@@ -1,13 +1,20 @@
 {
   "name": "dria-oracle-sdk",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "An on-chain LLM Oracle SDK for Dria",
   "license": "MIT",
   "author": "FirstBatch Team <[email protected]>",
   "homepage": "https://github.com/firstbatchxyz/dria-oracle-sdk#readme",
   "contributors": [
     "Erhan Tezcan <[email protected]> (https://github.com/erhant)"
   ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "start": "pnpm build && node dist/index.cjs",
+    "lint": "eslint '**/*.ts'",
+    "build": "pkgroll",
+    "test": "NODE_ENV=test jest "
+  },
   "files": [
     "dist/",
     "LICENSE",
@@ -45,13 +52,6 @@
   "peerDependencies": {
     "@irys/sdk": "^0.2.11"
   },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "start": "pnpm build && node dist/index.cjs",
-    "lint": "eslint '**/*.ts'",
-    "build": "pkgroll",
-    "test": "NODE_ENV=test jest"
-  },
   "prettier": {
     "printWidth": 120
   },
@@ -63,5 +63,6 @@
     "arweave",
     "llm",
     "ai"
-  ]
+  ],
+  "packageManager": "[email protected]+sha512.b2dc20e2fc72b3e18848459b37359a32064663e5627a51e4c74b2c29dd8e8e0491483c3abb40789cfd578bf362fb6ba8261b05f0387d76792ed6e23ea3b1b6a0"
 }

src/client.ts

@@ -4,7 +4,7 @@ import type { DecentralizedStorage } from "./storage";
 import type {
   ChatHistoryRequest,
   ChatHistoryResponse,
-  OracleModels,
+  Models,
   TaskRequestOptions,
   NewRequestReturnType,
   TaskParameters,
@@ -50,7 +50,7 @@ export class Oracle<T extends Transport, C extends Chain, K = unknown> {
 
   // defaults
   public taskParameters: TaskParameters = { difficulty: 2, numGenerations: 2, numValidations: 2 };
-  public protocol = "dria-oracle-sdk/0.x.x";
+  public protocol = "dria-oracle-sdk/0.0.x";
 
   constructor(
     readonly client: {
@@ -158,15 +158,15 @@ export class Oracle<T extends Transport, C extends Chain, K = unknown> {
    * @param opts optional request arguments, such as `protocol` and `taskParameters`
    * @returns task transaction hash
    */
-  async request(input: string, models: OracleModels, opts?: TaskRequestOptions): Promise<NewRequestReturnType>;
+  async request(input: string, models: Models, opts?: TaskRequestOptions): Promise<NewRequestReturnType>;
   async request(
     input: Prettify<ChatHistoryRequest>,
-    models: OracleModels,
+    models: Models,
     opts?: TaskRequestOptions
   ): Promise<NewRequestReturnType>;
   async request(
     input: string | Prettify<ChatHistoryRequest>,
-    models: OracleModels = "*",
+    models: Models = "*",
     opts: TaskRequestOptions = {}
   ): Promise<NewRequestReturnType> {
     if (this.coordinator === undefined) {
@@ -255,9 +255,9 @@ export class Oracle<T extends Transport, C extends Chain, K = unknown> {
   }
 
   /**
-   *
+   * Returns the task request for a given task id.
    * @param taskId task id
-   * @returns test request
+   * @returns task request
    */
   async getRequest(taskId: bigint | number): Promise<TaskRequest> {
     if (this.coordinator === undefined) {
@@ -361,16 +361,23 @@ export class Oracle<T extends Transport, C extends Chain, K = unknown> {
   }
 
   /**
-   * Fetches the events from the coordinator contract.
+   * Fetches the task events from the coordinator contract and returns its args.
+   * A returned task event has the taskId, protocol, statusBefore, and statusAfter.
+   * For a completed task, we are looking for the statusAfter to be `Completed` which is `3`.
    *
    * @param opts options for fetching tasks
    * - `protocol`: protocol name
    * - `from`: block to start from
    * - `to`: block to end at
-   *
-   * @returns array of events, you can read the topic values for `i`th event with `events[i].args`
+   * - `status`: task status to filter by
+   * @returns array of task events
    */
-  async getEvents(opts: { protocol?: string; from?: bigint | BlockTag; to?: bigint | BlockTag }) {
+  async getTaskEvents(opts: {
+    protocol?: string;
+    from?: bigint | BlockTag;
+    to?: bigint | BlockTag;
+    status?: TaskStatus;
+  }) {
     if (this.coordinator === undefined) {
       throw new Error("SDK not initialized.");
     }
@@ -381,7 +388,13 @@ export class Oracle<T extends Transport, C extends Chain, K = unknown> {
     const toBlock = opts.to ?? "latest";
 
     const events = await this.coordinator!.getEvents.StatusUpdate({ protocol }, { fromBlock, toBlock });
-    return events;
+    const taskEvents = events.map((event) => event.args);
+
+    if (opts.status) {
+      return taskEvents.filter((e) => e.statusAfter === opts.status);
+    } else {
+      return taskEvents;
+    }
   }
 
   /**

src/index.ts

@@ -1,10 +1,11 @@
 // sdk
 export { Oracle } from "./client";
-export type { OracleModels } from "./types";
+export type { Models as OracleModels } from "./types";
 
 // storage
 export type { DecentralizedStorage } from "./storage";
 export { ArweaveStorage, type ArweaveWallet } from "./storage/";
 
 // utilities
 export { contractBytesToStringWithStorage, stringToContractBytesWithStorage } from "./utils";
+export { TaskStatus } from "./types";

src/types/index.ts

@@ -1,3 +1,15 @@
-export * from "./model";
 export * from "./request";
 export * from "./task";
+
+/**
+ * Allowed Oracle models.
+ *
+ * The requested model(s) can be any of the following:
+ *
+ * - An array of model names, such as `["gemini-1.5-pro", "gpt-4o-mini"]`.
+ * - `*` for any model randomly (of the responder).
+ * - `!` for the first model (of the responder).
+ *
+ * You can look at the available models from [this repository](https://github.com/andthattoo/ollama-workflows/blob/main/src/program/models.rs#L14).
+ */
+export type Models = string[] | "*" | "!";

src/types/model.ts

@@ -1,5 +1,5 @@
 import type { Hex } from "viem";
-import type { OracleModels } from "./model";
+import type { Models } from "./";
 import type { TaskParameters, TaskStatus } from "./task";
 
 /** A chat history entry. */
@@ -23,7 +23,7 @@ export type NewRequestReturnType = {
   txHash: Hex;
   protocol: string;
   input: string;
-  models: OracleModels;
+  models: Models;
   taskParameters: TaskParameters;
 };
 

src/types/request.ts

@@ -36,11 +36,11 @@ describe("events", () => {
     const [from, to] = [24660077n, 24670077n]; // 10k blocks
 
     // there are 14 tasks specifically for the purchase requests
-    const purchaseTasks = await oracle.getEvents({ protocol: "swan-agent-purchase/0.1.0", from, to });
+    const purchaseTasks = await oracle.getTaskEvents({ protocol: "swan-agent-purchase/0.1.0", from, to });
     expect(purchaseTasks.length).toBe(2);
 
     // there are 84 tasks specifically for the state updates
-    const stateTasks = await oracle.getEvents({ protocol: "swan-agent-state/0.1.0", from, to });
+    const stateTasks = await oracle.getTaskEvents({ protocol: "swan-agent-state/0.1.0", from, to });
     expect(stateTasks.length).toBe(19);
   });
 });

tests/events.test.ts

@@ -7,7 +7,7 @@ import { baseSepolia } from "viem/chains";
 import { TaskStatus } from "../src/types";
 
 // this test uses the live testnet, NOT a forked local node!
-describe("oracle", () => {
+describe.skip("oracle", () => {
   let oracle: Oracle<HttpTransport, typeof baseSepolia>;
   let requestTxHash: Hex;