Merge branch 'main' into dwedul/1753-copy-sanction-in

provenance-io · Nov 28, 2023 · 853fab2 · 853fab2
2 parents a9eacaa + 57ebb37
commit 853fab2
Show file tree

Hide file tree

Showing 20 changed files with 186 additions and 162 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -44,6 +44,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
 ### Improvements
 
 * Add upgrade handler for 1.18 [#1756](https://github.com/provenance-io/provenance/pull/1756).
+* Updated documentation for each module to work with docusaurus [PR 1763](https://github.com/provenance-io/provenance/pull/1763)
 
 ### Dependencies
 

diff --git a/README.md b/README.md
@@ -36,7 +36,7 @@ For more information on the many TradFi institutions and Fintechs leveraging the
 
 ## Quick Start
 
-As the [Provenance Blockchain][provenance] and its core modules are based on the [Cosmos SDK][cosmos], [this introduction](https://docs.cosmos.network/main/learn/intro/overview) into Cosmos is a useful starting point.
+As the [Provenance Blockchain][provenance] and its core modules are based on the [Cosmos SDK][cosmos], [this introduction](https://docs.cosmos.network/v0.47/learn/intro/overview) into Cosmos is a useful starting point.
 
 Developers can use a local checkout and the make targets `make run` and `make localnet-start` to run a local development network.
 

diff --git a/x/README.md b/x/README.md
@@ -0,0 +1,22 @@
+---
+sidebar_position: 0
+---
+
+# List of Modules
+
+Modules are the code components of the Provenance Blockchain that execute the majority of the business logic for applications. The [Cosmos SDK](https://docs.cosmos.network/v0.47) enables developers to build modules that utilize the core structure of the SDK to allow the modules to function together. To read more about creating modules, refer to the [Cosmos documentation on modules](https://docs.cosmos.network/v0.47/building-modules/intro).
+
+Provenance uses inherited modules from the Cosmos SDK, and has also developed modules that are specific to Provenance.
+
+* [Inherited Cosmos modules](https://docs.cosmos.network/v0.47/build/modules)
+* [Attribute](./attribute/README.md) - Functions as a blockchain registry for storing \<Name, Value\> pairs.
+* [Exchange](./exchange/README.md) - Facilitates the trading of on-chain assets.
+* [Hold](./hold/README.md) - Keeps track of funds in an account that have a hold placed on them.
+* [ibchooks](./ibchooks/README.md) - Forked from https://github.com/osmosis-labs/osmosis/tree/main/x/ibchooks
+* [Marker](./marker/README.md) - Allows for the creation of fungible tokens.
+* [Metadata](./metadata/README.md) - Provides a system for referencing off-chain information.
+* [msgfees](./msgfees/README.md) - Manages additional fees that can be applied to tx msgs.
+* [Name](./name/README.md) - Provides a system for providing human-readable names as aliases for addresses.
+* [Oracle](./oracle/README.md) - Provides the capability to dynamically expose query endpoints.
+* [Reward](./reward/README.md) - Provides a system for distributing rewards to accounts.
+* [Trigger](./trigger/README.md) - Provides a system for triggering transactions based on predeterminded events.
diff --git a/x/attribute/spec/03_events.md b/x/attribute/spec/03_events.md
@@ -18,12 +18,12 @@ Fires when an attribute is successfully added.
 
 | Type              | Attribute Key | Attribute Value        |
 |-------------------|---------------|------------------------|
-| EventAttributeAdd | Name          | {name string}          |
-| EventAttributeAdd | Value         | {attribute value}      |
-| EventAttributeAdd | Type          | {attribute value type} |
-| EventAttributeAdd | Account       | {account address}      |
-| EventAttributeAdd | Owner         | {owner address}        |
-| EventAttributeAdd | Expiration    | {expiration date/time} |
+| EventAttributeAdd | Name          | \{name string\}          |
+| EventAttributeAdd | Value         | \{attribute value\}      |
+| EventAttributeAdd | Type          | \{attribute value type\} |
+| EventAttributeAdd | Account       | \{account address\}      |
+| EventAttributeAdd | Owner         | \{owner address\}        |
+| EventAttributeAdd | Expiration    | \{expiration date/time\} |
 
 `provenance.attribute.v1.EventAttributeAdd`
 
@@ -34,13 +34,13 @@ Fires when an existing attribute is successfully updated.
 
 | Type                 | Attribute Key | Attribute Value            |
 |----------------------|---------------|----------------------------|
-| EventAttributeUpdate | Name          | {name string}              |
-| EventAttributeUpdate | OriginalValue | {attribute value}          |
-| EventAttributeUpdate | OriginalType  | {attribute value type}     |
-| EventAttributeUpdate | UpdateValue   | {new attribute value}      |
-| EventAttributeUpdate | UpdateType    | {new attribute value type} |
-| EventAttributeUpdate | Account       | {account address}          |
-| EventAttributeUpdate | Owner         | {owner address}            |
+| EventAttributeUpdate | Name          | \{name string\}              |
+| EventAttributeUpdate | OriginalValue | \{attribute value\}          |
+| EventAttributeUpdate | OriginalType  | \{attribute value type\}     |
+| EventAttributeUpdate | UpdateValue   | \{new attribute value\}      |
+| EventAttributeUpdate | UpdateType    | \{new attribute value type\} |
+| EventAttributeUpdate | Account       | \{account address\}          |
+| EventAttributeUpdate | Owner         | \{owner address\}            |
 
 `provenance.attribute.v1.EventAttributeUpdate`
 
@@ -51,12 +51,12 @@ Fires when an existing attribute's expiration is successfully updated.
 
 | Type                           | Attribute Key      | Attribute Value            |
 |--------------------------------|--------------------|----------------------------|
-| EventAttributeExpirationUpdate | Name               | {name string}              |
-| EventAttributeExpirationUpdate | Value              | {attribute value}          |
-| EventAttributeExpirationUpdate | Account            | {account address}          |
-| EventAttributeExpirationUpdate | Owner              | {owner address}            |
-| EventAttributeExpirationUpdate | OriginalExpiration | {old expiration date/time} |
-| EventAttributeExpirationUpdate | UpdatedExpiration  | {new expiration date/time} |
+| EventAttributeExpirationUpdate | Name               | \{name string\}              |
+| EventAttributeExpirationUpdate | Value              | \{attribute value\}          |
+| EventAttributeExpirationUpdate | Account            | \{account address\}          |
+| EventAttributeExpirationUpdate | Owner              | \{owner address\}            |
+| EventAttributeExpirationUpdate | OriginalExpiration | \{old expiration date/time\} |
+| EventAttributeExpirationUpdate | UpdatedExpiration  | \{new expiration date/time\} |
 
 
 ---
@@ -66,9 +66,9 @@ Fires when an existing attribute is deleted.
 
 | Type                 | Attribute Key | Attribute Value   |
 |----------------------|---------------|-------------------|
-| EventAttributeDelete | Name          | {name string}     |
-| EventAttributeDelete | Account       | {account address} |
-| EventAttributeDelete | Owner         | {owner address}   |
+| EventAttributeDelete | Name          | \{name string\}     |
+| EventAttributeDelete | Account       | \{account address\} |
+| EventAttributeDelete | Owner         | \{owner address\}   |
 
 `provenance.attribute.v1.EventAttributeDelete`
 
@@ -79,11 +79,11 @@ Fires when an existing attribute is deleted distinctly.
 
 | Type                         | Attribute Key | Attribute Value        |
 |------------------------------|---------------|------------------------|
-| EventAttributeDistinctDelete | Name          | {name string}          |
-| EventAttributeDistinctDelete | Value         | {attribute value}      |
-| EventAttributeDistinctDelete | AttributeType | {attribute value type} |
-| EventAttributeDistinctDelete | Owner         | {owner address}        |
-| EventAttributeDistinctDelete | Account       | {account address}      |
+| EventAttributeDistinctDelete | Name          | \{name string\}          |
+| EventAttributeDistinctDelete | Value         | \{attribute value\}      |
+| EventAttributeDistinctDelete | AttributeType | \{attribute value type\} |
+| EventAttributeDistinctDelete | Owner         | \{owner address\}        |
+| EventAttributeDistinctDelete | Account       | \{account address\}      |
 
 `provenance.attribute.v1.EventAttributeDistinctDelete`
 
@@ -94,12 +94,12 @@ Fires when an attribute's expriration date/time has been reached and the attribu
 
 | Type                  | Attribute Key | Attribute Value        |
 |-----------------------|---------------|------------------------|
-| EventAttributeExpired | Name          | {name string}          |
-| EventAttributeExpired | Value         | {attribute value}      |
-| EventAttributeExpired | AttributeType | {attribute value type} |
-| EventAttributeExpired | Account       | {account address}      |
-| EventAttributeExpired | Owner         | {owner address}        |
-| EventAttributeExpired | Expiration    | {expiration date/time} |
+| EventAttributeExpired | Name          | \{name string\}          |
+| EventAttributeExpired | Value         | \{attribute value\}      |
+| EventAttributeExpired | AttributeType | \{attribute value type\} |
+| EventAttributeExpired | Account       | \{account address\}      |
+| EventAttributeExpired | Owner         | \{owner address\}        |
+| EventAttributeExpired | Expiration    | \{expiration date/time\} |
 
 ---
 ## Account Data Updated
@@ -108,4 +108,4 @@ Fires when account data is updated for an account.
 
 | Type                    | Attribute Key | Attribute Value        |
 |-------------------------|---------------|------------------------|
-| EventAccountDataUpdated | Account       | {account address}      |
+| EventAccountDataUpdated | Account       | \{account address\}      |
diff --git a/x/attribute/spec/README.md b/x/attribute/spec/README.md
@@ -1,12 +1,12 @@
-# `Attribute`
+# `x/attribute`
 
 ## Abstract
 
-The purpose of the Attributes Module is to act as a registry that allows an Address to store <Name, Value> pairs.
+The purpose of the Attributes Module is to act as a registry that allows an Address to store `<Name, Value>` pairs.
 Every Name must be registered by the Name Service, and a Name have multiple Values associated with it. Values are required to have a type, and they can be set or retrieved by Name.
 
 This feature provides the blockchain with the capability to store and retrieve values by Name. It plays a major
-part in some of our components such as smart contract creation process. It allows an Address to create and store 
+part in some of our components such as smart contract creation process. It allows an Address to create and store
 a named smart contract on the blockchain.
 
 ## Contents

diff --git a/x/exchange/spec/README.md b/x/exchange/spec/README.md
@@ -1,4 +1,4 @@
-# `Exchange`
+# `x/exchange`
 
 ## Overview
 

diff --git a/x/hold/spec/README.md b/x/hold/spec/README.md
@@ -1,4 +1,4 @@
-# `Hold`
+# `x/hold`
 
 ## Overview
 

diff --git a/x/ibchooks/README.md b/x/ibchooks/README.md
@@ -1,4 +1,4 @@
-# ibchooks
+# `x/ibchooks`
 
 ## Notice
 
@@ -9,7 +9,7 @@ _Unfortunately the original version could not be directly used due to extensive
 ## Wasm Hooks
 
 The wasm hook is an IBC middleware which is used to allow ICS-20 token transfers to initiate contract calls.
-This allows cross-chain contract calls, that involve token movement. 
+This allows cross-chain contract calls, that involve token movement.
 This is useful for a variety of usecases.
 One of primary importance is cross-chain swaps, which is an extremely powerful primitive.
 
@@ -37,15 +37,15 @@ type MsgExecuteContract struct {
 
 So we detail where we want to get each of these fields from:
 
-* Sender: We cannot trust the sender of an IBC packet, the counterparty chain has full ability to lie about it. 
+* Sender: We cannot trust the sender of an IBC packet, the counterparty chain has full ability to lie about it.
 We cannot risk this sender being confused for a particular user or module address on Osmosis.
 So we replace the sender with an account to represent the sender prefixed by the channel and a wasm module prefix.
-This is done by setting the sender to `Bech32(Hash("ibc-wasm-hook-intermediary" || channelID || sender))`, where the channelId is the channel id on the local chain. 
+This is done by setting the sender to `Bech32(Hash("ibc-wasm-hook-intermediary" || channelID || sender))`, where the channelId is the channel id on the local chain.
 * Contract: This field should be directly obtained from the ICS-20 packet metadata
 * Msg: This field should be directly obtained from the ICS-20 packet metadata.
 * Funds: This field is set to the amount of funds being sent over in the ICS 20 packet. One detail is that the denom in the packet is the counterparty chains representation of the denom, so we have to translate it to Osmosis' representation.
 
-> **_WARNING:_**  Due to a [bug](https://twitter.com/SCVSecurity/status/1682329758020022272) in the packet forward middleware, we cannot trust the sender from chains that use PFM. Until that is fixed, we recommend chains to not trust the sender on contracts executed via IBC hooks. 
+> **_WARNING:_**  Due to a [bug](https://twitter.com/SCVSecurity/status/1682329758020022272) in the packet forward middleware, we cannot trust the sender from chains that use PFM. Until that is fixed, we recommend chains to not trust the sender on contracts executed via IBC hooks.
 
 So our constructed cosmwasm message that we execute will look like:
 
@@ -66,7 +66,7 @@ msg := MsgExecuteContract{
 So given the details above, we propogate the implied ICS20 packet data structure.
 ICS20 is JSON native, so we use JSON for the memo format.
 
-```json 
+```json
 {
     //... other ibc fields that we don't care about
     "data":{
@@ -126,20 +126,20 @@ In wasm hooks, post packet execution:
 ## Ack callbacks
 
 A contract that sends an IBC transfer, may need to listen for the ACK from that packet. To allow
-contracts to listen on the ack of specific packets, we provide Ack callbacks. 
+contracts to listen on the ack of specific packets, we provide Ack callbacks.
 
 ### Design
 
-The sender of an IBC transfer packet may specify a callback for when the ack of that packet is received in the memo 
-field of the transfer packet. 
+The sender of an IBC transfer packet may specify a callback for when the ack of that packet is received in the memo
+field of the transfer packet.
 
 Crucially, _only_ the IBC packet sender can set the callback.
 
 ### Use case
 
 The crosschain swaps implementation sends an IBC transfer. If the transfer were to fail, we want to allow the sender
-to be able to retrieve their funds (which would otherwise be stuck in the contract). To do this, we allow users to 
-retrieve the funds after the timeout has passed, but without the ack information, we cannot guarantee that the send 
+to be able to retrieve their funds (which would otherwise be stuck in the contract). To do this, we allow users to
+retrieve the funds after the timeout has passed, but without the ack information, we cannot guarantee that the send
 hasn't failed (i.e.: returned an error ack notifying that the receiving change didn't accept it)
 
 ### Implementation
@@ -194,30 +194,30 @@ IBC supports the ability to send an ack back to the sender of the packet asynchr
 cases where the packet is received, but the ack is not immediately known. For example, if the packet is being
 forwarded to another chain, the ack may not be known until the packet is received on the other chain.
 
-Note this ACK does not imply full revertability. It is possible that unrevertable actions have occurred 
-even if there is an Ack Error. (This is distinct from the behavior of ICS-20 transfers). If you want to ensure 
+Note this ACK does not imply full revertability. It is possible that unrevertable actions have occurred
+even if there is an Ack Error. (This is distinct from the behavior of ICS-20 transfers). If you want to ensure
 revertability, your contract should be implemented in a way that actions are not finalized until a success ack
 is received.
 
 #### Use case
 
 Async acks are useful in cases where the contract needs to wait for a response from another chain before
-returning a result to the caller. 
+returning a result to the caller.
 
 For example, if you want to send tokens to another chain after the contract is executed you need to
-add a new ibc packet and wait for its ack. 
+add a new ibc packet and wait for its ack.
 
-In the synchronous acks case, the caller will receive an ack from the contract before the second packet 
-has been processed. This means that the caller will have to wait (and potentially track) if the second 
-packet has been processed successfully or not. 
+In the synchronous acks case, the caller will receive an ack from the contract before the second packet
+has been processed. This means that the caller will have to wait (and potentially track) if the second
+packet has been processed successfully or not.
 
-With async acks, you contract can take this responsibility and only send an ack to the caller once the 
+With async acks, you contract can take this responsibility and only send an ack to the caller once the
 second packet has been processed
 
 #### Making contract Acks async
 
 To support this, we allow contracts to return an `IBCAsync` response from the function being executed when the
-packet is received. That response specifies that the ack should be handled asynchronously. 
+packet is received. That response specifies that the ack should be handled asynchronously.
 
 Concretely the contract should return:
 
@@ -229,17 +229,17 @@ pub struct OnRecvPacketAsyncResponse {
 ```
 
 if `is_async_ack` is set to true, `OnRecvPacket` will return `nil` and the ack will not be written. Instead, the
-contract wil be stored as the "ack actor" for the packet so that only that contract is allowed to send an ack 
+contract wil be stored as the "ack actor" for the packet so that only that contract is allowed to send an ack
 for it.
 
-It is up to the contract developers to decide which conditions will trigger the ack to be sent. 
+It is up to the contract developers to decide which conditions will trigger the ack to be sent.
 
 #### Sending an async ack
 
-To send the async ack, the contract needs to send the MsgEmitIBCAck message to the chain. This message will 
-then make a sudo call to the contract requesting the ack and write the ack to state. 
+To send the async ack, the contract needs to send the MsgEmitIBCAck message to the chain. This message will
+then make a sudo call to the contract requesting the ack and write the ack to state.
 
-That message can be specified in the contract as: 
+That message can be specified in the contract as:
 
 ```rust
 #[derive(
@@ -304,7 +304,7 @@ pub enum IBCAck {
 
 Note: the sudo call is required to potentially allow anyone to send the MsgEmitIBCAck message. For now, however,
 this is artificially limited so that the message can only be send by the same contract. This could be expanded in
-the future if needed. 
+the future if needed.
 
 # Testing strategy