Research Preview — The SDK is under development.
Migration Guide: v0.1.x to v0.2.0 This guide covers the breaking changes and migration steps for upgrading from Astral SDK v0.1.x to v0.2.0.
Overview of Changes What Changed
Namespaced API : Methods are organized under location.offchain.*, location.onchain.*, and compute.*New Compute Module : The compute.* namespace provides verifiable geospatial operationsSimplified Configuration : Single AstralConfig for initialization
What Stayed the Same
Core attestation types (UnsignedLocationAttestation, OffchainLocationAttestation, OnchainLocationAttestation)
Location format support (GeoJSON, WKT, H3, coordinates)
EAS integration and schema encoding
Package Changes Before (v0.1.x) # Two separate packages npm install @decentralized-geo/astral-sdk npm install @decentralized-geo/astral-compute
After (v0.2.0) # Single unified package npm install @decentralized-geo/astral-sdk
Initialization Changes Before (v0.1.x) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; import { AstralCompute , AstralEAS } from '@decentralized-geo/astral-compute' ; // Separate initialization const sdk = new AstralSDK ({ signer: wallet }); const compute = new AstralCompute ({ chainId: 84532 }); const eas = new AstralEAS ( wallet , 84532 );
After (v0.2.0) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; // Unified initialization const astral = new AstralSDK ({ chainId: 84532 , signer: wallet , apiUrl: 'https://api.astral.global' }); // Access modules via namespaces astral . location . offchain . * astral . location . onchain . * astral . compute . *
Method Migration Table Location Module v0.1.x Method v0.2.0 Method sdk.buildLocationAttestation()astral.location.build()sdk.encodeLocationAttestation()astral.location.encode()sdk.decodeLocationAttestation()astral.location.decode()
Offchain Workflow v0.1.x Method v0.2.0 Method sdk.createOffchainLocationAttestation()astral.location.offchain.create()sdk.signOffchainLocationAttestation()astral.location.offchain.sign()sdk.verifyOffchainLocationAttestation()astral.location.offchain.verify()sdk.publishOffchainLocationAttestation()astral.location.offchain.publish()
Onchain Workflow v0.1.x Method v0.2.0 Method sdk.createOnchainLocationAttestation()astral.location.onchain.create()sdk.registerOnchainLocationAttestation()astral.location.onchain.register()sdk.verifyOnchainLocationAttestation()astral.location.onchain.verify()sdk.revokeOnchainLocationAttestation()astral.location.onchain.revoke()
Compute Module v0.1.x (astral-compute) v0.2.0 Method compute.distance()astral.compute.distance()compute.area()astral.compute.area()compute.length()astral.compute.length()compute.contains()astral.compute.contains()compute.within()astral.compute.within()compute.intersects()astral.compute.intersects()eas.submitDelegated()astral.compute.submit()eas.estimateGas()astral.compute.estimate()
Code Migration Examples Example 1: Creating an Offchain Attestation Before (v0.1.x) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; const sdk = new AstralSDK ({ signer: wallet }); const unsigned = await sdk . buildLocationAttestation ({ location: { type: 'Point' , coordinates: [ 2.2945 , 48.8584 ] }, memo: 'Eiffel Tower' }); const signed = await sdk . signOffchainLocationAttestation ( unsigned ); const verified = await sdk . verifyOffchainLocationAttestation ( signed );
After (v0.2.0) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; const astral = new AstralSDK ({ chainId: 84532 , signer: wallet }); // Option 1: Build and sign separately const unsigned = await astral . location . build ({ location: { type: 'Point' , coordinates: [ 2.2945 , 48.8584 ] }, memo: 'Eiffel Tower' }); const signed = await astral . location . offchain . sign ( unsigned ); // Option 2: Create in one step const attestation = await astral . location . offchain . create ({ location: { type: 'Point' , coordinates: [ 2.2945 , 48.8584 ] }, memo: 'Eiffel Tower' }); const verified = await astral . location . offchain . verify ( attestation );
Example 2: Creating an Onchain Attestation Before (v0.1.x) const sdk = new AstralSDK ({ signer: wallet , chainId: 84532 }); const unsigned = await sdk . buildLocationAttestation ({ location: geojson }); const onchain = await sdk . registerOnchainLocationAttestation ( unsigned );
After (v0.2.0) const astral = new AstralSDK ({ chainId: 84532 , signer: wallet }); // Option 1: Build and register separately const unsigned = await astral . location . build ({ location: geojson }); const onchain = await astral . location . onchain . register ( unsigned ); // Option 2: Create in one step const onchain = await astral . location . onchain . create ({ location: geojson });
Example 3: Geospatial Computation Before (v0.1.x) import { AstralCompute , AstralEAS } from '@decentralized-geo/astral-compute' ; const compute = new AstralCompute ({ chainId: 84532 }); const eas = new AstralEAS ( wallet , 84532 ); const result = await compute . within ( userLocationUID , landmarkUID , 500 , { schema: SCHEMA_UID } ); if ( result . result ) { await eas . submitDelegated ( result . delegatedAttestation ); }
After (v0.2.0) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; const astral = new AstralSDK ({ chainId: 84532 , signer: wallet , apiUrl: 'https://api.astral.global' }); const result = await astral . compute . within ( userLocationUID , landmarkUID , 500 , { schema: SCHEMA_UID } ); if ( result . result ) { await astral . compute . submit ( result . delegatedAttestation ); }
Example 4: Full Workflow Before (v0.1.x) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; import { AstralCompute , AstralEAS } from '@decentralized-geo/astral-compute' ; // Initialize three clients const sdk = new AstralSDK ({ signer: wallet }); const compute = new AstralCompute ({ chainId: 84532 }); const eas = new AstralEAS ( wallet , 84532 ); // Create location const unsigned = await sdk . buildLocationAttestation ({ location: userCoords }); const location = await sdk . registerOnchainLocationAttestation ( unsigned ); // Check policy const result = await compute . within ( location . uid , landmarkUID , 500 , { schema: SCHEMA_UID } ); // Submit result if ( result . result ) { await eas . submitDelegated ( result . delegatedAttestation ); }
After (v0.2.0) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; // Single unified client const astral = new AstralSDK ({ chainId: 84532 , signer: wallet , apiUrl: 'https://api.astral.global' }); // Create location const location = await astral . location . onchain . create ({ location: userCoords }); // Check policy const result = await astral . compute . within ( location . uid , landmarkUID , 500 , { schema: SCHEMA_UID } ); // Submit result if ( result . result ) { await astral . compute . submit ( result . delegatedAttestation ); }
Configuration Changes Before (v0.1.x) // AstralSDK config interface AstralSDKConfig { signer : Signer ; chainId ?: number ; defaultChain ?: string ; } // AstralCompute config interface AstralComputeConfig { chainId : number ; apiUrl ?: string ; }
After (v0.2.0) interface AstralConfig { // Required chainId : number ; // Optional signer ?: Signer ; provider ?: Provider ; apiUrl ?: string ; debug ?: boolean ; schemas ?: RuntimeSchemaConfig []; defaultSchema ?: RuntimeSchemaConfig ; strictSchemaValidation ?: boolean ; }
Legacy Support If you need to maintain backward compatibility during migration, the v0.1.x API is available via AstralSDKLegacy:
import { AstralSDKLegacy } from '@decentralized-geo/astral-sdk' ; // Use v0.1.x API const sdk = new AstralSDKLegacy ({ signer: wallet }); const unsigned = await sdk . buildLocationAttestation ({ ... }); const signed = await sdk . signOffchainLocationAttestation ( unsigned );
AstralSDKLegacy is deprecated and will be removed in v0.3.0. Migrate to the new API before then.
TypeScript Import Changes Before (v0.1.x) import { AstralSDK } from '@decentralized-geo/astral-sdk' ; import { AstralCompute , AstralEAS , NumericComputeResult , BooleanComputeResult } from '@decentralized-geo/astral-compute' ;
After (v0.2.0) import { AstralSDK , // Location types LocationAttestationInput , UnsignedLocationAttestation , OffchainLocationAttestation , OnchainLocationAttestation , VerificationResult , // Compute types Input , ComputeOptions , NumericComputeResult , BooleanComputeResult , DelegatedAttestation , // Configuration AstralConfig , RuntimeSchemaConfig , } from '@decentralized-geo/astral-sdk' ;
Need Help? If you encounter issues during migration:
Check the SDK Overview for complete API reference
Review the Location Module and Compute Module documentation
Join our Telegram community for support
Open an issue on GitHub
Back: SDK Overview Return to SDK overview
