> ## Documentation Index
> Fetch the complete documentation index at: https://astral-6ef288be-docs-policy-evaluation-framing.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugins

> Extensible plugin system for proof-of-location integrations

<Warning>
  **Research Preview** — The plugin system is under active development.
</Warning>

# 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.

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
astral.plugins.register(plugin: LocationProofPlugin): void
```

```typescript theme={null}
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.

```typescript theme={null}
astral.plugins.get(name: string): LocationProofPlugin
```

```typescript theme={null}
const mock = astral.plugins.get('mock');
console.log(mock.version); // '0.1.0'
```

### has()

Check if a plugin is registered.

```typescript theme={null}
astral.plugins.has(name: string): boolean
```

### list()

List metadata for all registered plugins.

```typescript theme={null}
astral.plugins.list(): PluginMetadata[]
```

```typescript theme={null}
interface PluginMetadata {
  name: string;
  version: string;
  runtimes: Runtime[];
  requiredCapabilities: string[];
  description: string;
}
```

### all()

Get all registered plugin instances.

```typescript theme={null}
astral.plugins.all(): LocationProofPlugin[]
```

### withMethod()

Find plugins that implement a specific method.

```typescript theme={null}
astral.plugins.withMethod(
  method: keyof LocationProofPlugin
): LocationProofPlugin[]
```

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

### Properties

```typescript theme={null}
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 |

<Card title="Plugin details" icon="plug" href="/plugins/overview">
  See the Plugins section for detailed documentation on each plugin.
</Card>

***

## MockPlugin

Built into the SDK for testing and development. Runs in all environments.

```typescript theme={null}
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](/plugins/mock) 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](/plugins/custom) for the complete guide with examples and testing patterns.

<Card title="Next: Compute module" icon="calculator" href="/sdk/compute">
  Geospatial computation methods
</Card>