From 0054870f06373638aa08125fc09ee9319bb97d58 Mon Sep 17 00:00:00 2001 From: Daniel Olshansky Date: Thu, 7 Mar 2024 14:17:35 -0800 Subject: [PATCH] Reply to PR review comments --- app/cmd/cli/app.go | 14 ++++++-------- app/util.go | 2 +- doc/guides/quickstart.md | 4 ++-- doc/specs/application-auth-token.md | 29 +++++++++++++++-------------- doc/specs/cli/apps.md | 4 ++-- doc/specs/cli/node.md | 6 +++--- doc/specs/cli/util.md | 19 +++++++++---------- x/pocketcore/keeper/aat.go | 2 +- x/pocketcore/keeper/proof.go | 5 +---- x/pocketcore/types/proof.go | 4 ++-- 10 files changed, 42 insertions(+), 47 deletions(-) diff --git a/app/cmd/cli/app.go b/app/cmd/cli/app.go index a495e8d79..0b4ce19ca 100644 --- a/app/cmd/cli/app.go +++ b/app/cmd/cli/app.go @@ -181,16 +181,14 @@ var createAATCmd = &cobra.Command{ Use: "create-aat ", Short: "Creates an application authentication token", 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 CLI is hard-coded to generate an AAT with spec version 0.0.1. +This command prompts you to input the account passphrase. +When you send a relay request with AAT, needs to be a staked +application. -The output is intended to be embedded into the Gateway for Relay servicing. - -Upon AAT generation, the user will be prompted for the account passphrase. - - is associated with the application - -Make sure to read doc/specs/application-auth-token.md to understand what's recommended during AAT configuration.`, +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) diff --git a/app/util.go b/app/util.go index b8c412873..07fd2f08c 100644 --- a/app/util.go +++ b/app/util.go @@ -15,7 +15,7 @@ import ( pocketKeeper "github.com/pokt-network/pocket-core/x/pocketcore/keeper" ) -// GenerateAAT generates an AAT to be used for relay servicing. +// GenerateAAT generates an AAT to be used for relay request authentication. // - appPubKey is the public key of the application that's paying for on-chain service. // - clientPubKey (a.k.a gatewayPubKey) is the public key of the Gateway that's facilitating relays on behalf of the app. // - appPubKey and clientPubKey may or may not be the same. diff --git a/doc/guides/quickstart.md b/doc/guides/quickstart.md index de18d96db..cbfb45458 100644 --- a/doc/guides/quickstart.md +++ b/doc/guides/quickstart.md @@ -189,7 +189,7 @@ pocket accounts set-validator
{% 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. diff --git a/doc/specs/application-auth-token.md b/doc/specs/application-auth-token.md index 09024a03b..575bdc534 100644 --- a/doc/specs/application-auth-token.md +++ b/doc/specs/application-auth-token.md @@ -2,7 +2,7 @@ description: >- Version 0.0.1 - The Pocket Network protocol contemplates the use of Application Auth Tokens (AATs) + The Pocket Network protocol contemplates the use of Application Authentication Tokens (AATs) to allow Gateways (off-chain) access Service Nodes (a.k.a Suppliers) on behalf of the Application. --- @@ -26,8 +26,8 @@ staked `Application` to a `Client` by passing an AAT which includes their the - [clientPublicKey](#clientpublickey) - [ECDSA ed25519 Signature Scheme](#ecdsa-ed25519-signature-scheme) - [AAT Generation](#aat-generation) - - [1. Application === Client (Gateway)](#1-application--client-gateway) - - [2. Application !== Gateway (Client)](#2-application--gateway-client) + - [1. Application !== Client (Gateway)](#1-application--client-gateway) + - [2. Application === Client (Gateway)](#2-application--client-gateway) - [AAT Signature Generation](#aat-signature-generation) - [Relay Generation \& Signing using AAT](#relay-generation--signing-using-aat) @@ -76,14 +76,15 @@ When generating a new AAT, the owner of the `Application` private key can choose which `Client` public key is used to sign Relays. More explicitly, this can be decomposed into two options: -1. **Sovereign Application** - Use the same public key for signing the AAT and the relay requests -2. **Gateway** - Use a different public key for signing the AAT and the relay requests +1. **Application Key != Client Key ** - Recommended for all Gateways. +2. **Application Key == Client Key** - Recommended for independent Applications that are not Gateways. -### 1. Application === Client (Gateway) +### 1. Application !== Client (Gateway) ```mermaid flowchart TB App([AppPrivKey]) + CG([ClientPrivateKey/ \n GatePrivateKey]) subgraph AAT Generation direction TB @@ -91,7 +92,7 @@ flowchart TB AAT["AAT"] App -- AppPublicKey --> AATU - App -- ClientPublicKey --> AATU + CG -- ClientPublicKey --> AATU AATU -- hash --> AATUB[AAT Bytes] AATUB -- Sign with AppPrivKey --> sig[Application Signature] AATU -- AAT Structure --> AAT @@ -99,12 +100,11 @@ flowchart TB end ``` -### 2. Application !== Gateway (Client) +### 2. Application === Client (Gateway) ```mermaid flowchart TB App([AppPrivKey]) - CG([ClientPrivateKey/ \n GatePrivateKey]) subgraph AAT Generation direction TB @@ -112,7 +112,7 @@ flowchart TB AAT["AAT"] App -- AppPublicKey --> AATU - CG -- ClientPublicKey --> AATU + App -- ClientPublicKey --> AATU AATU -- hash --> AATUB[AAT Bytes] AATUB -- Sign with AppPrivKey --> sig[Application Signature] AATU -- AAT Structure --> AAT @@ -148,10 +148,11 @@ This section can be summarized by two key points: - AAT includes client public key, signed by application private key - Relay request includes an AAT, signed by client private key -The `Client` is needed to sign the relays while the `Application` is the one that -needs to stake on-chain to get access to Pocket Network's services. Recall that -when an `Application` generates an `AAT`, it can either use its own public key or -another public key (i.e. usually a Gateway's public key) to sign the `AAT`. +The `Client`, an application to send relays, needs to sign every relay request, +while `Application` needs to be staked once with tokens on-chain to get access to +Pocket Network's services. In every session, the maximum number of relays for an +app is proportional to the tokens to be staked with the app. To make more relays, +you need to stake more tokens. ```mermaid flowchart TB diff --git a/doc/specs/cli/apps.md b/doc/specs/cli/apps.md index 9749f8704..ddf6675ac 100644 --- a/doc/specs/cli/apps.md +++ b/doc/specs/cli/apps.md @@ -22,9 +22,9 @@ Arguments: - ``: Target Address to stake. - ``: The amount of uPOKT to stake. Must be higher than the current value of the `ApplicationStakeMinimum` - parameter, found [here](https://docs.pokt.network/learn/protocol-parameters/#applicationstakeminimum). + parameter. - ``: A comma separated list of RelayChain Network Identifiers. Find the RelayChain Network - Identifiers [here](https://docs.pokt.network/supported-blockchains/). + Identifiers [here](https://docs.pokt.network/reference/supported-chains). - ``: The Pocket chain identifier; "mainnet" or "testnet". - ``: An amount of uPOKT for the network. diff --git a/doc/specs/cli/node.md b/doc/specs/cli/node.md index f53ecce29..d48a41d1f 100644 --- a/doc/specs/cli/node.md +++ b/doc/specs/cli/node.md @@ -45,7 +45,7 @@ Arguments: - ``: The amount of uPOKT to stake. Must be higher than the current value of the `StakeMinimum` parameter, found [here](https://docs.pokt.network/learn/protocol-parameters/#stakeminimum). - ``: A comma separated list of RelayChain Network Identifiers. Find the RelayChain Network - Identifiers [here](https://docs.pokt.network/supported-blockchains/). + Identifiers [here](https://docs.pokt.network/reference/supported-chains). - ``: The Service URI Applications will use to communicate with Nodes for Relays. - ``: The Pocket chain identifier; "mainnet" or "testnet". - ``: An amount of uPOKT for the network. @@ -63,7 +63,7 @@ Transaction submitted with hash: pocket nodes stake non-custodial ``` -Stakes a non-custodial node in the network, making it available for service. The signer may be the operator or the output address. The signer must specify the passphrase of either the output or operator address when prompted for the `` account passphrase. This will determine where the staked funds are taken from. +Stakes a non-custodial node in the network, making it available for service. The signer may be the operator or the output address. The signer must specify the passphrase of either the output or operator address when prompted for the `` account passphrase. This will determine where the staked funds are taken from. if the node is already staked, this transaction acts as an _update_ transaction. A node can update `` , ``, and increase the stake `` with this transaction. If the node is currently staked at `X` and @@ -77,7 +77,7 @@ Arguments: - ``: The amount of uPOKT to stake. Must be higher than the current value of the `StakeMinimum` parameter, found [here](https://docs.pokt.network/learn/protocol-parameters/#stakeminimum). - ``: A comma separated list of RelayChain Network Identifiers. Find the RelayChain Network - Identifiers [here](https://docs.pokt.network/supported-blockchains/). + Identifiers [here](https://docs.pokt.network/reference/supported-chains). - ``: The Service URI Applications will use to communicate with Nodes for Relays. - ``: The Pocket chain identifier; "mainnet" or "testnet". - ``: An amount of uPOKT for the network. diff --git a/doc/specs/cli/util.md b/doc/specs/cli/util.md index 411aa3916..ff38bbc93 100644 --- a/doc/specs/cli/util.md +++ b/doc/specs/cli/util.md @@ -11,7 +11,7 @@ pocket util generate-chains ``` Generate the chains.json file for RelayChain Network Identifiers. Find the RelayChain Network -Identifiers [here](https://docs.pokt.network/supported-blockchains/). +Identifiers [here](https://docs.pokt.network/reference/supported-chains). Example output: @@ -35,7 +35,7 @@ pocket util delete-chains ``` Delete the chains.json file for RelayChain Network Identifiers. Find the RelayChain Network -Identifiers [here](https://docs.pokt.network/supported-blockchains/). +Identifiers [here](https://docs.pokt.network/reference/supported-chains). Example Output: @@ -53,11 +53,11 @@ Rolls back the blockchain, the state, and app to a previous height Arguments: -* ``: the height you want to rollback to. +- ``: the height you want to rollback to. Flags -* `blocks`: rollback block store and state +- `blocks`: rollback block store and state ## Decode Transaction @@ -69,8 +69,8 @@ Decodes a given transaction encoded in Amino/Proto base64 bytes Arguments: -* ``: The transaction amino encoded bytes. -* ``: Enable/Disable amino encoding for transaction. +- ``: The transaction amino encoded bytes. +- ``: Enable/Disable amino encoding for transaction. Example output: @@ -95,7 +95,7 @@ Generate completion script for the specified shell Arguments: -* ``: the shell you currently use. Supported options: **bash / zsh / fish / powershell** +- ``: the shell you currently use. Supported options: **bash / zsh / fish / powershell** ## Convert Evidence to Proto from Amino @@ -303,8 +303,8 @@ In the event of a network reset, this will export a genesis file based on the pr Arguments: -* ``: the height from which to generate genesis.json -* ``: the chainID to use for exporting. +- ``: the height from which to generate genesis.json +- ``: the chainID to use for exporting. Example Output: @@ -333,4 +333,3 @@ Example Output: } } ``` - diff --git a/x/pocketcore/keeper/aat.go b/x/pocketcore/keeper/aat.go index 5064edf61..08670ef6c 100644 --- a/x/pocketcore/keeper/aat.go +++ b/x/pocketcore/keeper/aat.go @@ -8,7 +8,7 @@ import ( pc "github.com/pokt-network/pocket-core/x/pocketcore/types" ) -// GenerateAAT generates an AAT to be used for relay servicing. +// GenerateAAT generates an AAT to be used for relay request authentication. // - appPubKey is the public key of the application that's paying for on-chain service. // - clientPubKey (a.k.a gatewayPubKey) is the public key of the Gateway that's facilitating relays on behalf of the app. // - appPubKey and clientPubKey may or may not be the same. diff --git a/x/pocketcore/keeper/proof.go b/x/pocketcore/keeper/proof.go index e4bc57cf7..7a033e4bf 100644 --- a/x/pocketcore/keeper/proof.go +++ b/x/pocketcore/keeper/proof.go @@ -18,10 +18,7 @@ import ( pc "github.com/pokt-network/pocket-core/x/pocketcore/types" ) -// This is how servicers (a.k.a suppliers a.k.a as nodes a.k.a node runners) send proofs to the network. -// Nothing actionable (requests have already been signed by this point), but just FYI. - -// auto sends a proof transaction for the claim +// SendProofTx auto sends a proof transaction for the claim func (k Keeper) SendProofTx(ctx sdk.Ctx, n client.Client, node *pc.PocketNode, proofTx func(cliCtx util.CLIContext, txBuilder auth.TxBuilder, merkleProof pc.MerkleProof, leafNode pc.Proof, evidenceType pc.EvidenceType) (*sdk.TxResponse, error)) { addr := node.GetAddress() // get all mature (waiting period has passed) claims for your address diff --git a/x/pocketcore/types/proof.go b/x/pocketcore/types/proof.go index 34731a244..f53f1da83 100644 --- a/x/pocketcore/types/proof.go +++ b/x/pocketcore/types/proof.go @@ -129,8 +129,8 @@ func (rp RelayProof) ValidateBasic() sdk.Error { return NewInvalidTokenError(ModuleName, err) } - // Retrieving the client public key (aka the gateway public key), which - // may or may not be the same as the application public key depending on + // Retrieving the client public key + // NB: This is sometimes referred to as the gateway public key. // the inputs to when the AAT was generated. clientPubKey := rp.Token.ClientPublicKey