Skip to main content

L{CORE} TypeScript SDK

How to use the @localecore/lcore-sdk TypeScript package.

Compatibility​

RequirementSupported
Node.js18+
RuntimeNode.js, Bun, Deno
TypeScript5.0+ (optional)
PlatformsLinux, macOS, Windows

Installation​

npm install @localecore/lcore-sdk

Quick Start​

import { LCore } from '@localecore/lcore-sdk'

const lcore = new LCore({
  attestorUrl: 'http://localhost:8001',
  cartesiUrl: 'http://localhost:10000',
  dappAddress: '0xYourDappAddress',
})

// Create an attestation
const result = await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/data',
    responseRedactions: [{ jsonPath: 'value' }]
  }
})

console.log(result.claimId)

Core Concepts​

Attestation​

An attestation is a cryptographic proof that data from an external source matches certain criteria at a point in time.

const result = await lcore.attest({
  // Provider type (currently 'http')
  provider: 'http',

  // Provider-specific parameters
  params: {
    url: 'https://api.example.com/data',
    method: 'GET',
    responseRedactions: [
      { jsonPath: 'temperature' }
    ]
  },

  // Secret parameters (not included in proof)
  secretParams: {
    headers: {
      'Authorization': 'Bearer token'
    }
  }
})

Query​

Query attested data from the Cartesi node:

const result = await lcore.query({
  type: 'attestation',
  params: { claimId: 'abc123' }
})

if (result.success) {
  console.log(result.data)
}

HTTP Provider​

The HTTP provider attests data from any HTTP endpoint.

Basic GET Request​

await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/status',
    responseMatches: [
      { type: 'contains', value: '"online":true' }
    ]
  }
})

With URL Parameters​

await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/users/{{userId}}/profile',
    paramValues: {
      userId: '12345'
    },
    responseRedactions: [
      { jsonPath: 'name' },
      { jsonPath: 'email' }
    ]
  }
})

POST Request with Body​

await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://api.example.com/query',
    method: 'POST',
    body: JSON.stringify({ query: 'SELECT * FROM data' }),
    responseRedactions: [
      { jsonPath: 'results[0].value' }
    ]
  },
  secretParams: {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer secret-token'
    }
  }
})

Response Matching​

Validate response content before attestation:

params: {
  responseMatches: [
    // Must contain this exact string
    { type: 'contains', value: '"status":"success"' },

    // Must match regex pattern
    { type: 'regex', value: '"temperature":\\s*\\d+' },

    // Must equal exactly
    { type: 'exact', value: '{"ok":true}' }
  ]
}

Response Redaction​

Extract specific fields for the attestation:

params: {
  responseRedactions: [
    // Extract JSON field
    { jsonPath: 'data.temperature' },

    // Extract nested array element
    { jsonPath: 'readings[0].value' },

    // Extract by regex
    { regex: 'temperature=(\\d+)' },

    // Extract substring
    { startIndex: 10, endIndex: 20 }
  ]
}

IoT Integration Examples​

AWS IoT Device Shadow​

await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://data-ats.iot.{{region}}.amazonaws.com/things/{{thingName}}/shadow',
    paramValues: {
      region: 'us-east-1',
      thingName: 'temperature-sensor-001'
    },
    responseRedactions: [
      { jsonPath: 'state.reported.temperature' },
      { jsonPath: 'state.reported.humidity' }
    ]
  },
  secretParams: {
    headers: {
      'Authorization': 'AWS4-HMAC-SHA256 ...'
    }
  }
})

Azure IoT Hub Device Twin​

await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://{{hubName}}.azure-devices.net/twins/{{deviceId}}?api-version=2021-04-12',
    paramValues: {
      hubName: 'my-iot-hub',
      deviceId: 'sensor-001'
    },
    responseRedactions: [
      { jsonPath: 'properties.reported.temperature' }
    ]
  },
  secretParams: {
    headers: {
      'Authorization': 'SharedAccessSignature sr=...'
    }
  }
})

Generic REST API​

// Weather station API
await lcore.attest({
  provider: 'http',
  params: {
    url: 'https://weather.station.local/api/v1/readings',
    responseMatches: [
      { type: 'contains', value: '"status":"ok"' }
    ],
    responseRedactions: [
      { jsonPath: 'temperature' },
      { jsonPath: 'humidity' },
      { jsonPath: 'pressure' }
    ]
  }
})

Health Check​

Check if services are running:

const health = await lcore.health()

console.log(health)
// {
//   status: 'ok',           // 'ok' | 'degraded' | 'down'
//   version: '5.0.0',
//   lcoreEnabled: true,
//   cartesiConnected: true
// }

Error Handling​

import { LCore, LCoreError } from '@localecore/lcore-sdk'

try {
  await lcore.attest(...)
} catch (error) {
  if (error instanceof LCoreError) {
    console.error(`Error: ${error.code}`)
    // Codes: ATTESTOR_UNREACHABLE, CARTESI_UNREACHABLE,
    //        INVALID_CONFIG, ATTESTATION_FAILED,
    //        QUERY_FAILED, SIGNATURE_INVALID, TIMEOUT
  }
}

Environment Variables​

Create a client from environment variables:

import { createLCoreFromEnv } from '@localecore/lcore-sdk'

// Uses:
// - LCORE_ATTESTOR_URL
// - LCORE_CARTESI_URL
// - LCORE_DAPP_ADDRESS
// - LCORE_TIMEOUT (optional)

const lcore = createLCoreFromEnv()

Advanced: Direct Client Access​

For advanced operations, access the underlying clients:

// Attestor client
const attestor = lcore.attestorClient
const schemas = await attestor.getProviderSchemas()

// Cartesi client
const cartesi = lcore.cartesiClient
const result = await cartesi.query({
  type: 'bucket',
  params: { bucketId: '...' }
})

TypeScript Types​

All types are exported:

import type {
  LCoreConfig,
  AttestRequest,
  AttestResult,
  QueryRequest,
  QueryResult,
  HttpProviderParams,
  HealthStatus,
  ProviderSchema,
} from '@localecore/lcore-sdk'

Next Steps​