Create docs for signing & broadcasting txs

docs/core/transactions.md

@@ -141,13 +141,13 @@ simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake
 
 The `Tx` service exposes a handful of utility functions, such as simulating a transaction or querying a transaction, and also one method to broadcast transactions.
 
-An example of broadcasting a transaction is shown in [TODO](https://github.com/cosmos/cosmos-sdk/issues/7657).
+Examples of broadcasting and simulating a transaction are shown [here](../run-node/txs.md#programmatically-with-go).
 
 #### REST
 
 Each gRPC method has its corresponding REST endpoint, generated using [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway). Therefore, instead of using gRPC, you can also use HTTP to broadcast the same transaction, on the `POST /cosmos/tx/v1beta1/txs` endpoint.
 
-An example can be seen [here TODO](https://github.com/cosmos/cosmos-sdk/issues/7657)
+An example can be seen [here](../run-node/txs.md#using-rest)
 
 #### Tendermint RPC
 

docs/migrations/rest.md

@@ -34,7 +34,7 @@ Some important information concerning all legacy REST endpoints:
 
 Thanks to the Protocol Buffers migration in v0.40 we are able to take advantage of a vast number of gRPC tools and solutions. For most of the legacy REST endpoints, Cosmos SDK v0.40 provides new REST endpoints generated from [gRPC `Query` services](../building-modules/query-services.md) using [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/). We usually call them _gGPC-gateway REST endpoints_.
 
-Some modules expose legacy `POST` endpoints to generate unsigned transactions for their `Msg`s. These `POST` endpoints have been removed. We recommend to use [service `Msg`s](../building-modules/msg-services.md) directly, and use Protobuf to do client-side transaction generation. A guide can be found [here (TODO)](https://github.com/cosmos/cosmos-sdk/issues/7657).
+Some modules expose legacy `POST` endpoints to generate unsigned transactions for their `Msg`s. These `POST` endpoints have been removed. We recommend to use [service `Msg`s](../building-modules/msg-services.md) directly, and use Protobuf to do client-side transaction generation. A guide can be found [here](../run-node/txs.md).
 
 | Legacy REST Endpoint                                                            | Description                                                         | New gGPC-gateway REST Endpoint                                                                        |
 | ------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
@@ -98,4 +98,4 @@ Some modules expose legacy `POST` endpoints to generate unsigned transactions fo
 
 ## Migrating to gRPC
 
-Instead of hitting REST endpoints as described in the previous paragraph, the SDK also exposes a gRPC server. Any client can use gRPC instead of REST to interact with the node. An overview of different ways to communicate with a node can be found [here (TODO)](https://github.com/cosmos/cosmos-sdk/issues/7657), and a concrete tutorial for setting up a gRPC client [here (TODO)](https://github.com/cosmos/cosmos-sdk/issues/7657).
+Instead of hitting REST endpoints as described in the previous paragraph, the SDK also exposes a gRPC server. Any client can use gRPC instead of REST to interact with the node. An overview of different ways to communicate with a node can be found [here](../core/grpc_rest.md), and a concrete tutorial for setting up a gRPC client [here](../run-node/txs.md#programmatically-with-go).

docs/run-node/README.md

@@ -9,5 +9,6 @@ parent:
 This folder contains documentation on how to run a node and interact with it.
 
 1. [Setting up the keyring](./keyring.md)
-2. [Running a Node](./run-node.md)
-3. [Interacting with a Node](./interact-node.md)
+1. [Running a Node](./run-node.md)
+1. [Interacting with a Node](./interact-node.md)
+1. [Generating, Signing and Broadcasting Transactions](./txs.md)

docs/run-node/interact-node.md

@@ -31,7 +31,7 @@ RECIPIENT=$(simd keys show recipient -a --keyring-backend test)
 The command above creates a local key-pair that is not yet registered on the chain. An account is created the first time it receives tokens from another account. Now, run the following command to send tokens to the `recipient` account:
 
 ```bash
-simd tx send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain
+simd tx bank send $MY_VALIDATOR_ADDRESS $RECIPIENT 1000stake --chain-id my-test-chain
 
 # Check that the recipient account did receive the tokens.
 simd query account $RECIPIENT --chain-id my-test-chain
@@ -52,12 +52,13 @@ You should see two delegations, the first one made from the `gentx`, and the sec
 
 The Protobuf ecosystem developed tools for different use cases, including code-generation from `*.proto` files into various languages. These tools allow to build clients easily. Often, the client connection (i.e. the transport) can be plugged and replaced very easily. Let's explore one of the most popular transport: [gRPC](../core/grpc_rest.md).
 
-Since the code generation library largely depends on your own tech stack, we will only present two alternatives:
+Since the code generation library largely depends on your own tech stack, we will only present three alternatives:
 
 - `grpcurl` for generic debugging and testing,
+- programmatically via Go,
 - CosmJS for JavaScript/TypeScript developers.
 
-### grpcurl: Reflection, Queries, and Simulation
+### grpcurl
 
 [grpcurl])https://github.com/fullstorydev/grpcurl is like `curl` but for gRPC. It is also available as a Go library, but we will use it only as a CLI command for debugging and testing purposes. Follow the instructions in the previous link to install it.
 
@@ -97,7 +98,7 @@ grpcurl \
 
 The list of all available gRPC query endpoints is [coming soon](https://github.com/cosmos/cosmos-sdk/issues/7786).
 
-### Query for historical state using gRPC
+#### Query for historical state using grpcurl
 
 You may also query for historical data by passing some [gRPC metadata](https://github.com/grpc/grpc-go/blob/master/Documentation/grpc-metadata.md) to the query: the `x-cosmos-block-height` metadata should contain the block to query. Using grpcurl as above, the command looks like:
 
@@ -115,9 +116,91 @@ grpcurl \
 
 Assuming the state at that block has not yet been pruned by the node, this query should return a non-empty response.
 
+### Programmatically via Go
+
+The following snippet shows how to query the state using gRPC inside a Go program. The idea is to create a gRPC connection, and use the Protobuf-generated client code to query the gRPC server.
+
+```go
+import (
+    "context"
+    "fmt"
+
+	"google.golang.org/grpc"
+
+    sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/types/tx"
+)
+
+func queryState() error {
+    myAddress, err := sdk.AccAddressFromBech32("cosmos1...")
+    if err != nil {
+        return err
+    }
+
+    // Create a connection to the gRPC server.
+    grpcConn := grpc.Dial(
+        "127.0.0.1:9090", // Or your gRPC server address.
+        grpc.WithInsecure(), // The SDK doesn't support any transport security mechanism.
+    )
+    defer grpcConn.Close()
+
+    // This creates a gRPC client to query the x/bank service.
+    bankClient := banktypes.NewQueryClient(grpcConn)
+    bankRes, err := bankClient.Balance(
+        context.Background(),
+        &banktypes.QueryBalanceRequest{Address: myAddress, Denom: "atom"},
+    )
+    if err != nil {
+        return err
+    }
+
+    fmt.Println(bankRes.GetBalance()) // Prints the account balance
+
+    return nil
+}
+```
+
+You can replace the query client (here we are using `x/bank`'s) with one generated from any other Protobuf service. The list of all available gRPC query endpoints is [coming soon](https://github.com/cosmos/cosmos-sdk/issues/7786).
+
+#### Query for historical state using Go
+
+Querying for historical blocks is done by adding the block height metadata in the gRPC request.
+
+```go
+import (
+    "context"
+    "fmt"
+
+    "google.golang.org/grpc"
+    "google.golang.org/grpc/metadata"
+
+    grpctypes "github.com/cosmos/cosmos-sdk/types/grpc"
+	"github.com/cosmos/cosmos-sdk/types/tx"
+)
+
+func queryState() error {
+    // --snip--
+
+    var header metadata.MD
+    bankRes, err = bankClient.Balance(
+        metadata.AppendToOutgoingContext(context.Background(), grpctypes.GRPCBlockHeightHeader, "12"), // Add metadata to request
+        &banktypes.QueryBalanceRequest{Address: myAddress, Denom: denom},
+        grpc.Header(&header), // Retrieve header from response
+    )
+    if err != nil {
+        return err
+    }
+    blockHeight = header.Get(grpctypes.GRPCBlockHeightHeader)
+
+    fmt.Println(blockHeight) // Prints the block height (12)
+
+    return nil
+}
+```
+
 ### CosmJS
 
-CosmJS documentation can be found at https://cosmos.github.io/cosmjs/. As of December 2020, CosmJS documentation is still work in progress.
+CosmJS documentation can be found at [https://cosmos.github.io/cosmjs](https://cosmos.github.io/cosmjs). As of January 2021, CosmJS documentation is still work in progress.
 
 ## Using the REST Endpoints
 
@@ -152,4 +235,4 @@ Assuming the state at that block has not yet been pruned by the node, this query
 
 ## Next {hide}
 
-Sending transactions using gRPC and REST requires some additional steps: generating the transaction, signing it, and finally broadcasting it. Read about [generating and signing transactions](TODO https://github.com/cosmos/cosmos-sdk/issues/7657). {hide}
+Sending transactions using gRPC and REST requires some additional steps: generating the transaction, signing it, and finally broadcasting it. Read about [generating and signing transactions](./txs.md). {hide}