diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index e782822b1..970c27264 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -6,7 +6,7 @@ # Getting Started - [Dependencies](./getting-started/dependencies.md) -- [Service Infrastructure](./getting-started/starting-the-fuel-indexer.md) +- [Service Infrastructure](./getting-started/indexer-service-infrastructure.md) - [How it Compares](./getting-started/how-it-compares.md) - [Quickstart](./getting-started/quickstart.md) @@ -21,7 +21,6 @@ - [Scalars](./designing-a-schema/scalars.md) - [Directives](./designing-a-schema/directives.md) - [Relationships](./designing-a-schema/relationships.md) - - [API Server](./designing-a-schema/api-server.md) - [Indexing Fuel Types](./indexing-fuel-types/index.md) - [Blocks](./indexing-fuel-types/blocks.md) - [Transactions](./indexing-fuel-types/transactions.md) @@ -36,7 +35,20 @@ - [A Full Example](./querying/full-example.md) - [Authentication](./authentication/index.md) - [forc index](./forc-index/index.md) + - [auth](./forc-index/auth.md) + - [build](./forc-index/build.md) + - [check](./forc-index/check.md) + - [deploy](./forc-index/deploy.md) + - [kill](./forc-index/kill.md) + - [new](./forc-index/new.md) + - [remove](./forc-index/remove.md) + - [start](./forc-index/start.md) + - [status](./forc-index/status.md) - [forc postgres](./forc-postgres/index.md) + - [create](./forc-postgres/create.md) + - [drop](./forc-postgres/drop.md) + - [start](./forc-postgres/start.md) + - [stop](./forc-postgres/stop.md) # For Contributors diff --git a/docs/src/designing-a-schema/index.md b/docs/src/designing-a-schema/index.md index 606e481ed..9aee8d414 100644 --- a/docs/src/designing-a-schema/index.md +++ b/docs/src/designing-a-schema/index.md @@ -19,12 +19,12 @@ While we do our best to maintain compliance with the GraphQL specification and p | Functionality | Status | Notes | |------|----------|-------| -| Arguments | ✅ | [read the Search and Filtering section](./search-filtering.md) | +| Arguments | ✅ | [read the Search and Filtering section](../querying/search-and-filtering.md) | | Aliases | ✅ | | | Fragments | ✅ | inline fragments are currently not supported | | Introspection | ✅ | | -| GraphQL Playground | ✅ | [read the Playground section](./playground.md) | -| Pagination | ✅ | [read the Pagination section](./pagination.md) | +| GraphQL Playground | ✅ | [read the Playground section](../querying/playground.md) | +| Pagination | ✅ | [read the Pagination section](../querying/pagination.md) | | Directives | 🚧 | [read the Directives section](./directives.md) | | List Types | 🚧 | | | Union Types | 🚧 | | diff --git a/docs/src/designing-a-schema/types.md b/docs/src/designing-a-schema/types.md index df3c51466..98326a7a9 100644 --- a/docs/src/designing-a-schema/types.md +++ b/docs/src/designing-a-schema/types.md @@ -2,7 +2,7 @@ ## Objects -Object types are the most commonly used type in indexer GraphQL schema. Each object type marked with an `@entity` directive will be converted into a SQL table. +Object types are the most commonly used type in indexer GraphQL schema. Each object type marked with an `@entity` directive will be converted into a SQL table. ```graphql type Account @entity { @@ -56,7 +56,7 @@ mod indexer_mod { ## Unions -Union types are unique in that any type marked as a `union` will be converted into an Object type, who's fields are the unique set of fields over all members of the union. +Union types are unique in that any type marked as a `union` will be converted into an Object type, who's fields are the unique set of fields over all members of the union. ```graphql enum TransactionLabel { diff --git a/docs/src/forc-index/index.md b/docs/src/forc-index/index.md index c582b7aa9..45bc1cf14 100644 --- a/docs/src/forc-index/index.md +++ b/docs/src/forc-index/index.md @@ -15,12 +15,16 @@ OPTIONS: -V, --version Print version information SUBCOMMANDS: - build Build an indexer - check Get status checks on all indexer components - deploy Deploy an indexer asset bundle to a remote or locally running indexer server - help Print this message or the help of the given subcommand(s) - init Create a new indexer project in the current directory - new Create a new indexer project in a new directory - remove Stop and remove a running indexer - start Start a local indexer service + auth Authenticate against an indexer service + build Build an indexer + check Check for Fuel indexer components + deploy Deploy an indexer to an indexer service + help Print this message or the help of the given subcommand(s) + kill Kill the indexer process. Note that this command will kill any process listening + on the default indexer port or the port specified by the `--port` flag + new Create a new indexer project in a new directory + postgres Fuel Postgres Orchestrator + remove Stop and remove a running indexer + start Standalone binary for the Fuel indexer service + status Check the status of a registered indexer ``` diff --git a/docs/src/getting-started/how-it-compares.md b/docs/src/getting-started/how-it-compares.md index fc4935396..431be13c8 100644 --- a/docs/src/getting-started/how-it-compares.md +++ b/docs/src/getting-started/how-it-compares.md @@ -1,6 +1,7 @@ # How it compares Legend: + - 🟩 : Functionally complete - 🟨 : Partially complete - 🟥 : Planned but incomplete @@ -8,10 +9,9 @@ Legend: - | Feature | The Graph | Fuel Indexer | Notes | |:-:|:-:|:-:|:-:| | Decentralized Hosting | 🟩 | ⛔ | | | Hosted Indexers | 🟩 | 🟩 | | | WASM Execution | 🟩 | 🟩 | | -| Native Execution | 🟥 | 🟩 | | \ No newline at end of file +| Native Execution | 🟥 | 🟩 | | diff --git a/docs/src/getting-started/indexer-service-infrastructure.md b/docs/src/getting-started/indexer-service-infrastructure.md index d14bd4604..e77ba16ed 100644 --- a/docs/src/getting-started/indexer-service-infrastructure.md +++ b/docs/src/getting-started/indexer-service-infrastructure.md @@ -147,12 +147,11 @@ OPTIONS: {{#include ../../../config.yaml}} ``` - ## Web API Server The `fuel-indexer-api-server` crate of the Fuel indexer contains a standalone web API server that acts as a queryable endpoint on top of the database. Note that the main `fuel-indexer` binary of the indexer project also contains the same web API endpoint. -> The `fuel-indexer-api-server` crate offers a _standalone_ web API endpoint, whereas the API endpoint offered in `fuel-indexer` is bundled with other Fuel indexer functionality (e.g., execution, handling, data-layer construction, etc). Offering the API server as a separate piece allows users to separate components and run them on different systems, if desired. +> The `fuel-indexer-api-server` crate offers a _standalone_ web API endpoint, whereas the API endpoint offered in `fuel-indexer` is bundled with other Fuel indexer functionality (e.g., execution, handling, data-layer construction, etc). Offering the API server as a separate piece allows users to separate components and run them on different systems, if desired. ### Usage diff --git a/docs/src/getting-started/quickstart.md b/docs/src/getting-started/quickstart.md index 316730bc9..6d8d2367b 100644 --- a/docs/src/getting-started/quickstart.md +++ b/docs/src/getting-started/quickstart.md @@ -102,7 +102,7 @@ To quickly setup and bootstrap the PostgreSQL database that we'll need, we'll us We can quickly create a bootstrapped database and start the Fuel indexer service by running the following command: -> IMPORTANT: Below we're specifying our Postgres hostname as `--postgres-host postgresql`, but you might need to change this based on your own Postgres instance details (see `forc index start --help` for more details). +> IMPORTANT: Below we're specifying our Postgres hostname as `--postgres-host postgresql`, but you might need to change this based on your own Postgres instance details (see `forc index start --help` for more details). > > Additionally, you can try using the `--embedded-database` flag in order to quickly use an embedded instance of Postgres, but this flag can be flaky, and its ease of use often depends on what platform you're using. diff --git a/docs/src/indexing-custom-types/index.md b/docs/src/indexing-custom-types/index.md index 7deeea0e5..2c4045d64 100644 --- a/docs/src/indexing-custom-types/index.md +++ b/docs/src/indexing-custom-types/index.md @@ -1,6 +1,6 @@ # Custom Types -In addition to Fuel-specific types, you can also index custom Sway types as well. To index custom types from a Sway smart contract, you'll need that contract's ABI in JSON format; the JSON ABI is generated as a result of running `forc build` to build your contract. After that, the process is similar to [indexing Fuel types](./indexing-fuel-types.md). +In addition to Fuel-specific types, you can also index custom Sway types as well. To index custom types from a Sway smart contract, you'll need that contract's ABI in JSON format; the JSON ABI is generated as a result of running `forc build` to build your contract. After that, the process is similar to [indexing Fuel types](../indexing-fuel-types/index.md). Let's go over an example. @@ -32,7 +32,7 @@ abi ValueStore { } storage { - total: u64 = 1000, + total: u64 = 1000, } impl ValueStore for Contract { @@ -197,6 +197,7 @@ resumable: true ## Handler Logic Finally, we can create handlers to index these particular types and store them in the database. Let's look at the following example: + ```rust, ignore use fuel_indexer_utils::prelude::*; diff --git a/docs/src/indexing-fuel-types/blocks.md b/docs/src/indexing-fuel-types/blocks.md index 8de077136..df89e8f23 100644 --- a/docs/src/indexing-fuel-types/blocks.md +++ b/docs/src/indexing-fuel-types/blocks.md @@ -29,4 +29,4 @@ mod indexer_mod { info!("This block #{height}"); } } -``` \ No newline at end of file +``` diff --git a/docs/src/indexing-fuel-types/receipts.md b/docs/src/indexing-fuel-types/receipts.md index 16d805ab8..39836aa9c 100644 --- a/docs/src/indexing-fuel-types/receipts.md +++ b/docs/src/indexing-fuel-types/receipts.md @@ -261,8 +261,7 @@ mod indexer_mod { ## Return -A `Return` receipt is generated when returning a non-reference type in a Sway contract, specifically `bool`, `u8`, `u16`, `u32`, and `u64`. The `val` field includes the value being returned. -- [Read more about `Return` in the Fuel protocol spec](https://docs.fuel.network/docs/specs/abi/receipts/#return-receipt). +A `Return` receipt is generated when returning a non-reference type in a Sway contract, specifically `bool`, `u8`, `u16`, `u32`, and `u64`. The `val` field includes the value being returned. [Read more about `Return` in the Fuel protocol spec](https://docs.fuel.network/docs/specs/abi/receipts/#return-receipt). ```rust, ignore use fuel_types::ContractId; @@ -274,7 +273,6 @@ pub struct Return { } ``` - You can handle functions that produce a `Return` receipt type by adding a parameter with the type `Return`. ```rust, ignore @@ -339,8 +337,6 @@ pub struct Revert { | FailedAssertEq | 3 | | FailedAssert | 4 | - - ```rust, ignore extern crate alloc; use fuel_indexer_utils::prelude::*; diff --git a/docs/src/indexing-fuel-types/transactions.md b/docs/src/indexing-fuel-types/transactions.md index 42c7ee134..e3a1e787d 100644 --- a/docs/src/indexing-fuel-types/transactions.md +++ b/docs/src/indexing-fuel-types/transactions.md @@ -1,3 +1,4 @@ + # Transactions ## `TransactionData` @@ -39,7 +40,6 @@ mod indexer_mod { ``` - ## `TransactionStatus` `TransactionStatus` refers to the status of a `Transaction` in the Fuel network. diff --git a/docs/src/project-components/module.md b/docs/src/project-components/module.md index 6c224c084..cf259f8fc 100644 --- a/docs/src/project-components/module.md +++ b/docs/src/project-components/module.md @@ -24,10 +24,8 @@ mod indexer_mod { The first line imports the [prelude](https://docs.rs/fuel-indexer-utils/latest/fuel_indexer_utils/prelude/index.html) from `fuel_indexer_utils`; this allows you to quickly bootstrap an indexer by using common types and traits. Then, we have a module decorated with the `#[indexer]` macro. This macro processes a manifest at the supplied file path, parses your schema and Sway contract ABI (if supplied), and generates code that is combined with handler functions in order to create a complete indexer module. - Finally, we have an example handler function. You can define which functions handle different events by using the function parameters. If you add a function parameter of a certain type `T`, the function will be triggered whenever that type is found as part of a block, transaction, or receipt. In this example, let's say that you have a Sway contract with a function that logs a `Greeting` struct. When that function executes as part of a transaction, the logged struct will be included in the data that is processed from the Fuel blockchain. Your indexer module will see the struct and execute `log_the_greeting`. - > You can learn more about what data can be indexed and find example handlers in the [Indexing Fuel Types](../indexing-fuel-types/index.md) and [Indexing Custom Types](../indexing-custom-types/index.md) sections. --- @@ -47,12 +45,12 @@ After that, you can conveniently use the [`forc index`](./../forc-index/index.md > There are a few points that Fuel indexer users should know when using WASM: > > 1. WASM modules are only used if the execution mode specified in your manifest file is `wasm`. -> +> > 2. Developers should be aware of what things may not work off-the-shelf in a module: file I/O, thread spawning, and anything that depends on system libraries or makes system calls. This is due to the technological limitations of WASM as a whole; more information can be found [here](https://rustwasm.github.io/docs/book/reference/which-crates-work-with-wasm.html). > > 3. As of this writing, there is a small bug in newly built Fuel indexer WASM modules that produces a WASM runtime error due to an errant upstream dependency. For now, a quick workaround requires the use of `wasm-snip` to remove the errant symbols from the WASM module. More info can be found in the related script [here](https://github.com/FuelLabs/fuel-indexer/blob/develop/scripts/stripper.bash). > > 4. Users on Apple Silicon macOS systems may experience trouble when trying to build WASM modules due to its `clang` binary not supporting WASM targets. If encountered, you can install a binary with better support from Homebrew (`brew install llvm`) and instruct `rustc` to leverage it by setting the following environment variables: -> +> > - `AR=/opt/homebrew/opt/llvm/bin/llvm-ar` > - `CC=/opt/homebrew/opt/llvm/bin/clang` diff --git a/docs/src/project-components/schema.md b/docs/src/project-components/schema.md index d661538ef..ef3e7df05 100644 --- a/docs/src/project-components/schema.md +++ b/docs/src/project-components/schema.md @@ -24,9 +24,8 @@ type Wallet @entity { } ``` -For a complete list of all scalars that can be used in a Fuel indexer, please see the [GraphQL Scalars](./../graphql/scalars.md) section. +For a complete list of all scalars that can be used in a Fuel indexer, please see the [GraphQL Scalars](../designing-a-schema/scalars.md) section. -Further, for a complete list of how Sway data types, GraphQL scalar types, and Fuel indexer database types map to each other, please see the [Database Types](./../database/index.md) section. +Further, for a complete list of how Sway data types, GraphQL scalar types, and Fuel indexer database types map to each other, please see the [Database Types](../storing-records/index.md) section. - -Finally, for a more in-depth explanation on the schema being used above 👆🏽, please read the [GraphQL](./../graphql/index.md) section. +Finally, for a more in-depth explanation on the schema being used above 👆🏽, please read the [GraphQL](./../designing-a-schema/index.md) section. diff --git a/docs/src/querying/basic-queries.md b/docs/src/querying/basic-queries.md index cd77d3db6..d2498bf73 100644 --- a/docs/src/querying/basic-queries.md +++ b/docs/src/querying/basic-queries.md @@ -1,6 +1,6 @@ # Queries -Once data has been persisted into your storage backend, you can retrieve it by querying the [GraphQL API server](./api-server.md). By default, the API server can be reached at `http://localhost:29987/api/graph/:namespace/:identifier`, where `:namespace` and `:identifier` are the values for the respective fields in your indexer's manifest. If you've changed the `WEB_API_HOST` or `WEB_API_PORT` values of your configuration, then you'll need to adjust the URL accordingly. +Once data has been persisted into your storage backend, you can retrieve it by querying the [GraphQL API server](../project-components/indexer-service-infrastructure.md). By default, the API server can be reached at `http://localhost:29987/api/graph/:namespace/:identifier`, where `:namespace` and `:identifier` are the values for the respective fields in your indexer's manifest. If you've changed the `WEB_API_HOST` or `WEB_API_PORT` values of your configuration, then you'll need to adjust the URL accordingly. ## Basic Query @@ -63,7 +63,7 @@ We're requesting the ID, height, and timestamp for each block stored in the back ## Nested Query -The Fuel indexer supports [foreign keys](./relationships.md) on entity types; thus, you can also ask for information about a referenced entity inside of your query. A nested query has the following general structure: +The Fuel indexer supports [foreign keys](../designing-a-schema/relationships.md) on entity types; thus, you can also ask for information about a referenced entity inside of your query. A nested query has the following general structure: ```graphql query { @@ -112,7 +112,7 @@ type Character @entity { } ``` -This schema uses implicit foreign keys to reference other entities; for more information on implicit and explicit foreign keys, please refer to the [Relationships](./relationships.md) section of the book. In this contrived example, we're storing information about characters that are found in books which are stored in libraries that can be found in cities. This will be the query that we use to retrieve the aforementioned data: +This schema uses implicit foreign keys to reference other entities; for more information on implicit and explicit foreign keys, please refer to the [Relationships](../designing-a-schema/relationships.md) section of the book. In this contrived example, we're storing information about characters that are found in books which are stored in libraries that can be found in cities. This will be the query that we use to retrieve the aforementioned data: ```graphql query { diff --git a/docs/src/querying/index.md b/docs/src/querying/index.md index 78725bf1c..bfcfe24dd 100644 --- a/docs/src/querying/index.md +++ b/docs/src/querying/index.md @@ -1,7 +1,7 @@ # Queries -- [Basic Queries](./queries.md) +- [Basic Queries](./basic-queries.md) - [Pagination](./pagination.md) -- [Search & Filtering](./search-filtering.md) +- [Search & Filtering](./search-and-filtering.md) - [Full Example](./full-example.md) - [The GraphQL Playground](./playground.md) diff --git a/docs/src/querying/playground.md b/docs/src/querying/playground.md index 5e645a77b..ec2ed5f42 100644 --- a/docs/src/querying/playground.md +++ b/docs/src/querying/playground.md @@ -6,10 +6,8 @@ Every public indexer can access the GraphQL playground of the Fuel indexer node ## Usage -To use the GraphQL playground to explor your indices, simply [start your indexer service](../getting-started/starting-the-fuel-indexer.md) - then open the following URL in your browser - where `namespace` and `identifier` correspond to the namespace and identifier of the index that you'd like to explore. +To use the GraphQL playground to explor your indices, simply [start your indexer service](../getting-started/indexer-service-infrastructure.md) - then open the following URL in your browser - where `namespace` and `identifier` correspond to the namespace and identifier of the index that you'd like to explore. ```bash http://localhost:29987/api/playground/:namespace/:identifier ``` - -> NOTE: On initial page render, the playground throws a 500. Don't worry about this, you should still be able to query.