Feat/dynamic context validation in sdk

kleros-sdk/package.json

@@ -35,6 +35,7 @@
   "dependencies": {
     "@kleros/kleros-v2-contracts": "workspace:^",
     "@reality.eth/reality-eth-lib": "^3.2.30",
+    "graphql-request": "^7.1.0",
     "mustache": "^4.2.0",
     "zod": "^3.22.4"
   }

kleros-sdk/src/dataMappings/actions/callAction.ts

@@ -1,10 +1,9 @@
 import { parseAbiItem } from "viem";
 import { AbiCallMapping } from "src/dataMappings/utils/actionTypes";
 import { createResultObject } from "src/dataMappings/utils/createResultObject";
-import { configureSDK, getPublicClient } from "src/sdk";
+import { getPublicClient } from "src/sdk";
 
-export const callAction = async (mapping: AbiCallMapping, alchemyApiKey: string) => {
-  configureSDK({ apiKey: alchemyApiKey });
+export const callAction = async (mapping: AbiCallMapping) => {
   const publicClient = getPublicClient();
 
   const { abi: source, address, args, seek, populate } = mapping;

kleros-sdk/src/dataMappings/actions/eventAction.ts

@@ -2,10 +2,9 @@ import { parseAbiItem } from "viem";
 import { type AbiEvent } from "abitype";
 import { AbiEventMapping } from "src/dataMappings/utils/actionTypes";
 import { createResultObject } from "src/dataMappings/utils/createResultObject";
-import { configureSDK, getPublicClient } from "src/sdk";
+import { getPublicClient } from "src/sdk";
 
-export const eventAction = async (mapping: AbiEventMapping, alchemyApiKey: string) => {
-  configureSDK({ apiKey: alchemyApiKey });
+export const eventAction = async (mapping: AbiEventMapping) => {
   const publicClient = getPublicClient();
 
   const { abi: source, address, eventFilter, seek, populate } = mapping;

kleros-sdk/src/dataMappings/executeActions.ts

@@ -32,9 +32,9 @@ export const executeAction = async (
     case "json":
       return jsonAction(validateJsonMapping(mapping));
     case "abi/call":
-      return await callAction(validateAbiCallMapping(mapping), context.alchemyApiKey as string);
+      return await callAction(validateAbiCallMapping(mapping));
     case "abi/event":
-      return await eventAction(validateAbiEventMapping(mapping), context.alchemyApiKey as string);
+      return await eventAction(validateAbiEventMapping(mapping));
     case "fetch/ipfs/json":
       return await fetchIpfsJsonAction(validateFetchIpfsJsonMapping(mapping));
     case "reality":

kleros-sdk/src/dataMappings/utils/replacePlaceholdersWithValues.ts

@@ -1,4 +1,5 @@
 import mustache from "mustache";
+import retrieveVariables from "./retrieveVariables";
 import { ActionMapping } from "./actionTypes";
 
 export function replacePlaceholdersWithValues(
@@ -7,6 +8,7 @@ export function replacePlaceholdersWithValues(
 ): ActionMapping | ActionMapping[] {
   function replace(obj: ActionMapping): ActionMapping | ActionMapping[] {
     if (typeof obj === "string") {
+      validateContext(obj, context);
       return mustache.render(obj, context) as unknown as ActionMapping;
     } else if (Array.isArray(obj)) {
       return obj.map(replace) as unknown as ActionMapping[];
@@ -21,3 +23,18 @@ export function replacePlaceholdersWithValues(
 
   return replace(mapping);
 }
+
+/**
+ *
+ * @param template
+ * @param context
+ * @description retrieves all variables from a template and validates if they are provided in the context
+ */
+const validateContext = (template: string, context: Record<string, unknown>) => {
+  const variables = retrieveVariables(template);
+
+  variables.forEach((variable) => {
+    if (!context[variable]) throw new Error(`Expected key :  "${variable}" to be provided in context.`);
+  });
+  return true;
+};

kleros-sdk/src/dataMappings/utils/retrieveVariables.ts

@@ -0,0 +1,20 @@
+import mustache from "mustache";
+
+/**
+ *
+ * @param template
+ * @returns Variables[] returns the variables in a template string
+ * @note This is a naive implementation and wil not work for complex tags, only works for {{}} and {{{}}} tags for now.
+ *       Reference : https://github.com/janl/mustache.js/issues/538
+ */
+const retrieveVariables = (template: string) =>
+  mustache
+    .parse(template)
+    .filter(function (v) {
+      return v[0] === "name" || v[0] === "&";
+    }) // add more conditions here to include more tags
+    .map(function (v) {
+      return v[1];
+    });
+
+export default retrieveVariables;

kleros-sdk/src/requests/fetchDisputeDetails.ts

@@ -0,0 +1,35 @@
+import { request } from "graphql-request";
+
+type DisputeDetailsQueryResponse = {
+  dispute: {
+    arbitrated: {
+      id: string;
+    };
+    arbitrableChainId: number;
+    externalDisputeId: number;
+    templateId: number;
+  };
+};
+
+const fetchDisputeDetails = async (endpoint: string, id: number) => {
+  const query = `
+    query DisputeDetails {
+    dispute(id: ${id}) {
+        arbitrated {
+            id
+        }
+        arbitrableChainId
+        externalDisputeId
+        templateId
+    }
+  }
+`;
+
+  try {
+    return await request<DisputeDetailsQueryResponse>(endpoint, query);
+  } catch (error: any) {
+    throw new Error(`Error querying Dispute Details , endpoint : ${endpoint}, message : ${error?.message}`);
+  }
+};
+
+export default fetchDisputeDetails;

kleros-sdk/src/requests/fetchDisputeTemplateFromId.ts

@@ -0,0 +1,27 @@
+import { request } from "graphql-request";
+
+type DisputeTemplateQueryResponse = {
+  disputeTemplate: {
+    templateData: string;
+    templateDataMappings: string;
+  };
+};
+
+const fetchDisputeTemplateFromId = async (endpoint: string, id: number) => {
+  const query = `
+    query DisputeTemplate {
+        disputeTemplate(id: ${id}) {
+            templateData
+            templateDataMappings
+        }
+    }
+`;
+
+  try {
+    return await request<DisputeTemplateQueryResponse>(endpoint, query);
+  } catch (error: any) {
+    throw new Error(`Error querying Dispute Template Registry , endpoint : ${endpoint}, message : ${error?.message}`);
+  }
+};
+
+export default fetchDisputeTemplateFromId;

kleros-sdk/src/sdk.ts

@@ -1,20 +1,15 @@
-import { createPublicClient, webSocket, type PublicClient } from "viem";
-import { arbitrumSepolia } from "viem/chains";
+import { createPublicClient, type PublicClient } from "viem";
+import { SdkConfig } from "./types";
 
 let publicClient: PublicClient | undefined;
 
-export const configureSDK = (config: { apiKey?: string }) => {
-  if (config.apiKey) {
-    const ALCHEMY_API_KEY = config.apiKey;
-    const transport = webSocket(`wss://arb-sepolia.g.alchemy.com/v2/${ALCHEMY_API_KEY}`);
-    publicClient = createPublicClient({
-      chain: arbitrumSepolia,
-      transport,
-    });
+export const configureSDK = (config: SdkConfig) => {
+  if (config.client) {
+    publicClient = createPublicClient(config.client);
   }
 };
 
-export const getPublicClient = (): PublicClient => {
+export const getPublicClient = (): PublicClient | undefined => {
   if (!publicClient) {
     throw new Error("SDK not configured. Please call `configureSDK` before using.");
   }

kleros-sdk/src/types/index.ts

@@ -0,0 +1,17 @@
+import { PublicClientConfig } from "viem";
+
+export type SdkConfig = {
+  client: PublicClientConfig;
+};
+
+type GetDisputeParametersOptions = {
+  sdkConfig: SdkConfig;
+  additionalContext: Record<string, any>;
+};
+
+export type GetDisputeParameters = {
+  disputeId: number;
+  coreSubgraph: string;
+  dtrSubgraph: string;
+  options: GetDisputeParametersOptions | undefined;
+};

kleros-sdk/src/utils/getDispute.ts

@@ -0,0 +1,57 @@
+import { type GetDisputeParameters } from "src/types";
+import { configureSDK } from "src/sdk";
+import fetchDisputeDetails from "src/requests/fetchDisputeDetails";
+import fetchDisputeTemplateFromId from "src/requests/fetchDisputeTemplateFromId";
+import { executeActions } from "dataMappings/executeActions";
+import { populateTemplate } from "dataMappings/utils/populateTemplate";
+import { DisputeDetails } from "dataMappings/utils/disputeDetailsTypes";
+
+/**
+ * Retrieves dispute parameters based on the provided dispute ID and subgraph endpoints.
+ *
+ * @param {GetDisputeParameters} disputeParameters - The parameters required to get the dispute.
+ * @param {number} disputeParameters.disputeId - A unique numeric identifier of the dispute in the Kleros Core contract.
+ * @param {string} disputeParameters.coreSubgraph - Endpoint for the Kleros core subgraph to use.
+ * @param {string} disputeParameters.dtrSubgraph - Endpoint for the Kleros dispute template registry subgraph.
+ * @param {GetDisputeParametersOptions | undefined} disputeParameters.options - Optional parameters to configure the SDK and provide additional context, if not configured already.
+ */
+export const getDispute = async (disputeParameters: GetDisputeParameters): Promise<DisputeDetails | undefined> => {
+  if (disputeParameters.options?.sdkConfig) {
+    configureSDK(disputeParameters.options.sdkConfig);
+  }
+  const { disputeId, dtrSubgraph, coreSubgraph, options } = disputeParameters;
+
+  const disputeDetails = await fetchDisputeDetails(coreSubgraph, disputeId);
+
+  if (!disputeDetails?.dispute) {
+    throw new Error(`Dispute details not found for disputeId: ${disputeId}`);
+  }
+
+  const template = await fetchDisputeTemplateFromId(dtrSubgraph, disputeDetails.dispute.templateId);
+
+  if (!template) {
+    throw new Error(`Template not found for template ID: ${disputeDetails.dispute.templateId}`);
+  }
+
+  const { templateData, templateDataMappings } = template.disputeTemplate;
+
+  const initialContext = {
+    arbitrableAddress: disputeDetails.dispute.arbitrated.id,
+    arbitrableChainID: disputeDetails.dispute.arbitrableChainId,
+    externalDisputeID: disputeDetails.dispute.externalDisputeId,
+    ...options?.additionalContext,
+  };
+
+  let data = {};
+  if (templateDataMappings) {
+    try {
+      data = await executeActions(JSON.parse(templateDataMappings), initialContext);
+    } catch (err: any) {
+      throw new Error(err);
+    }
+  }
+
+  const populatedTemplate = populateTemplate(templateData, data);
+
+  return populatedTemplate;
+};

kleros-sdk/test/dataMappings.test.ts

@@ -174,6 +174,7 @@ describe("full flow test", () => {
         { title: "Yes", description: "User is responsible", id: "0x01" },
         { title: "No", description: "User is not responsible", id: "0x02" },
       ],
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
       details: {
         ruling: "{{ruling}}",
         tied: "{{tied}}",
@@ -182,6 +183,9 @@ describe("full flow test", () => {
         toAddress: "{{toAddress}}",
         transferValue: "{{transferValue}}",
       },
+      arbitratorChainID: "421613",
+      arbitratorAddress: "0x0987654321098765432109876543210987654321",
+      version: "1.0",
     });
 
     const initialContext = { alchemyApiKey: "mocked_api_key" };
@@ -199,6 +203,7 @@ describe("full flow test", () => {
         { title: "Yes", description: "User is responsible", id: "0x01" },
         { title: "No", description: "User is not responsible", id: "0x02" },
       ],
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
       details: {
         ruling: "1",
         tied: "false",
@@ -207,6 +212,9 @@ describe("full flow test", () => {
         toAddress: "0x0987654321098765432109876543210987654321",
         transferValue: "100",
       },
+      arbitratorChainID: "421613",
+      arbitratorAddress: "0x0987654321098765432109876543210987654321",
+      version: "1.0",
     });
   });
 });
@@ -345,10 +353,7 @@ describe("populateTemplate", () => {
           reserved: false,
         },
       ],
-      policyURI: "https://example.com/policy",
-      frontendUrl: "https://example.com",
-      arbitrableChainID: "100",
-      arbitrableAddress: "0x1234567890123456789012345678901234567890",
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
       arbitratorChainID: "421613",
       arbitratorAddress: "0x0987654321098765432109876543210987654321",
       category: "General",
@@ -376,10 +381,7 @@ describe("populateTemplate", () => {
           reserved: false,
         },
       ],
-      policyURI: "https://example.com/policy",
-      frontendUrl: "https://example.com",
-      arbitrableChainID: "100",
-      arbitrableAddress: "0x1234567890123456789012345678901234567890",
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
       arbitratorChainID: "421613",
       arbitratorAddress: "0x0987654321098765432109876543210987654321",
       category: "General",
@@ -394,6 +396,22 @@ describe("populateTemplate", () => {
       title: "Test Title",
       description: "Test Description",
       question: "{{missingQuestion}}",
+      type: "single-select",
+      answers: [
+        {
+          title: "Yes",
+          description: "Affirmative",
+          id: "0x01",
+          reserved: false,
+        },
+      ],
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
+      arbitratorChainID: "421613",
+      arbitratorAddress: "0x0987654321098765432109876543210987654321",
+      category: "General",
+      lang: "en_US",
+      specification: "Spec",
+      version: "1.0",
     });
 
     const data = {
@@ -406,6 +424,22 @@ describe("populateTemplate", () => {
       title: "Test Title",
       description: "Test Description",
       question: "",
+      type: "single-select",
+      answers: [
+        {
+          title: "Yes",
+          description: "Affirmative",
+          id: "0x01",
+          reserved: false,
+        },
+      ],
+      policyURI: "/ipfs/QmUnPyGi31RoF4DRR8vT3u13YsppxtsbBKbdQAbcP8be4M/file.json",
+      arbitratorChainID: "421613",
+      arbitratorAddress: "0x0987654321098765432109876543210987654321",
+      category: "General",
+      lang: "en_US",
+      specification: "Spec",
+      version: "1.0",
     });
   });
 

subgraph/core/schema.graphql

@@ -174,6 +174,10 @@ type Dispute @entity {
   jurors: [User!]! @derivedFrom(field: "disputes")
   shifts: [TokenAndETHShift!]! @derivedFrom(field: "dispute")
   disputeKitDispute: [DisputeKitDispute!]! @derivedFrom(field: "coreDispute")
+  isCrossChain: Boolean
+  arbitrableChainId:BigInt
+  externalDisputeId:BigInt
+  templateId:BigInt
 }
 
 type PeriodIndexCounter @entity {