Dark Forest Dev Guides
jacob/community
jacob/community
  • Developing for Dark Forest!
  • Connecting to the blockchain
    • What is an RPC endpoint?
    • Changing your RPC endpoint
    • Running your own xDAI node
  • Plugins
    • What is a plugin?
    • Writing your first plugin
    • Porting v0.5 plugins to v0.6
  • Mining
    • What is mining?
    • Sharing map data
    • Running a headless miner
    • Connecting to a remote (headless) miner
  • Developer resources
    • Running a custom client
    • Developing plugins locally
    • 3rd-party contract development
    • Dark Forest subgraph
    • How to query a subgraph
  • SNARKing
    • Running a remote SNARKer
  • Contributing
    • Contributing to this knowledge base
Powered by GitBook
On this page
  • How to query
  • Troubleshooting
  • lower case
  • Leading 0x and padding

Was this helpful?

  1. Developer resources

How to query a subgraph

PreviousDark Forest subgraphNextRunning a remote SNARKer

Last updated 3 years ago

Was this helpful?

is a decentralized protocol for indexing and querying data from blockchains. It makes it possible to query data that is difficult to query directly from the smart contract itself.

For Dark Forest the subgraph acts almost as a read only excel spreadsheet client to the game where you can query for any information that is public in the smart contract.

You might want to familiarize yourself with the of how the game works in order to understand lazy state and what is actually stored in the blockchain.

Like the contract, the subgraph doesn’t know any map data and can’t tell you anything about (x, y) coordinates. Also, like the contract, the subgraph only knows about planets have been interacted with at least once. However UNLIKE the contract, the subgraph DOES apply voyage arrivals as they occur, and therefore has all the most recent ownership data!

How to query

The query language is called graphql and can take some getting used to. Thegraph explorer has a nice right column that allows you to investigate the schema to see what columns and fields are available.

A little guide of a small query getting upgraded to a big one using different commands/properties. This query will show you all the planet ids (well the first 100 by default) that the contract knows about.

{
  planets {
    id
  }
}

Query that shows planets that are foundries (RUINS=Foundries) ordered by their id

{
  planets(where:{planetType:RUINS}) {
    id
  }
}

Query that shows planets that are foundries with their respective level (ordered by their id...)

{
  planets(where:{planetType:RUINS}) {
    id
    planetLevel
  }
}

Query that shows planets that are foundries greater or equal to level 8 with their respective level (ordered by their id...)

{
  planets(where:{planetType:RUINS, planetLevel_gte:8}) {
    id
    planetLevel
  }
}

Query that shows planets that are foundries greater or equal to level 8 with their respective level and the owners id of each foundry

{
  planets(where:{planetType:RUINS, planetLevel_gte:8}) {
    id
    planetLevel
    owner {
      id
    }
  }
}

Query that shows planets that are foundries greater or equal to level 8 with their respective level, owner and coords (Coords only will be shown if the planet has been broadcasted by someone)

{
  planets(where:{planetType:RUINS, planetLevel_gte:8}) {
    id
    planetLevel
    owner {
      id
    }
    x
    y
  }
}

Query that shows planets that are foundries greater or equal to level 8 with their respective level, owner, coords and type of space

{
  planets(where:{planetType:RUINS, planetLevel_gte:8}) {
    id
    planetLevel
    owner {
      id
    }
    x
    y
    spaceType
  }
}

Query that shows planets that are foundries greater or equal to level 8 ordered by their level with their respective level, owner, coords and type of space

{
  planets(where:{planetType:RUINS, planetLevel_gte:8}, orderBy:planetLevel) {
    id
    planetLevel
    owner {
      id
    }
    x
    y
    spaceType
  }
}

Query that shows planets that are foundries greater or equal to level 8 owned by "0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9" ordered by their level with their respective level, owner, coords and type of space

{
  planets(where:{planetType:RUINS, planetLevel_gte:8, owner:"0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9"}, orderBy:planetLevel) {
    id
    planetLevel
    owner {
      id
    }
    x
    y
    spaceType
  }
}

Query that shows the first 10 planets that are foundries greater or equal to level 8 owned by "0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9" ordered by their level with their respective level, owner, coords and type of space

{
  planets(where:{planetType:RUINS, planetLevel_gte:8, owner:"0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9"}, orderBy:planetLevel, first:10) {
    id
    planetLevel
    owner {
      id
     }
     x
     y
     spaceType
   }
 }

Query that shows the planets in the range 101-201 that are foundries greater or equal to level 8 owned by "0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9" ordered by their level with their respective level, owner, coords and type of space

{
  planets(where:{planetType:RUINS, planetLevel_gte:8, owner:"0xb5ce86c2ab9e2403ab47acfbe501845e2480fad9"}, orderBy:planetLevel, first:100, skip:100){
    id
    planetLevel
    owner {
      id
     }
     x
     y
     spaceType
   }
 }

Troubleshooting

lower case

All ids like are lower case like 0x0f45aba574aceba2e0717ca86e910211b34f9db9. Sadly blockscout and metamask can occasionally mix case in ids like 0x0f45aBA574AcEbA2E0717Ca86e910211b34f9db9!

So for example this might return data:

{
  players(where: {id: "0x0f45aba574aceba2e0717ca86e910211b34f9db9"}) {
      id
  }
}

But this won't:

{
  players(where: {id: "0x0f45aBA574AcEbA2E0717Ca86e910211b34f9db9"}) {
      id
  }
}

Leading 0x and padding

User ids (which are actually ethereum wallet addresses) are always shown with a leading 0x and are zero paddded to 42 characters (0x0f45aba574aceba2e0717ca86e910211b34f9db9) . However planet locationId (00000000004896511cb246d2e6dfcde2dccc1b3855fcf69b53e046b09a929953) do NOT use a 0x in front and are 0 padded to 64 characters.

Theres online that can help if you find yourself in this predicimant

The Graph
df wikis more technical explanation
case converters