Skip to main content
Research preview — The plugin system is under active development.

​
Plugins

The Astral SDK provides an extensible plugin system for integrating proof-of-location systems. Plugins implement a standard interface and are registered with the SDK at startup. The StampsModule and ProofsModule then orchestrate across registered plugins. 
import { AstralSDK } from '@decentralized-geo/astral-sdk';

const astral = new AstralSDK({ chainId: 84532, signer: wallet });

// Access via astral.plugins
astral.plugins.register(plugin);
astral.plugins.get(name);
astral.plugins.has(name);
astral.plugins.list();
astral.plugins.all();
astral.plugins.withMethod(method);

​
LocationProofPlugin interface

Every plugin implements this interface. All methods are optional — plugins implement what makes sense for their environment and data source. 
interface LocationProofPlugin {
  readonly name: string;                    // Unique identifier
  readonly version: string;                 // Semver
  readonly runtimes: Runtime[];             // Supported environments
  readonly requiredCapabilities: string[];  // e.g., ['gps', 'network']
  readonly description: string;

  collect?(options?: CollectOptions): Promise<RawSignals>;
  create?(signals: RawSignals): Promise<UnsignedLocationStamp>;
  sign?(stamp: UnsignedLocationStamp, signer?: StampSigner): Promise<LocationStamp>;
  verify?(stamp: LocationStamp): Promise<StampVerificationResult>;
}

​
Method responsibilities

MethodPurposeWhen to implement
collect()Gather raw signals from sensors/APIsPlugin can actively collect evidence
create()Parse signals into an unsigned stampPlugin produces structured location data
sign()Add cryptographic signature to stampPlugin has its own signing mechanism
verify()Check stamp internal validityPlugin can verify its own stamps

​
Runtime type

type Runtime = 'react-native' | 'node' | 'browser';

​
PluginRegistry API

​
register()

Register a plugin with the SDK. Validates runtime compatibility and throws if the current environment is not supported. 
astral.plugins.register(plugin: LocationProofPlugin): void

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

astral.plugins.register(new MockPlugin());
// Throws if current runtime is not in plugin.runtimes

​
get()

Get a plugin by name. Throws if not found. 
astral.plugins.get(name: string): LocationProofPlugin

const mock = astral.plugins.get('mock');
console.log(mock.version); // '0.1.0'

​
has()

Check if a plugin is registered. 
astral.plugins.has(name: string): boolean

​
list()

List metadata for all registered plugins. 
astral.plugins.list(): PluginMetadata[]

interface PluginMetadata {
  name: string;
  version: string;
  runtimes: Runtime[];
  requiredCapabilities: string[];
  description: string;
}

​
all()

Get all registered plugin instances. 
astral.plugins.all(): LocationProofPlugin[]

​
withMethod()

Find plugins that implement a specific method. 
astral.plugins.withMethod(
  method: keyof LocationProofPlugin
): LocationProofPlugin[]

// Find all plugins that can collect signals
const collectors = astral.plugins.withMethod('collect');
console.log(collectors.map(p => p.name)); // ['mock']

​
Properties

astral.plugins.currentRuntime  // Current detected runtime: 'node', 'browser', or 'react-native'
astral.plugins.size            // Number of registered plugins

​
Available plugins

PluginPackageStatuscollectcreatesignverify
MockBuilt into SDKCompleteYesYesYesYes
ProofMode@location-proofs/plugin-proofmodeAlphaComing soonYes—Yes
WitnessChain@location-proofs/plugin-witnesschainIn developmentComing soonComing soonComing soonComing soon

Plugin details

See the Plugins section for detailed documentation on each plugin.

​
MockPlugin

Built into the SDK for testing and development. Runs in all environments. 
import { MockPlugin } from '@decentralized-geo/astral-sdk';

const mock = new MockPlugin({
  lat: 37.7749,           // Default: 40.7484 (Empire State Building)
  lon: -122.4194,         // Default: -73.9857
  jitterMeters: 5,        // Random offset in meters (default: 0)
  accuracy: 10,           // Meters (default: 10)
  timestamp: 1700000000,  // Unix seconds (default: current time)
  durationSeconds: 60,    // Temporal footprint duration (default: 60)
  privateKey: '0x...'     // Deterministic signing key (optional)
});

astral.plugins.register(mock);
See MockPlugin documentation for full details.

​
How to write a custom plugin

Implement the LocationProofPlugin interface with whichever methods your system supports, then register with astral.plugins.register(). See Building a custom plugin for the complete guide with examples and testing patterns.

Next: Compute module

Geospatial computation methods