Location Records

Location data that serves as input to geospatial operations

Research Preview — Under active development.

Location Records

Location records are the inputs to geospatial operations. They represent spatial data — points, polygons, routes, or any geometry — that Astral can compute against.

Supported Input Types

Astral currently supports two types of location records:

1. Location Attestations — EAS attestations conforming to the Location Protocol v0.2 schema
2. Raw GeoJSON — Unsigned geometry data for reference locations or prototyping

We plan to expand support for other location record formats in the future, including AT Protocol location lexicon records and other standards.

Location Attestations

Location Attestations are signed spatial records stored as EAS attestations. They contain:

• Geometry: The spatial data (GeoJSON format)
• Metadata: Optional descriptive information
• Signature: Cryptographic proof of the attester’s identity

Code snippets need testing — Verify against actual implementation before use.

// Creating a location attestation
const landmark = await astral.location.create({
  type: 'Point',
  coordinates: [2.2945, 48.8584]
}, {
  chainId: 84532,
  submitOnchain: true,
  metadata: {
    name: "Eiffel Tower",
    description: "Iconic Paris landmark"
  }
});

console.log(landmark.uid);  // 0xabc123...

Storage Options

Location Attestations can be stored onchain or offchain:

Onchain Attestations

• Stored on EAS contracts
• Referenced by UID alone
• Higher gas cost
• Permanent, immutable

Offchain Attestations

• Stored on IPFS, servers, etc.
• Referenced by UID + URI
• No gas cost to create
• EIP-712 signed

Onchain

// Create onchain attestation
const location = await astral.location.create(geojson, {
  submitOnchain: true
});

// Reference by UID only
await astral.compute.distance(location.uid, otherUID);

Offchain

// Create offchain attestation
const location = await astral.location.create(geojson, {
  submitOnchain: false,
  storage: 'ipfs'  // or 'arweave', 'https', etc.
});

// Reference by UID + URI
await astral.compute.distance(
  { uid: location.uid, uri: location.uri },
  otherUID
);

Schema

Location Attestations follow the Location Protocol v0.2 schema:

Verification in progress — We are actively verifying that deployed schemas conform to Location Protocol v0.2. There may be inconsistencies between the documentation, deployed schemas, and the spec. See GitHub issue #11 for status.

Field	Type	Description
lp_version	string	Location Protocol version (e.g., “0.2”)
location_type	string	The type of location data (e.g., “GeoJSON”)
location	bytes	Encoded location data
srs	string	Spatial reference system as OGC URI

Using Location Attestations

Location Attestations serve as inputs to geospatial operations:

// As direct UID (onchain attestation)
const result = await astral.compute.distance(
  '0xabc123...',  // UID of first location
  '0xdef456...'   // UID of second location
);

// As UID + URI (offchain attestation)
const result = await astral.compute.contains(
  { uid: '0xabc123...', uri: 'ipfs://Qm...' },
  userLocationUID
);

// As inline attestation object
const result = await astral.compute.within(
  { attestation: signedOffchainAttestation },
  landmarkUID,
  500
);

Raw GeoJSON Alternative

You can also use raw GeoJSON without creating an attestation first:

// Raw GeoJSON as input
const result = await astral.compute.contains(
  {
    type: 'Polygon',
    coordinates: [[[...]]]  // SF Bay Area boundary
  },
  userLocationUID
);

Raw GeoJSON is not attested. The Policy Attestation proves “Astral computed the relationship between inputs A and B” but does NOT prove who signed those geometries. Use raw GeoJSON for reference geometries (official boundaries) or prototyping.

Fetching Location Attestations

// Get by UID
const location = await astral.location.get('0xabc123...');
console.log(location.geometry);  // { type: 'Point', coordinates: [...] }

// Query with filters
const locations = await astral.location.query({
  bbox: [-122.5, 37.7, -122.4, 37.8],  // Bounding box
  limit: 100
});

Coordinate System

Location Attestations honor the srs field, using OGC URIs per Location Protocol v0.2:

• Default: http://www.opengis.net/def/crs/OGC/1.3/CRS84 (WGS84, lon/lat order)
• Custom: Any OGC CRS URI supported by PostGIS

Coordinates should be in [longitude, latitude] order (GeoJSON standard).

Next: Geospatial Operations

Learn about the spatial computations you can perform