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

Method	Purpose	When to implement
`collect()`	Gather raw signals from sensors/APIs	Plugin can actively collect evidence
`create()`	Parse signals into an unsigned stamp	Plugin produces structured location data
`sign()`	Add cryptographic signature to stamp	Plugin has its own signing mechanism
`verify()`	Check stamp internal validity	Plugin can verify its own stamps

Runtime type

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

PluginRegistry API

register()

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

Plugin status

Plugin	Package	Status	collect	create	sign	verify
Mock	Built into SDK	Complete	Yes	Yes	Yes	Yes
ProofMode	`@location-proofs/plugin-proofmode`	Alpha	Coming soon	Yes	—	Yes
WitnessChain	`@location-proofs/plugin-witnesschain`	In development	Coming soon	Coming soon	Coming soon	Coming 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

​Plugins

​LocationProofPlugin interface

​Method responsibilities

​Runtime type

​PluginRegistry API

​register()

​get()

​has()

​list()

​all()

​withMethod()

​Properties

​Plugin status

Plugin details

​MockPlugin

​How to write a custom plugin

Next: Compute module

Plugins

LocationProofPlugin interface

Method responsibilities

Runtime type

PluginRegistry API

register()

get()

has()

list()

all()

withMethod()

Properties

Plugin status

MockPlugin

How to write a custom plugin