Off-Chain Data Usage

Updated 2022-09-12

As the GSR supports looking up and checking placement data on-chain, it can be used by other smart contracts. However, its main function is to provide shared, trusted data that off-chain Dapps can use to display placements. There are a few way that Illust and other Dapp creators can use and search GSR data:

Map Display

As the GSR is a public registry of digital asset placements, that data can be displayed by any interested application. Marketplaces may choose to display the locations of individual assets on their lot pages, or of all assets on their contract on a map. Illust, which provides a WebAR application for viewing geolocated NFTs in Augmented Reality, will also list all GSR placements on its global map. So simply by declaring a position, the NFT will automatically appear in AR at the designated location, with the specified scene.


While all data in the GSR is publicly available on the blockchain, more complex queries - like Placements within an arbitrary geofence, enumeration of assets by owner or contract, or Placement history - would not be gas-efficient to perform on-chain.

To facilitate this, every Placement will emit a GsrPlacement event, which Illust (or others) can watch for and react to. The GsrPlacement event will include the EncodedAssetId, the geohash of the location, the scene_uri metadata, and the address publishing the event. It is incumbent upon the consumer of this data to verify that the publishing address is the current owner of the NFT, and to ignore the event otherwise.

To make querying and searching placement data easier, Illust will provide a public API on top of the Indexer service. But other services may also offer an indexer service, as they will all be built on top of the same shared source of truth.

Embedding NFT Placement UI

To improve adoption of the GSR, Illust will also provide an SDK that makes it easy to display GSR position data for a given NFT on a marketplace or other site. This will consist of two parts:


This web component will take as parameters an NFT identifier and a web3.js or ethers.js provider, and use them to query for the current owner, query the GSR for the current position, and display it as the geocoded street address of the described NFT.


To align the community on shared AssetType decoding standards, Illust will publish an open-source GSR SDK TypeScript NPM package, which will have an AssetTypeHandler class defined for each AssetType. To add a new chain (like Solana), data source (like Steam), or other asset type (like a new EVM NFT standard), someone can submit a PR implementing encoding, decoding, and ownership validation for the asset type. Once the PR is accepted and published, consumers of GSR data can easily submit these assets, and indexer services and Dapps using the SDK can read and verify them.

This SDK will also allow consuming Dapps to work solely with DecodedAssetId data structures, rather than having to manually encode them to interact with the contract.

In both cases, these libraries will allow marketplaces to easily integrate functionality to allow asset owners to geolocate their assets without leaving the marketplace, and integrate with the marketplace’s existing Web3 wallet connections.


Last updated