From 1308e06160b48cd3d5a63e021706b42962988894 Mon Sep 17 00:00:00 2001 From: erhant Date: Tue, 17 Dec 2024 22:44:44 +0300 Subject: [PATCH] update docs and rename functions --- README.md | 36 ++++++++++++++++++++++++++++++++---- examples/view.mjs | 3 ++- package.json | 2 +- src/client.ts | 32 +++++++++++++++++++++++--------- src/index.ts | 4 ++-- 5 files changed, 60 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 0789720..4beec8d 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ await oracle.wait(taskId); When we return from `wait` without any errors, we are sure that the request has been completed. -### Reading Results +### Reading the Best Response To read the best (i.e. highest score) response to a request, we have the `read` function: @@ -145,13 +145,41 @@ const response = await oracle.read(taskId); const { output, metadata } = response; ``` -Internally, this handles t +This function also handles downloading the actual values from Arweave, if the responder nodes have used it to save from gas. Note that you must have passed in the `ArweaveStorage` instance to the `Oracle` constructor for this to work. -TODO: describe parsing +### Reading All sResponses + +If you are interested in reading all generations, you can use: + +```ts +const responses = await oracle.getResponses(taskId); +``` + +This returns you an array of raw responses. You can fetch the actual values from Arweave using the `processResponse` function: + +```ts +for (const responseRaw of responses) { + const response = await oracle.processResponse(responseRaw); + // console.log ... +} +``` ### Reading Validations -TODO: describe validations +If you are interested in reading all validations, you can use: + +```ts +const validations = await oracle.getValidations(taskId); +``` + +This returns you an array of raw responses. You can fetch the actual values from Arweave using the `processResponse` function: + +```ts +for (const validationRaw of validations) { + const validation = await oracle.processValidation(validationRaw); + // console.log ... +} +``` ## Examples diff --git a/examples/view.mjs b/examples/view.mjs index 16b326c..16b921a 100644 --- a/examples/view.mjs +++ b/examples/view.mjs @@ -8,9 +8,10 @@ async function main() { // task id from command line const taskId = BigInt(process.argv[2] ?? 1); + console.log("Viewing task:", taskId); console.log("\nGenerations:"); - const responses = await oracle.readResponses(taskId); + const responses = await oracle.getResponses(taskId); for (const responseRaw of responses) { const response = await oracle.processResponse(responseRaw); console.log( diff --git a/package.json b/package.json index 40211c5..282f10f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "dria-oracle-sdk", - "version": "0.0.8", + "version": "0.0.9", "description": "An on-chain AI oracle SDK for Dria", "license": "MIT", "author": "FirstBatch Team ", diff --git a/src/client.ts b/src/client.ts index 9ed6903..1f88495 100644 --- a/src/client.ts +++ b/src/client.ts @@ -44,7 +44,7 @@ export class Oracle { // defaults public taskParameters: TaskParameters = { difficulty: 2, numGenerations: 2, numValidations: 2 }; - public protocol = "oracle-js-sdk/0.1.0"; + public protocol = "dria-oracle-sdk/0.x.x"; constructor( readonly client: { @@ -83,9 +83,24 @@ export class Oracle { /** * Change the underlying default protocol. + * + * The protocol is a string that should fit a `bytes32` type in Solidity. It is used + * to identify the source of the request, and can be used within event filters. + * + * It should have to format `name/version`, e.g. `dria-oracle-sdk/0.x.x`. * @param protocol protocol name */ withProtocol(protocol: string) { + // ensure `/` appears once + if (protocol.split("/").length !== 2) { + throw new Error("Invalid protocol format."); + } + + // ensure it fits bytes32 + if (Buffer.from(protocol).length > 32) { + throw new Error("Protocol string is too long."); + } + this.protocol = protocol; return this; } @@ -225,8 +240,7 @@ export class Oracle { * @returns true if the task is completed, or `taskId` is 0 */ async isCompleted(taskId: bigint | number): Promise { - // 0 is always accepted - // TODO: explain why + // 0 is always accepted; because `history_id: 0` may be used for chat messages if (BigInt(taskId) === 0n) { return true; } @@ -252,9 +266,9 @@ export class Oracle { } /** - * Reads the request of a task. + * Returns the validations of all generation responses for a task. * @param taskId task id - * @returns task validations + * @returns array of task validations */ async getValidations(taskId: bigint | number): Promise[]> { if (this.coordinator === undefined) { @@ -264,12 +278,11 @@ export class Oracle { } /** - * Read the validations of a task. + * Returns the generation responses for a task. * @param taskId task id - * @param idx index of the response, if not provided, the best & completed response is returned - * @returns task response + * @returns array of task responses */ - async readResponses(taskId: bigint | number): Promise[]> { + async getResponses(taskId: bigint | number): Promise[]> { if (this.coordinator === undefined) { throw new Error("SDK not initialized."); } @@ -306,6 +319,7 @@ export class Oracle { try { return { ...validation, + // here we assume the type like this, because validators are trusted metadata: JSON.parse(metadata) as TaskValidationScores[], }; } catch (err) { diff --git a/src/index.ts b/src/index.ts index e25b14c..c1ad517 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,10 +1,10 @@ -// main +// sdk export { Oracle } from "./client"; export type { OracleModels } from "./types"; // storage export type { DecentralizedStorage } from "./storage"; -export { ArweaveStorage, type ArweaveWallet } from "./storage/arweave"; +export { ArweaveStorage, type ArweaveWallet } from "./storage/"; // utilities export { contractBytesToStringWithStorage, stringToContractBytesWithStorage } from "./utils";