Handling Multiple URLs

The Problem

In many use cases, one may want to create an aggregated attestation for multiple request URLs. For example, you can generate one zkTLS attestation which contains both the token A's USDT price and token B's USDT price from an exchange market data service.

Primus zkTLS tools including network-core-sdk and zktls-core-sdk support the multiple URLs aggregation. The zktls-js-sdk can be configured to support multiple URLs as well. This feature is available upon request; please contact the Primus team.

The Usage in zkTLS-Core-SDK

The adoption of multiple urls in zkTLS-Core-SDK is a little bit different from the usage in Network-Core-SDK.

The Defined Requests and ResponseResolves

Note this part is the same as the use in Network-Core-SDK.

let request = [
                {
                    url: "https://www.okx.com/api/v5/public/instruments?instType=SPOT&instId=BTC-USD",
                    method: "GET",
                    header: {},
                    body: "",
                },
                {
                    url: "https://www.okx.com/api/v5/public/time",
                    method: "GET",
                    header: {},
                    body: "",
                }
            ];

            const responseResolves = [
                [
                    {
                        keyName: "instType",
                        parseType: "json",
                        parsePath: "$.data[0].instType"
                    }
                ],
                [
                    {
                        keyName: "time",
                        parseType: "json",
                        parsePath: "$.data[0].ts",
                    }
                ]
            ];

Encode the attestParams

You can use the following code segement to add the requests and the responseResolves in the attestation parameters, and then call the startAttestation() function.

// Generate attestation request.
const generateRequest = zkTLS.generateRequestParams(request, responseResolves);
// Start attestation process.
const attestation = await zkTLS.startAttestation(generateRequest);

The Attestation Structure

Note the returned attestation encoding is different from the above multi-URL attestation in the usage of Network-Core-SDK.

Specifically, multi-URL requests and their response resolutions are encoded as two-dimensional arrays. In the returned attestation, the data contains all the requested data fields for both URLs, like in the Network-Core-SDK.

The request and responseResolve params for the first request URL appears directly in the attestation payload, while the related params for second request URL are wrapped and presented within the additionalParams field.

attestation= {
  recipient: '0x0000000000000000000000000000000000000000',
  request: {
    url: 'https://www.okx.com/api/v5/market/index-tickers?instId=BTC-USDT',
    header: '',
    method: 'GET',
    body: ''
  },
  reponseResolve: [
    {
      keyName: 'btc-idxPx',
      parseType: '',
      parsePath: '$.data[0].idxPx'
    },
    {
      keyName: 'btc-high24h',
      parseType: '',
      parsePath: '$.data[0].high24h'
    }
  ],
  data: '{"sol-idxPx.count":"1","btc-high24h":"89622.8","btc-high24h.count":"1","sol-idxPx":"126.37","btc-idxPx":"89083.8","btc-idxPx.count":"1"}',  // the data for two requests, the `count` field can be ignored
  attConditions: '[{"op":"REVEAL_STRING","field":"$.data[0].idxPx"},{"op":"REVEAL_STRING","field":"$.data[0].high24h"},{"op":"REVEAL_STRING","field":"$.data[0].idxPx"}]',
  timestamp: 1766389694836,
  additionParams: '{"algorithmType":"proxytls","requests[1].url":"https://www.okx.com/api/v5/market/index-tickers?instId=SOL-USDT","requests[1].method":"GET","requests[1].body":"","requests[1].header":"","reponseResolves[1][0].keyName":"sol-idxPx","reponseResolves[1][0].parseType":"","reponseResolves[1][0].parsePath":"$.data[0].idxPx"}', // the additonal params for the request param and responseResolve param in the second URL
  attestors: [
    {
      attestorAddr: '0xdb736b13e2f522dbe18b2015d0291e4b193d8ef6',
      url: 'https://primuslabs.xyz'
    }
  ],
  signatures: [
    '0xc4b714d23c28866c503b3d7b9caa637b65c21f962f6cf38dc6b2c91a5c837504048a9ffecd5b5e8f63dbb3d8ee40f075fd19667b7789b88bcc884d38d5669b6a1b'
  ]
}