Installation

Install and configure the Astral SDK v0.2.0

Development Preview — The SDK is under development.

Installation

The Astral SDK v0.2.0 is a unified package that includes both location attestations and geospatial computations.

Package Manager

npm

npm install @decentralized-geo/astral-sdk

Peer Dependencies

The SDK requires ethers.js v6:

npm install ethers@^6.0.0

Basic Initialization

import { AstralSDK } from '@decentralized-geo/astral-sdk';
import { ethers } from 'ethers';

// Create a provider and signer
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

// Initialize the SDK
const astral = new AstralSDK({
  chainId: 84532,  // Base Sepolia
  signer: wallet,
  apiUrl: 'https://api.astral.global'
});

// Now you can use both location and compute modules
const attestation = await astral.location.offchain.create({ ... });
const distance = await astral.compute.distance(uid1, uid2, options);

With Browser Wallet

import { AstralSDK } from '@decentralized-geo/astral-sdk';
import { ethers } from 'ethers';

// Connect to browser wallet (MetaMask, etc.)
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Get the chain ID from the connected wallet
const network = await provider.getNetwork();

// Initialize the SDK
const astral = new AstralSDK({
  chainId: Number(network.chainId),
  signer: signer,
  apiUrl: 'https://api.astral.global'
});

Read-Only Mode

For querying and verification without signing:

import { AstralSDK } from '@decentralized-geo/astral-sdk';
import { ethers } from 'ethers';

// Provider-only (no signer)
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');

const astral = new AstralSDK({
  chainId: 84532,
  provider: provider,
  apiUrl: 'https://api.astral.global'
});

// Can verify attestations
const result = await astral.location.onchain.verify(attestation);

// Can compute (API calls don't require signer)
const distance = await astral.compute.distance(uid1, uid2, options);

// Cannot submit to EAS without signer
// await astral.compute.submit(attestation); // Would throw error

Configuration Options

interface AstralConfig {
  /**
   * Target chain ID. Required.
   * All operations are scoped to this chain.
   */
  chainId: number;

  /**
   * Ethers signer for signing attestations and transactions.
   * Required for creating attestations and submitting to EAS.
   */
  signer?: Signer;

  /**
   * Ethers provider for read-only blockchain operations.
   * If not provided and signer is present, uses signer's provider.
   */
  provider?: Provider;

  /**
   * Astral API base URL.
   * Defaults to 'https://api.astral.global'
   */
  apiUrl?: string;

  /**
   * Enable debug logging.
   * Defaults to false.
   */
  debug?: boolean;

  /**
   * Pre-register custom EAS schemas.
   * Useful for performance when using multiple schemas.
   */
  schemas?: RuntimeSchemaConfig[];

  /**
   * Default schema to use when none is specified.
   * If not provided, uses the built-in location schema.
   */
  defaultSchema?: RuntimeSchemaConfig;

  /**
   * Throw errors on schema validation failures.
   * Defaults to false (logs warnings instead).
   */
  strictSchemaValidation?: boolean;
}

Supported Chains

Network	Chain ID	Status
Base Sepolia	84532	Active
Base Mainnet	8453	Active
Ethereum Sepolia	11155111	Active
Ethereum Mainnet	1	Active
Celo	42220	Active
Arbitrum	42161	Active
Optimism	10	Active

Custom Schema Configuration

import { AstralSDK } from '@decentralized-geo/astral-sdk';

// Define a custom schema
const customSchema = {
  uid: '0x1234567890abcdef...',
  rawString: 'uint256 eventTimestamp,string srs,string locationType,string location,string[] recipeType,string[] recipePayload,string[] mediaType,string[] mediaData,string memo'
};

// Initialize with custom schema
const astral = new AstralSDK({
  chainId: 84532,
  signer: wallet,
  defaultSchema: customSchema,
  strictSchemaValidation: true
});

// Or specify per-operation
const attestation = await astral.location.offchain.create(
  { location: geojson },
  { schema: customSchema }
);

TypeScript Support

The SDK is written in TypeScript and ships with full type definitions:

import {
  AstralSDK,
  // Location types
  LocationAttestationInput,
  UnsignedLocationAttestation,
  OffchainLocationAttestation,
  OnchainLocationAttestation,
  VerificationResult,
  // Compute types
  Input,
  ComputeOptions,
  NumericComputeResult,
  BooleanComputeResult,
  DelegatedAttestation,
  // Configuration types
  AstralConfig,
  RuntimeSchemaConfig,
} from '@decentralized-geo/astral-sdk';

Submodule Imports

You can also import submodules directly for tree-shaking:

// Import just what you need
import { LocationModule } from '@decentralized-geo/astral-sdk/location';
import { ComputeModule } from '@decentralized-geo/astral-sdk/compute';

// Use independently
const location = new LocationModule({ chainId: 84532, signer: wallet });
const compute = new ComputeModule({ apiUrl: 'https://api.astral.global', chainId: 84532 });

Environment Variables

For server-side applications:

# .env
PRIVATE_KEY=0x...          # Your wallet private key
CHAIN_ID=84532             # Target chain ID
ASTRAL_API_URL=https://api.astral.global

import { AstralSDK } from '@decentralized-geo/astral-sdk';
import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(getRpcUrl(process.env.CHAIN_ID));
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY, provider);

const astral = new AstralSDK({
  chainId: Number(process.env.CHAIN_ID),
  signer: wallet,
  apiUrl: process.env.ASTRAL_API_URL
});

Next: Location Module

Learn about location attestation workflows