SDK Overview

Unified TypeScript SDK for Astral Location Services v0.2.0

Development Preview — The SDK is under development.

v0.2.0 Unified SDK — The SDK now provides a unified API with namespaced modules. Location attestations and geospatial computations are now in a single package: @decentralized-geo/astral-sdk.

SDK Overview

The Astral SDK is the official TypeScript client for Astral Location Services, providing a unified interface for location attestations and verifiable geospatial computations.

Design Philosophy

• Namespaced API: Clear separation between location and compute operations
• Workflow-oriented: Distinct offchain and onchain workflows for location attestations
• Type-safe: Full TypeScript support with comprehensive types
• Batteries included: Handles signing, encoding, and EAS integration

Package Structure

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

// Initialize with unified configuration
const astral = new AstralSDK({
  chainId: 84532,
  signer: wallet,
  apiUrl: 'https://api.astral.global'
});

// Location module - offchain workflow
astral.location.offchain.create(input);
astral.location.offchain.sign(unsigned);
astral.location.offchain.verify(attestation);
astral.location.offchain.publish(attestation);

// Location module - onchain workflow
astral.location.onchain.create(input);
astral.location.onchain.register(unsigned);
astral.location.onchain.verify(attestation);
astral.location.onchain.revoke(attestation);

// Location module - common operations
astral.location.build(input);
astral.location.encode(attestation);
astral.location.decode(data);

// Compute module - spatial operations
astral.compute.distance(from, to, options);
astral.compute.area(geometry, options);
astral.compute.length(geometry, options);
astral.compute.contains(container, containee, options);
astral.compute.within(geometry, target, radius, options);
astral.compute.intersects(a, b, options);

// Compute module - submission
astral.compute.submit(delegatedAttestation);
astral.compute.estimate(delegatedAttestation);
astral.compute.health();

Quick Start

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

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

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

// Create an offchain location attestation
const attestation = await astral.location.offchain.create({
  location: {
    type: 'Point',
    coordinates: [2.2945, 48.8584]
  },
  memo: 'Eiffel Tower'
});

console.log('Attestation UID:', attestation.uid);

// Compute distance between two locations
const distance = await astral.compute.distance(
  attestation.uid,
  landmarkUID,
  { schema: SCHEMA_UID }
);

console.log('Distance:', distance.result, distance.units);

// Submit computation result onchain
await astral.compute.submit(distance.delegatedAttestation);

Key Concepts

Namespaced Modules

Clear separation: location.offchain.*, location.onchain.*, and compute.*

Flexible Inputs

Accept UIDs, raw GeoJSON, or attestation objects interchangeably.

Delegated Attestations

SDK handles the delegated attestation pattern — you pay gas, Astral is attester.

Type Safety

Full TypeScript types for all inputs, outputs, and options.

Configuration

interface AstralConfig {
  // Required
  chainId: number;              // Target chain ID (e.g., 84532 for Base Sepolia)

  // Recommended
  signer?: Signer;              // For signing attestations and transactions
  provider?: Provider;          // For read-only blockchain operations
  apiUrl?: string;              // Defaults to 'https://api.astral.global'

  // Advanced
  debug?: boolean;              // Enable debug logging
  schemas?: RuntimeSchemaConfig[];  // Pre-register custom schemas
  defaultSchema?: RuntimeSchemaConfig;  // Override default schema
  strictSchemaValidation?: boolean;     // Throw on schema validation errors
}

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

Module Architecture

AstralSDK
├── location: LocationModule
│   ├── offchain: OffchainWorkflow
│   │   ├── create()    - Build + sign in one step
│   │   ├── sign()      - Sign unsigned attestation
│   │   ├── verify()    - Verify signature
│   │   └── publish()   - Store to IPFS/storage
│   ├── onchain: OnchainWorkflow
│   │   ├── create()    - Build + register in one step
│   │   ├── register()  - Register unsigned attestation
│   │   ├── verify()    - Verify onchain attestation
│   │   └── revoke()    - Revoke attestation
│   ├── build()         - Build unsigned attestation
│   ├── encode()        - Encode for EAS
│   └── decode()        - Decode from EAS
└── compute: ComputeModule
    ├── distance()      - Distance between geometries
    ├── area()          - Area of polygon
    ├── length()        - Length of line
    ├── contains()      - Containment check
    ├── within()        - Proximity check
    ├── intersects()    - Intersection check
    ├── submit()        - Submit delegated attestation
    ├── estimate()      - Estimate gas
    └── health()        - Service health check

Pages

Installation

Install and configure the SDK

Location Module

Offchain and onchain attestation workflows

Compute Module

Geospatial computation methods

Migration Guide

Migrate from v0.1.x to v0.2.0