Research Preview — APIs may change. GitHub

Building verification plugins

A plugin connects a proof-of-location (PoL) system to Astral’s verification framework. Plugins collect signals from a PoL system, produce location stamps, and verify those stamps.

The plugin interface is under active development. The patterns shown here reflect the current design direction, but specifics may change as we iterate on the verification framework.

What is a plugin?

Proof-of-location systems vary widely — hardware attestation, network triangulation, sensor fusion, institutional records. A plugin is a standardized adapter that translates a specific PoL system’s output into the common stamp format that Astral can verify and cross-correlate. Each plugin handles three responsibilities:

Collect signals from the PoL system (GPS readings, network measurements, device attestations)
Create stamps from those signals (structured evidence artifacts)
Verify stamps for authenticity and structural integrity

Plugin interface

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

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

  // Each method is optional — a plugin implements the stages it supports
  collect?(options?: CollectOptions): Promise<RawSignals>;
  create?(signals: RawSignals): Promise<UnsignedLocationStamp>;
  sign?(stamp: UnsignedLocationStamp, signer?: StampSigner): Promise<LocationStamp>;
  verify?(stamp: LocationStamp): Promise<StampVerificationResult>;
}

interface RawSignals {
  plugin: string;
  timestamp: number;             // Unix seconds
  data: Record<string, unknown>; // plugin-specific signal data
}

interface StampVerificationResult {
  valid: boolean;
  signaturesValid: boolean;
  structureValid: boolean;
  signalsConsistent: boolean;
  details: Record<string, unknown>;
}

How stamps work

A stamp is a signed artifact from a PoL system. It encodes the system’s conclusion about where and when an event occurred, along with the raw signals that support that conclusion. Stamps follow the Location Protocol format:

interface LocationStamp {
  // Location data (LP v0.2)
  lpVersion: string;
  locationType: string;
  location: LocationData;     // Where evidence indicates the subject was
  srs: string;

  // Temporal footprint
  temporalFootprint: { start: number; end: number };

  // Plugin identification
  plugin: string;             // "proofmode", "witnesschain", etc.
  pluginVersion: string;

  // Evidence and signatures
  signals: Record<string, unknown>;
  signatures: Signature[];
}

The distinction between a stamp’s location and a claim’s location is important. The stamp records where the PoL system observed the subject. The claim records where the subject asserts they were. Verification compares the two.

Implementation guide

Here is a step-by-step walkthrough for building a hypothetical plugin that uses Wi-Fi access point data.

Step 1: Define signal collection

import type {
  LocationProofPlugin,
  RawSignals,
  UnsignedLocationStamp,
  LocationStamp,
  StampVerificationResult,
} from '@decentralized-geo/astral-sdk';

const wifiPlugin: LocationProofPlugin = {
  name: 'wifi-triangulation',
  version: '0.1.0',
  runtimes: ['node', 'browser'],
  requiredCapabilities: ['wifi-scan'],
  description: 'Wi-Fi triangulation via nearby access points',

  // `collect` returns a single RawSignals object: { plugin, timestamp, data }
  async collect(): Promise<RawSignals> {
    const networks = await scanNearbyNetworks();

    return {
      plugin: 'wifi-triangulation',
      timestamp: Date.now() / 1000,
      data: {
        accessPoints: networks.map((network) => ({
          bssid: network.bssid,
          ssid: network.ssid,
          rssi: network.signalStrength,
          frequency: network.frequency,
        })),
      },
    };
  },

  // ... continued below
};

Step 2: Create stamps from signals

  // `create` transforms RawSignals into an unsigned stamp
  async create(signals: RawSignals): Promise<UnsignedLocationStamp> {
    const accessPoints = signals.data.accessPoints as WifiAccessPoint[];

    // Triangulate position from Wi-Fi signals
    const position = triangulateFromAccessPoints(accessPoints);

    return {
      lpVersion: '0.2',
      locationType: 'geojson-point',
      location: {
        type: 'Point',
        coordinates: [position.longitude, position.latitude]
      },
      srs: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84',
      temporalFootprint: { start: signals.timestamp, end: signals.timestamp },
      plugin: 'wifi-triangulation',
      pluginVersion: '0.1.0',
      signals: {
        accessPoints,
        triangulationMethod: 'weighted-centroid'
      }
    };
  },

Step 3: Implement stamp verification

  // `verify` returns a StampVerificationResult:
  // { valid, signaturesValid, structureValid, signalsConsistent, details }
  async verify(stamp: LocationStamp): Promise<StampVerificationResult> {
    const signals = stamp.signals as { accessPoints?: unknown[] };
    const accessPointCount = signals.accessPoints?.length ?? 0;

    // Structure: Wi-Fi triangulation needs at least 3 access points
    const structureValid =
      stamp.plugin === 'wifi-triangulation' && accessPointCount >= 3;

    // Signal consistency: collection window should be tight (≤ 60s)
    const duration = stamp.temporalFootprint.end - stamp.temporalFootprint.start;
    const signalsConsistent = duration <= 60;

    // Signatures
    const signaturesValid = await verifyStampSignatures(stamp);

    return {
      valid: structureValid && signalsConsistent && signaturesValid,
      signaturesValid,
      structureValid,
      signalsConsistent,
      details: {
        accessPointCount,
        collectionDuration: duration,
        signaturesChecked: stamp.signatures.length
      }
    };
  }

Registration

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

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

astral.plugins.register(wifiPlugin);

// Now you can collect stamps using your plugin (collect returns an array)
const signals = await astral.stamps.collect({ plugins: ['wifi-triangulation'] });

const unsigned = await astral.stamps.create(
  { plugin: 'wifi-triangulation' },
  signals[0]
);
const stamp = await astral.stamps.sign({ plugin: 'wifi-triangulation' }, unsigned, signer);

Testing

Test each plugin responsibility independently:

import { describe, it, expect } from 'vitest';

describe('wifi-triangulation plugin', () => {
  it('collects signals from nearby networks', async () => {
    const signals = await wifiPlugin.collect();

    expect(signals.plugin).toBe('wifi-triangulation');
    expect(signals.timestamp).toBeGreaterThan(0);
    expect((signals.data.accessPoints as unknown[]).length).toBeGreaterThan(0);
  });

  it('creates a valid stamp from signals', async () => {
    const signals = mockWifiSignals(5);
    const stamp = await wifiPlugin.create(signals);

    expect(stamp.lpVersion).toBe('0.2');
    expect(stamp.plugin).toBe('wifi-triangulation');
    expect(stamp.location.type).toBe('Point');
    expect(stamp.location.coordinates).toHaveLength(2);
  });

  it('rejects stamps with fewer than 3 access points', async () => {
    const stamp = createMockStamp({ accessPointCount: 2 });
    const result = await wifiPlugin.verify(stamp);

    expect(result.valid).toBe(false);
    expect(result.structureValid).toBe(false);
  });
});

Existing plugins

ProofMode is the plugin that’s working end to end today. The Verify service also includes experimental stamp-verification logic — witnesschain, gpsd, geoclue, wifi-mls, and ip-geolocation — with interfaces defined. We’re keen to develop new ones with partners. Two are highlighted here:

ProofMode

Device attestation and sensor fusion. Uses Secure Enclave (iOS) or hardware keystore (Android) to sign location observations.

WitnessChain

Infrastructure verification using UDP latency triangulation and a challenger network. Trust is intended to derive from speed-of-light constraints and cryptoeconomic incentives.

Each plugin documents its own threat model and trust assumptions. When building a new plugin, you should clearly document what an attacker would need to do to forge a stamp from your system.

Building Verification Plugins

Building verification plugins

What is a plugin?

Plugin interface

How stamps work

Implementation guide

Step 1: Define signal collection

Step 2: Create stamps from signals

Step 3: Implement stamp verification

Registration

Testing

Existing plugins

ProofMode

WitnessChain

Next steps

Location proofs

Verifying location proofs

​Building verification plugins

​What is a plugin?

​Plugin interface

​How stamps work

​Implementation guide

​Step 1: Define signal collection

​Step 2: Create stamps from signals

​Step 3: Implement stamp verification

​Registration

​Testing

​Existing plugins

ProofMode

WitnessChain

​Next steps

Location proofs

Verifying location proofs

Building verification plugins

What is a plugin?

Plugin interface

How stamps work

Implementation guide

Step 1: Define signal collection

Step 2: Create stamps from signals

Step 3: Implement stamp verification

Registration

Testing

Existing plugins

Next steps