From 13b0a5edbdd54ba4711a90a4c8e8e4a5232adcaf Mon Sep 17 00:00:00 2001
From: Ira Miller <72319+iramiller@users.noreply.github.com>
Date: Wed, 2 Oct 2024 15:49:03 -0600
Subject: [PATCH] provide better documentation for marker nav cmd. (#2159)

* provide better documentation for marker nav cmd.

* updated description based on coderabbit suggestion

* spelling fixes.

* add missing changelog
---
 .../improvements/2128-marker-nav-docs.md      |  1 +
 x/marker/client/cli/tx.go                     | 44 +++++++++++++++++--
 2 files changed, 41 insertions(+), 4 deletions(-)
 create mode 100644 .changelog/unreleased/improvements/2128-marker-nav-docs.md

diff --git a/.changelog/unreleased/improvements/2128-marker-nav-docs.md b/.changelog/unreleased/improvements/2128-marker-nav-docs.md
new file mode 100644
index 000000000..684c68bc5
--- /dev/null
+++ b/.changelog/unreleased/improvements/2128-marker-nav-docs.md
@@ -0,0 +1 @@
+* Address missing documentation on marker nav command [#2134](https://github.com/provenance-io/provenance/issues/2128).
\ No newline at end of file
diff --git a/x/marker/client/cli/tx.go b/x/marker/client/cli/tx.go
index 694c79a4c..39da6f9d6 100644
--- a/x/marker/client/cli/tx.go
+++ b/x/marker/client/cli/tx.go
@@ -1053,11 +1053,47 @@ $ %[1]s tx marker account-data hotdogcoin --%[4]s`,
 // GetCmdAddNetAssetValues returns a CLI command for adding/updating marker net asset values.
 func GetCmdAddNetAssetValues() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "add-net-asset-values <denom> " + attrcli.AccountDataFlagsUse,
+		Use:     "add-net-asset-values <denom> <valuation[;valuation...]>",
 		Aliases: []string{"add-navs", "anavs"},
-		Short:   "Add/updates net asset values for a marker",
-		Example: fmt.Sprintf(`$ %[1]s tx marker add-net-asset-values hotdogcoin 1usd,1;2nhash,3`,
-			version.AppName),
+		Short:   "Provide net asset values for a marker",
+		Long: `
+Provide net asset valuations for a marker. Net asset values are used to establish 
+the relative value of the marker in relation to other assets or currencies.
+
+Net asset values are expressed as a ratio between an amount of coin paid (price) 
+and a volume of the marker's tokens which are considered equivalent in value.
+
+The denomination of the amount paid (price) must either:
+1) Exist on-chain as a separate marker, or
+2) Be supplied as [1000usd], an integer valued in mils (1000 mils = $1 USD).
+
+The volume is supplied as an integer count of the current marker's tokens.
+
+IMPORTANT: All values must be represented as whole integers. If a decimal value 
+is required, adjust the ratio between the price and volume to achieve the 
+desired precision.
+`,
+		Example: fmt.Sprintf(`
+  Set a value of $1 = 1markercoin (Note USD is denominated in mils)
+  $ %[1]s tx %[2]s add-net-asset-values markercoin 1000usd,1
+  
+  Provide more than one valuation in a single call
+  $ %[1]s tx %[2]s add-net-asset-values markercoin 1000usd,1;5000000000nhash,1
+
+  Valuations for larger trades with volumes greater than 1
+  $ %[1]s tx %[2]s add-net-asset-values markercoin 100000usd,199;1000stake,19
+
+  All values must be represented as whole integers.  If a decimal value is required
+  then the ratio between the price and volume must be adjusted to achieve the decimal
+  required.
+
+  Note: When the valuations are recorded, each will indicate the address of the admin
+  who provided the value. This will be published in the associated event data and 
+  captured in the NAV record.  For NAVs set by other modules such as x/exchange the
+  protocol will indicate these sources.  This separates established values from
+  the owner (self-attestation) from those set through blockchain transactions.
+		`,
+			version.AppName, types.ModuleName),
 		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			clientCtx, err := client.GetClientTxContext(cmd)