Skip to main content

Configuration

This guide covers configuring the L{CORE} SDK for development and connecting to City-Chain networks.

SDK Configuration​

Basic Initialization​

import { LCore } from '@locale/lcore-sdk';

const lcore = new LCore({
  // Required: Your API key (get from dashboard.locale.cash)
  apiKey: process.env.LCORE_API_KEY,

  // Required: Target network environment
  network: 'testnet',
});

Configuration Options​

interface LCoreConfig {
  // Authentication
  apiKey?: string;              // API key for authenticated requests

  // Network
  network: 'testnet' | 'mainnet';  // Target network environment
  rpcEndpoint?: string;            // Custom RPC endpoint (optional)

  // Timeouts
  timeout?: number;             // Request timeout in milliseconds (default: 30000)
  retries?: number;             // Number of retry attempts (default: 3)

  // Logging
  debug?: boolean;              // Enable debug logging (default: false)
}

Python Configuration​

from lcore_sdk import LCore

lcore = LCore(
    api_key=os.environ.get('LCORE_API_KEY'),
    network='testnet',
    debug=True  # Enable for troubleshooting
)

Environment Variables​

Create a .env file in your project root:

# Required for authenticated API calls
LCORE_API_KEY=your-api-key-here

# Target network environment
LCORE_NETWORK=testnet

# Optional: Custom endpoints
LCORE_RPC_ENDPOINT=https://custom-rpc.example.com
LCORE_API_ENDPOINT=https://api.locale.cash

# Optional: Debugging
LCORE_DEBUG=true

Loading Environment Variables​

TypeScript (with dotenv):

import 'dotenv/config';
import { LCore } from '@locale/lcore-sdk';

const lcore = new LCore({
  apiKey: process.env.LCORE_API_KEY,
  network: (process.env.LCORE_NETWORK as 'testnet' | 'mainnet') || 'testnet',
});

Python:

from dotenv import load_dotenv
import os

load_dotenv()

lcore = LCore(
    api_key=os.environ.get('LCORE_API_KEY'),
    network=os.environ.get('LCORE_NETWORK', 'testnet')
)

Available Networks​

NetworkDescriptionUse Case
testnetArbitrum SepoliaDevelopment and testing
mainnetArbitrum OneProduction

Network-Specific Configuration​

// Development
const devConfig = {
  apiKey: process.env.LCORE_API_KEY,
  network: 'testnet',
  debug: true,
};

// Production
const prodConfig = {
  apiKey: process.env.LCORE_API_KEY,
  network: 'mainnet',
  debug: false,
  timeout: 60000,  // Longer timeout for production
};

Device Configuration​

When registering devices, you'll configure device-specific settings:

const deviceConfig = {
  type: DeviceType.ENVIRONMENTAL_SENSOR,
  manufacturer: 'SensorCorp',
  model: 'ENV-100',

  // Location
  location: {
    lat: 39.0997,
    lng: -94.5786,
    altitude: 250,  // Optional: meters above sea level
  },

  // Custom metadata
  metadata: {
    installDate: '2024-01-15',
    serialNumber: 'SN-12345',
    calibrationDate: '2024-01-10',
  },
};

const device = await lcore.devices.register(deviceConfig);

Stream Configuration​

Configure data streams for your devices:

const streamConfig = {
  deviceId: device.id,
  dataType: 'air_quality',

  // Data collection interval (seconds)
  interval: 60,

  // Data schema (JSON Schema format)
  schema: {
    type: 'object',
    properties: {
      pm25: { type: 'number' },
      pm10: { type: 'number' },
      temperature: { type: 'number' },
      humidity: { type: 'number' },
    },
    required: ['pm25', 'pm10'],
  },

  // Optional: Transform rules
  transformRules: [
    {
      name: 'celsius-to-fahrenheit',
      input: 'temperature',
      output: 'temperature_f',
      operation: (value) => (value * 9/5) + 32,
    },
  ],
};

const stream = await lcore.streams.create(streamConfig);

Attestation Configuration​

Configure how attestations are created:

const attestationConfig = {
  streamId: stream.id,

  // Time range for attestation
  fromTimestamp: Date.now() - 3600000,  // 1 hour ago
  toTimestamp: Date.now(),

  // Aggregation method
  aggregation: 'average',  // 'average', 'sum', 'min', 'max', 'count'

  // Optional: Include raw data hash
  includeDataHash: true,
};

const attestation = await lcore.attest(attestationConfig);

Production Encryption Configuration​

For production deployments with data privacy requirements, you need to configure encryption. This is handled at the infrastructure level, not in the SDK.

See Encryption Key Configuration for:

  • Generating encryption keypairs
  • Configuring INPUT encryption (device data privacy)
  • Configuring OUTPUT encryption (query response privacy)
  • Key baking requirements for Cartesi

For a complete understanding of the encryption architecture, see Encryption Architecture.

Wallet Configuration (For Self-Hosted)​

If you're running your own attestation infrastructure, configure wallet access:

# attestor/.env

# Wallet for submitting attestations to chain
MNEMONIC=your twelve word mnemonic phrase here

# Or use private key directly
PRIVATE_KEY=0x...
Security

Never commit wallet credentials to version control. Use environment variables or secure secret management.

Configuration Validation​

The SDK validates configuration on initialization:

try {
  const lcore = new LCore({
    apiKey: process.env.LCORE_API_KEY,
    cityChainId: 'invalid-network',  // Will throw
  });
} catch (error) {
  if (error instanceof ConfigurationError) {
    console.error('Invalid configuration:', error.message);
  }
}

Configuration Best Practices​

  1. Use environment variables for sensitive data (API keys, mnemonics)
  2. Create separate configs for development, staging, and production
  3. Validate early - check configuration at application startup
  4. Use TypeScript for type-safe configuration
  5. Document your config - keep .env.example updated

Example: Multi-Environment Setup​

// config/index.ts
type Environment = 'development' | 'staging' | 'production';

const configs: Record<Environment, LCoreConfig> = {
  development: {
    apiKey: process.env.LCORE_API_KEY,
    network: 'testnet',
    debug: true,
  },
  staging: {
    apiKey: process.env.LCORE_API_KEY,
    network: 'testnet',
    debug: false,
  },
  production: {
    apiKey: process.env.LCORE_API_KEY,
    network: 'mainnet',
    debug: false,
    timeout: 60000,
  },
};

const env = (process.env.NODE_ENV || 'development') as Environment;
export const config = configs[env];

Cartesi Configuration​

If you're building Cartesi-based attestation applications, see the Cartesi Quickstart for initial setup and configuration options.

Next Steps​