[Docs] AAT related comments & documentation improvements (#1598)

This PR is the result of reviewing the codebase to answer AAT-related questions for the backend & infra teams at grove. As a result, the following changes were made: - Reformat (automatically) a handful of files using [goimports-reviser](https://github.com/incu6us/goimports-reviser) - Update comments in some parts of the source code related to AATs - Update the documentation related to generating and using AATs - Build a reference upon which the foundation will update the official documentation at [pokt-network/docs-v2](https://github.com/pokt-network/docs-v2) General quality-of-life improvements for documentation, comments and code health. --------- Co-authored-by: 0xThresh <104535511+0xThresh@users.noreply.github.com> Co-authored-by: tokikuch <msmania@users.noreply.github.com>
pokt-network · Mar 13, 2024 · 93592fa · 93592fa
1 parent 57ab4c7
commit 93592fa
Show file tree

Hide file tree

Showing 30 changed files with 366 additions and 208 deletions.
diff --git a/app/cmd/cli/app.go b/app/cmd/cli/app.go
@@ -9,10 +9,11 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/spf13/cobra"
+
 	"github.com/pokt-network/pocket-core/app"
 	"github.com/pokt-network/pocket-core/crypto/keys/mintkey"
 	"github.com/pokt-network/pocket-core/types"
-	"github.com/spf13/cobra"
 )
 
 func init() {
@@ -26,7 +27,7 @@ func init() {
 var appCmd = &cobra.Command{
 	Use:   "apps",
 	Short: "application management",
-	Long: `The apps namespace handles all applicaiton related interactions,
+	Long: `The apps namespace handles all application related interactions,
 from staking and unstaking; to generating AATs.`,
 }
 
@@ -179,10 +180,15 @@ command, you must have the private key of the current staked app <fromAddr>
 var createAATCmd = &cobra.Command{
 	Use:   "create-aat <appAddr> <clientPubKey>",
 	Short: "Creates an application authentication token",
-	Long: `Creates a signed application authentication token (version 0.0.1 of the AAT spec), that can be embedded into application software for Relay servicing.
-Will prompt the user for the <appAddr> account passphrase.
-Read the Application Authentication Token documentation for more information.
-NOTE: USE THIS METHOD AT YOUR OWN RISK. READ THE APPLICATION SECURITY GUIDELINES IN ORDER TO UNDERSTAND WHAT'S THE RECOMMENDED AAT CONFIGURATION FOR YOUR APPLICATION.`,
+	Long: `Creates a signed Application Authentication Token.
+Creates a signed AAT (= Application Authentication Token) where the version is
+hardcoded as "0.0.1" that is the only version supported by the protocol.
+
+This command prompts you to input the <appAddr> account passphrase.
+When you send a relay request with AAT, <appAddr> needs to be a staked
+application.
+
+Please read doc/specs/application-auth-token.md for additional details.`,
 	Args: cobra.ExactArgs(2),
 	Run: func(cmd *cobra.Command, args []string) {
 		app.InitConfig(datadir, tmNode, persistentPeers, seeds, remoteCLIURL)
@@ -203,15 +209,22 @@ NOTE: USE THIS METHOD AT YOUR OWN RISK. READ THE APPLICATION SECURITY GUIDELINES
 		}
 		fmt.Println("Enter passphrase: ")
 		cred := app.Credentials(pwd)
-		privkey, err := mintkey.UnarmorDecryptPrivKey(kp.PrivKeyArmor, cred)
+
+		// Retrieve the priv & public keys
+		pubKey := kp.PublicKey.RawBytes()
+		pubKeyHexEncoded := hex.EncodeToString(pubKey)
+		privKeyArmored := kp.PrivKeyArmor
+		privKey, err := mintkey.UnarmorDecryptPrivKey(privKeyArmored, cred)
 		if err != nil {
 			return
 		}
-		aat, err := app.GenerateAAT(hex.EncodeToString(kp.PublicKey.RawBytes()), args[1], privkey)
+
+		aat, err := app.GenerateAAT(pubKeyHexEncoded, args[1], privKey)
 		if err != nil {
 			fmt.Println(err)
 			return
 		}
+
 		fmt.Println(string(aat))
 	},
 }
diff --git a/app/cmd/cli/gov.go b/app/cmd/cli/gov.go
@@ -7,10 +7,11 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/spf13/cobra"
+
 	"github.com/pokt-network/pocket-core/app"
 	"github.com/pokt-network/pocket-core/types"
 	govTypes "github.com/pokt-network/pocket-core/x/gov/types"
-	"github.com/spf13/cobra"
 )
 
 func init() {
@@ -120,6 +121,7 @@ Actions: [burn, transfer]`,
 		fmt.Println(resp)
 	},
 }
+
 var govChangeParam = &cobra.Command{
 	Use:   "change_param <fromAddr> <networkID> <paramKey module/param> <paramValue (jsonObj)> <fees>",
 	Short: "Edit a param in the network",
@@ -205,6 +207,7 @@ func dropTag(version string) string {
 }
 
 const FeatureUpgradeKey = "FEATURE"
+
 const FeatureUpgradeHeight = int64(1)
 
 var govFeatureEnable = &cobra.Command{

diff --git a/app/cmd/cli/node.go b/app/cmd/cli/node.go
@@ -5,8 +5,9 @@ import (
 	"fmt"
 	"strconv"
 
-	"github.com/pokt-network/pocket-core/app"
 	"github.com/spf13/cobra"
+
+	"github.com/pokt-network/pocket-core/app"
 )
 
 func init() {

diff --git a/app/cmd/cli/query.go b/app/cmd/cli/query.go
@@ -6,13 +6,13 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/spf13/cobra"
+
+	"github.com/pokt-network/pocket-core/app"
 	"github.com/pokt-network/pocket-core/app/cmd/rpc"
 	"github.com/pokt-network/pocket-core/types"
 	types2 "github.com/pokt-network/pocket-core/x/apps/types"
-
-	"github.com/pokt-network/pocket-core/app"
 	nodeTypes "github.com/pokt-network/pocket-core/x/nodes/types"
-	"github.com/spf13/cobra"
 )
 
 func init() {
@@ -342,9 +342,13 @@ var queryAccount = &cobra.Command{
 }
 
 var nodeStakingStatus string
+
 var nodeJailedStatus string
+
 var blockchain string
+
 var nodePage int
+
 var nodeLimit int
 
 func init() {
@@ -490,6 +494,7 @@ var queryNodeParams = &cobra.Command{
 }
 
 var appStakingStatus string
+
 var appPage, appLimit int
 
 func init() {

diff --git a/app/cmd/cli/root.go b/app/cmd/cli/root.go
@@ -8,9 +8,10 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/spf13/cobra"
+
 	"github.com/pokt-network/pocket-core/app"
 	"github.com/pokt-network/pocket-core/app/cmd/rpc"
-	"github.com/spf13/cobra"
 )
 
 var (

diff --git a/app/cmd/cli/stake.go b/app/cmd/cli/stake.go
@@ -8,9 +8,10 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/spf13/cobra"
+
 	"github.com/pokt-network/pocket-core/app"
 	"github.com/pokt-network/pocket-core/types"
-	"github.com/spf13/cobra"
 )
 
 func init() {

diff --git a/app/cmd/cli/util.go b/app/cmd/cli/util.go
@@ -2,14 +2,15 @@ package cli
 
 import (
 	"fmt"
-	"github.com/pokt-network/pocket-core/x/pocketcore/types"
 	"os"
 	"strconv"
 
-	"github.com/pokt-network/pocket-core/app"
 	"github.com/spf13/cobra"
 	"github.com/tendermint/tendermint/libs/log"
 	"github.com/tendermint/tendermint/state"
+
+	"github.com/pokt-network/pocket-core/app"
+	"github.com/pokt-network/pocket-core/x/pocketcore/types"
 )
 
 func init() {

diff --git a/app/cmd/rpc/client.go b/app/cmd/rpc/client.go
@@ -5,15 +5,16 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
-	nodesTypes "github.com/pokt-network/pocket-core/x/nodes/types"
 	"io/ioutil"
 	"net/http"
 	"os"
 	"strings"
 	"time"
 
 	"github.com/julienschmidt/httprouter"
+
 	"github.com/pokt-network/pocket-core/app"
+	nodesTypes "github.com/pokt-network/pocket-core/x/nodes/types"
 	"github.com/pokt-network/pocket-core/x/pocketcore/types"
 )
 

diff --git a/app/config.go b/app/config.go
@@ -17,6 +17,22 @@ import (
 
 	kitlevel "github.com/go-kit/kit/log/level"
 	"github.com/go-kit/kit/log/term"
+	"github.com/spf13/cobra"
+	config2 "github.com/tendermint/tendermint/config"
+	cryptoamino "github.com/tendermint/tendermint/crypto/encoding/amino"
+	"github.com/tendermint/tendermint/libs/cli/flags"
+	"github.com/tendermint/tendermint/libs/log"
+	cmn "github.com/tendermint/tendermint/libs/os"
+	"github.com/tendermint/tendermint/libs/rand"
+	"github.com/tendermint/tendermint/node"
+	"github.com/tendermint/tendermint/p2p"
+	"github.com/tendermint/tendermint/privval"
+	"github.com/tendermint/tendermint/rpc/client"
+	"github.com/tendermint/tendermint/rpc/client/http"
+	"github.com/tendermint/tendermint/rpc/client/local"
+	dbm "github.com/tendermint/tm-db"
+	"golang.org/x/crypto/ssh/terminal"
+
 	"github.com/pokt-network/pocket-core/baseapp"
 	"github.com/pokt-network/pocket-core/codec"
 	types2 "github.com/pokt-network/pocket-core/codec/types"
@@ -33,21 +49,6 @@ import (
 	nodesTypes "github.com/pokt-network/pocket-core/x/nodes/types"
 	pocket "github.com/pokt-network/pocket-core/x/pocketcore"
 	"github.com/pokt-network/pocket-core/x/pocketcore/types"
-	"github.com/spf13/cobra"
-	config2 "github.com/tendermint/tendermint/config"
-	cryptoamino "github.com/tendermint/tendermint/crypto/encoding/amino"
-	"github.com/tendermint/tendermint/libs/cli/flags"
-	"github.com/tendermint/tendermint/libs/log"
-	cmn "github.com/tendermint/tendermint/libs/os"
-	"github.com/tendermint/tendermint/libs/rand"
-	"github.com/tendermint/tendermint/node"
-	"github.com/tendermint/tendermint/p2p"
-	"github.com/tendermint/tendermint/privval"
-	"github.com/tendermint/tendermint/rpc/client"
-	"github.com/tendermint/tendermint/rpc/client/http"
-	"github.com/tendermint/tendermint/rpc/client/local"
-	dbm "github.com/tendermint/tm-db"
-	"golang.org/x/crypto/ssh/terminal"
 )
 
 var (

diff --git a/app/query.go b/app/query.go
@@ -9,6 +9,7 @@ import (
 	"strconv"
 	"strings"
 
+	core_types "github.com/tendermint/tendermint/rpc/core/types"
 	tmtypes "github.com/tendermint/tendermint/types"
 
 	"github.com/pokt-network/pocket-core/codec"
@@ -19,7 +20,6 @@ import (
 	"github.com/pokt-network/pocket-core/x/gov/types"
 	nodesTypes "github.com/pokt-network/pocket-core/x/nodes/types"
 	pocketTypes "github.com/pokt-network/pocket-core/x/pocketcore/types"
-	core_types "github.com/tendermint/tendermint/rpc/core/types"
 )
 
 const (
@@ -66,6 +66,7 @@ func (app PocketCoreApp) QueryAccountTxs(addr string, page, perPage int, prove b
 	res, err = tmClient.TxSearch(query, prove, page, perPage, checkSort(sort))
 	return
 }
+
 func (app PocketCoreApp) QueryRecipientTxs(addr string, page, perPage int, prove bool, sort string, height int64) (res *core_types.ResultTxSearch, err error) {
 	tmClient := app.GetClient()
 	defer func() { _ = tmClient.Stop() }()
@@ -625,6 +626,7 @@ func checkPagination(page, limit int) (int, int) {
 	}
 	return page, limit
 }
+
 func checkSort(s string) string {
 	switch s {
 	case "asc":

diff --git a/app/util.go b/app/util.go
@@ -15,8 +15,12 @@ import (
 	pocketKeeper "github.com/pokt-network/pocket-core/x/pocketcore/keeper"
 )
 
-func GenerateAAT(appPubKey, clientPubKey string, key crypto.PrivateKey) (aatjson []byte, err error) {
-	aat, er := pocketKeeper.AATGeneration(appPubKey, clientPubKey, key)
+// GenerateAAT generates an AAT to be used for relay request authentication.
+// - appPubKey is the public key of the application that's staking for on-chain service.
+// - clientPubKey is the public key of a client facilitating relays on behalf of the app.
+// - appPubKey and clientPubKey may or may not be the same.
+func GenerateAAT(appPubKey, clientPubKey string, appPrivKey crypto.PrivateKey) (aatjson []byte, err error) {
+	aat, er := pocketKeeper.AATGeneration(appPubKey, clientPubKey, appPrivKey)
 	if er != nil {
 		return nil, er
 	}

diff --git a/doc/guides/quickstart.md b/doc/guides/quickstart.md
@@ -189,7 +189,7 @@ pocket accounts set-validator <address>
 {% hint style="info" %} Check with `pocket accounts get-validator`
 {% endhint %}
 
-### Set [Relay Chains](https://docs.pokt.network/supported-blockchains/)
+### Set [Relay Chains](https://docs.pokt.network/reference/supported-chains)
 
 {% tabs %} {% tab title="Command" %}
 
@@ -468,7 +468,7 @@ Use pocket core flags --mainnet or --testnet to automatically write
 Use the CLI or Manually Edit: `$HOME/.pocket/config/chains.json`
 
 {% hint style="info" %} Relay Chain ID's and docs can be
-found [here](https://docs.pokt.network/supported-blockchains/). {% endhint %}
+found [here](https://docs.pokt.network/reference/supported-chains). {% endhint %}
 
 These are external blockchain nodes such as ethereum, polygon and harmony. You will need to set these up by following their respective documentation. Once they are synced, you can enter the url and credentials into the following file.