Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Remove deprecated "Interfaces" section #8294

Merged
merged 14 commits into from
Jan 18, 2021
5 changes: 3 additions & 2 deletions docs/basics/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ This repository contains reference documentation on the basic concepts of the Co

1. [Anatomy of an SDK Application](./app-anatomy.md)
2. [Lifecycle of a transaction](./tx-lifecycle.md)
3. [Accounts](./accounts.md)
4. [Gas and Fees](./gas-fees.md)
3. [Lifecycle of a query](./query-lifecycle.md)
4. [Accounts](./accounts.md)
5. [Gas and Fees](./gas-fees.md)

After reading the basics, head on to the [Core Reference](../core/README.md) for more advanced material.
2 changes: 1 addition & 1 deletion docs/basics/accounts.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!--
order: 3
order: 4
-->

# Accounts
Expand Down
6 changes: 3 additions & 3 deletions docs/basics/app-anatomy.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ Here are descriptions of what each of the four fields means:
- `TxConfig`: `TxConfig` defines an interface a client can utilize to generate an application-defined concrete transaction type. Currently, the SDK handles two transaction types: `SIGN_MODE_DIRECT` (which uses Protobuf binary as over-the-wire encoding) and `SIGN_MODE_LEGACY_AMINO_JSON` (which depends on Amino). Read more about transactions [here](../core/transactions.md).
- `Amino`: Some legacy parts of the SDK still use Amino for backwards-compatibility. Each module exposes a `RegisterLegacyAmino` method to register the module's specific types within Amino. This `Amino` codec should not be used by app developers anymore, and will be removed in future releases.

The SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`.
The SDK exposes a `MakeTestEncodingConfig` function used to create a `EncodingConfig` for the app constructor (`NewApp`). It uses Protobuf as a default `Marshaler`.
NOTE: this function is marked deprecated and should only be used to create an app or in tests. We are working on refactoring codec management in a post Stargate release.

See an example of a `MakeTestEncodingConfig` from `simapp`:
Expand Down Expand Up @@ -160,7 +160,7 @@ Each module should also implement the `RegisterServices` method as part of the [

### gRPC `Query` Services

gRPC `Query` services are introduced in the v0.40 Stargate release. They allow users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configued under the `grpc.enable` and `grpc.address` fields inside `app.toml`.
gRPC `Query` services are introduced in the v0.40 Stargate release. They allow users to query the state using [gRPC](https://grpc.io). They are enabled by default, and can be configued under the `grpc.enable` and `grpc.address` fields inside [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml).

gRPC `Query` services are defined in the module's Protobuf definition files, specifically inside `query.proto`. The `query.proto` definition file exposes a single `Query` [Protobuf service](https://developers.google.com/protocol-buffers/docs/proto#services). Each gRPC query endpoint corresponds to a service method, starting with the `rpc` keyword, inside the `Query` service.

Expand Down Expand Up @@ -208,7 +208,7 @@ Some external clients may not wish to use gRPC. The SDK provides in this case a

The REST endpoints are defined in the Protobuf files, along with the gRPC services, using Protobuf annotations. Modules that want to expose REST queries should add `google.api.http` annotations to their `rpc` methods. By default, all REST endpoints defined in the SDK have an URL starting with the `/cosmos/` prefix.

The SDK also provides a development endpoint to generate [Swagger](https://swagger.io/) definition files for these REST endpoints. This endpoint can be enabled inside the `app.toml` config file, under the `api.swagger` key.
The SDK also provides a development endpoint to generate [Swagger](https://swagger.io/) definition files for these REST endpoints. This endpoint can be enabled inside the [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) config file, under the `api.swagger` key.

#### Legacy API REST Endpoints

Expand Down
2 changes: 1 addition & 1 deletion docs/basics/gas-fees.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!--
order: 4
order: 5
-->

# Gas and Fees
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!--
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moving query-lifecycle to basics

order: 2
order: 3
-->

# Query Lifecycle
Expand All @@ -8,7 +8,7 @@ This document describes the lifecycle of a query in a SDK application, from the

## Pre-requisite Readings

* [Introduction to Interfaces](./interfaces-intro.md) {prereq}
- [Introduction to Interfaces](./interfaces-intro.md) {prereq}

## Query Creation

Expand Down Expand Up @@ -36,7 +36,7 @@ appcli query [moduleName] [command] <arguments> --flag <flagArg>

To provide values such as `--node` (the full-node the CLI connects to), the user can use the `config` command to set themn or provide them as flags.

The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](./cli.md#root-command) (`appcli`), the type of command (`query`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there.
The CLI understands a specific set of commands, defined in a hierarchical structure by the application developer: from the [root command](./cli.md#root-command) (`appcli`), the type of command (`query`), the module that contains the command (`staking`), and command itself (`delegations`). Thus, the CLI knows exactly which module handles this command and directly passes the call there.

### REST

Expand Down Expand Up @@ -64,14 +64,14 @@ The interactions from the users' perspective are a bit different, but the underl

The first thing that is created in the execution of a CLI command is a `Context`, while the REST Server directly provides a `Context` for the REST Request handler. A [Context](../core/context.md) is an immutable object that stores all the data needed to process a request on the user side. In particular, a `Context` stores the following:

* **Codec**: The [encoder/decoder](../core/encoding.md) used by the application, used to marshal the parameters and query before making the Tendermint RPC request and unmarshal the returned response into a JSON object.
* **Account Decoder**: The account decoder from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/spec) module, which translates `[]byte`s into accounts.
* **RPC Client**: The Tendermint RPC Client, or node, to which the request will be relayed to.
* **Keybase**: A [Key Manager](../basics/accounts.md#keybase) used to sign transactions and handle other operations with keys.
* **Output Writer**: A [Writer](https://golang.org/pkg/io/#Writer) used to output the response.
* **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query and `--indent`, which indicates to add an indent to the JSON response.
- **Codec**: The [encoder/decoder](../core/encoding.md) used by the application, used to marshal the parameters and query before making the Tendermint RPC request and unmarshal the returned response into a JSON object.
- **Account Decoder**: The account decoder from the [`auth`](https://github.com/cosmos/cosmos-sdk/tree/master/x/auth/spec) module, which translates `[]byte`s into accounts.
- **RPC Client**: The Tendermint RPC Client, or node, to which the request will be relayed to.
- **Keybase**: A [Key Manager](../basics/accounts.md#keybase) used to sign transactions and handle other operations with keys.
- **Output Writer**: A [Writer](https://golang.org/pkg/io/#Writer) used to output the response.
- **Configurations**: The flags configured by the user for this command, including `--height`, specifying the height of the blockchain to query and `--indent`, which indicates to add an indent to the JSON response.

The `Context` also contains various functions such as `Query()` which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node.
The `Context` also contains various functions such as `Query()` which retrieves the RPC Client and makes an ABCI call to relay a query to a full-node.

+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/client/context/context.go#L23-L47

Expand Down Expand Up @@ -147,13 +147,13 @@ Since `Query()` is an ABCI function, `baseapp` returns the response as an [`abci

### CLI Response

The application [`codec`](../core/encoding.md) is used to unmarshal the response to a JSON and the `Context` prints the output to the command line, applying any configurations such as `--indent`.
The application [`codec`](../core/encoding.md) is used to unmarshal the response to a JSON and the `Context` prints the output to the command line, applying any configurations such as `--indent`.

+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/staking/client/cli/query.go#L252-L293

### REST Response

The [REST server](./rest.md#rest-server) uses the `Context` to format the response properly, then uses the HTTP package to write the appropriate response or error.
The [REST server](./rest.md#rest-server) uses the `Context` to format the response properly, then uses the HTTP package to write the appropriate response or error.

+++ https://github.com/cosmos/cosmos-sdk/blob/7d7821b9af132b0f6131640195326aa02b6751db/x/staking/client/rest/utils.go#L115-L148

Expand Down
4 changes: 2 additions & 2 deletions docs/building-modules/module-interfaces.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,9 +126,9 @@ service Query{
}
```

gRPC gateway is started in-process along with the application and Tendermint. It can be enabled or disabled by setting gRPC Configuration `enable` in `app.toml`.
gRPC gateway is started in-process along with the application and Tendermint. It can be enabled or disabled by setting gRPC Configuration `enable` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml).

The SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in `app.toml` defines if swagger documentation should be automatically registered.
The SDK provides a command for generating [Swagger](https://swagger.io/) documentation (`protoc-gen-swagger`). Setting `swagger` in [`app.toml`](../run-node/run-node.md#configuring-the-node-using-apptoml) defines if swagger documentation should be automatically registered.

## Legacy REST

Expand Down
11 changes: 6 additions & 5 deletions docs/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,12 @@ This repository contains reference documentation on the core concepts of the Cos
5. [Store](./store.md)
6. [Encoding](./encoding.md)
7. [gRPC, REST and Tendermint Endpoints](./grpc_rest.md)
8. [Events](./events.md)
9. [Telemetry](./telemetry.md)
10. [Object-Capabilities](./ocap.md)
11. [RunTx recovery middleware](./runtx_middleware.md)
12. [Protobuf documentation](./proto-docs.md)
8. [Command-Line Interface](./cli.md)
9. [Events](./events.md)
10. [Telemetry](./telemetry.md)
11. [Object-Capabilities](./ocap.md)
12. [RunTx recovery middleware](./runtx_middleware.md)
13. [Protobuf documentation](./proto-docs.md)

After reading about the core concepts, check the [IBC documentation](../ibc/README.md) to learn more
about the IBC core concepts and how to integrate it to you application.
Loading