[2137]: Update the spec docs to reflect the new value owner storage. …

…Also fix a few typos in there.

x/metadata/spec/01_concepts.md

@@ -33,7 +33,7 @@ See [Specifications](02_state.md#specifications) for details.
 ## Metadata Addresses
 
 Entries and Specifications must each have a unique metadata address.
-These addresses are byte arrays that are commonly referered to as "ids".
+These addresses are byte arrays that are commonly referred to as "ids".
 As strings, they should be represented using the bech32 address format.
 The addresses for the different messages have specific formats that help facilitate grouping and indexing.
 All addresses start with a single byte that identifies the type, and are followed by 16 bytes commonly called a UUID.
@@ -105,6 +105,7 @@ The following are requirements related to smart contract usage of the `x/metadat
 * When a smart contract signs a message, it MUST be first or have only smart-contract signers before it, and SHOULD include the invoker address(es) after.
 * When a smart contract is a signer, it must either be a party/owner, or have authorizations (via `x/authz`) from all signers after it.
 * If a smart contract is a signer, but not a party, it cannot be the only signer, and cannot be the last signer.
+* A smart contract cannot be used to change the value owner of a scope unless the smart contract is the value owner itself.
 
 ### With Party Rollup Required
 

x/metadata/spec/02_state.md

@@ -22,8 +22,6 @@ They group and identify information.
 
 ### Scopes
 
-<!-- TODO[2137]: Update this to reflect new value owner storage. -->
-
 A scope is a high-level grouping of information combined with some access control.
 
 * A scope must conform to a pre-determined scope specification.
@@ -82,6 +80,15 @@ message Scope {
 }
 ```
 
+Before a scope is stored in state, the `value_owner_address` is cleared out (set to an empty string).
+The scope is then protobuf encoded, and those bytes are the value stored in state.
+
+#### Scope Value Owners
+
+The `value_owner_address` is tracked using the `x/bank` module. When a scope first gets a value owner (either upon scope
+creation, or later with an update), a single coin with the denom `nft/<scope_id>` is minted and placed in the value
+owner's account. That coin can be transferred or traded the same ways as any other on-chain funds, e.g. via `MsgSend`.
+
 #### Scope Indexes
 
 Scopes by owner:
@@ -95,11 +102,6 @@ Scopes by Scope Specification:
 * Part 1: All bytes of the scope specification key
 * Part 2: All bytes of the scope key
 
-Scopes by value owner:
-* Type byte: `0x18`
-* Part 1: The value owner address (length byte then value bytes)
-* Part 2: All bytes of the scope key
-
 
 
 ### Sessions

x/metadata/spec/03_messages.md

@@ -51,13 +51,17 @@ Scopes are identified using their `scope_id`.
 +++ https://github.com/provenance-io/provenance/blob/v1.19.0/proto/provenance/metadata/v1/tx.proto#L93-L119
 
 The `scope_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used to generate the appropriate scope id for use in the `scope.scope_id` field.
 
 The `spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used to generate the appropriate scope specification id for use in the `scope.specification_id` field.
 
+An empty `scope.value_owner_address` indicates that there is no change to the scope's value owner. I.e. Once a scope has
+a value owner, it will always have a value owner (until the scope is deleted); it cannot be changed to an empty string.
+
+
 #### Response
 
 +++ https://github.com/provenance-io/provenance/blob/v1.19.0/proto/provenance/metadata/v1/tx.proto#L121-L125
@@ -227,7 +231,7 @@ The `session_id_components` field is optional.
 If supplied, it will be used to generate the appropriate session id for use in the `session.session_id` field.
 
 The `spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used to generate the appropriate contract specification id for use in the `session.specification_id` field.
 
 #### Response
@@ -265,7 +269,7 @@ The `session_id_components` field is optional.
 If supplied, it will be used to generate the appropriate session id for use in the `record.session_id` field.
 
 The `contract_spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used with `record.name` to generate the appropriate record specification id for use in the `record.specification_id` field.
 
 #### Response
@@ -300,7 +304,7 @@ This service message is expected to fail if:
 * The `inputs` list does not contain one or more inputs defined in the record specification.
 * An entry in `inputs` has a `type_name` different from its input specification.
 * An entry in `inputs` has a `source` type that doesn't match the input specification.
-* An entry in `inputs` has a `source` value that doesn't match the intput specification.
+* An entry in `inputs` has a `source` value that doesn't match the input specification.
 * The record specification has a result type of `record` but there isn't exactly one entry in `outputs`.
 * The record specification has a result type of `record_list` but the `outputs` list is empty.
 * The `signers` do not have permission to write the record.
@@ -340,7 +344,7 @@ Scope specifications are identified using their `specification_id`.
 +++ https://github.com/provenance-io/provenance/blob/v1.19.0/proto/provenance/metadata/v1/tx.proto#L345-L363
 
 The `spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used to generate the appropriate scope specification id for use in the `specification.specification_id` field.
 
 #### Response
@@ -393,7 +397,7 @@ Contract specifications are identified using their `specification_id`.
 +++ https://github.com/provenance-io/provenance/blob/v1.19.0/proto/provenance/metadata/v1/tx.proto#L385-L403
 
 The `spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used to generate the appropriate contract specification id for use in the `specification.specification_id` field.
 
 #### Response
@@ -496,7 +500,7 @@ Record specifications are identified using their `specification_id`.
 +++ https://github.com/provenance-io/provenance/blob/v1.19.0/proto/provenance/metadata/v1/tx.proto#L461-L479
 
 The `contract_spec_uuid` field is optional.
-It should be a uuid formated as a string using the standard UUID format.
+It should be a uuid formatted as a string using the standard UUID format.
 If supplied, it will be used with the `specification.name` to generate the appropriate record specification id for use in the `specification.specification_id` field.
 
 #### Response