Merge pull request #94 from provenance-io/aj/add-module-docs

Add sdk docs and a cron to keep them updated

.github/workflows/copy-sdk.yml

@@ -0,0 +1,50 @@
+name: Copy SDK Files
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Runs every day at 6pm PST (2am UST)
+    - cron: '0 2 * * *'
+
+jobs:
+  sync-docs-and-create-pr:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          ref: sync-docs
+          fetch-depth: 0
+
+      - name: Set Up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install Dependencies
+        run: |
+          yarn install --frozen-lockfile
+
+      - name: Run Sync Script
+        run: |
+          chmod +x sync_script.sh
+          ./sync_script.sh
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Updated SDK spec changes from provenance/x
+          branch: update-sdk-docs
+          delete-branch: true
+          title: 'Update SDK docs'
+          labels: |
+            automated pr
+          assignees: webbushka
+          reviewers: peter-evans
+          team-reviewers: |
+            blockchain-core

.gitignore

@@ -2,6 +2,7 @@
 
 # Dependencies
 /node_modules
+/provenance
 
 # Production
 /build

docs/sdk/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.

docs/sdk/attribute/01_state.md

@@ -0,0 +1,64 @@
+# State
+The attribute module inserts all attributes into a basic state store.
+
+<!-- TOC -->
+  - [Attribute KV-Store](#attribute-kv-store)
+    - [Key layout](#key-layout)
+    - [Attribute Record](#attribute-record)
+    - [Attribute Type](#attribute-type)
+
+
+
+## Attribute KV-Store
+
+The attribute module takes in an attribute supplied by the user and generates a key for it. This key is generated
+by combinining the attribute prefix, address, attribute name, and a hashed value of the attribute value. This
+can then be used to either store a marshalled attribute record, or retrieve the value it points to in the store.
+
+### Key layout
+[0x02][address][attribute name][hashvalue]
+
+### Attribute Record
+```
+// Attribute holds a typed key/value structure for data associated with an account
+type Attribute struct {
+	// The attribute name.
+	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+
+	// The attribute value.
+	Value []byte `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
+
+	// The attribute value type.
+	AttributeType AttributeType `protobuf:"varint,3,opt,name=attribute_type,json=attributeType,proto3,enum=provenance.attribute.v1.AttributeType" json:"attribute_type,omitempty"`
+
+	// The address the attribute is bound to
+	Address string `protobuf:"bytes,4,opt,name=address,proto3" json:"address,omitempty"`
+}
+```
+
+### Attribute Type
+```
+// AttributeType defines the type of the data stored in the attribute value
+type AttributeType int32
+
+const (
+	// ATTRIBUTE_TYPE_UNSPECIFIED defines an unknown/invalid type
+	AttributeType_Unspecified AttributeType = 0
+	// ATTRIBUTE_TYPE_UUID defines an attribute value that contains a string value representation of a V4 uuid
+	AttributeType_UUID AttributeType = 1
+	// ATTRIBUTE_TYPE_JSON defines an attribute value that contains a byte string containing json data
+	AttributeType_JSON AttributeType = 2
+	// ATTRIBUTE_TYPE_STRING defines an attribute value that contains a generic string value
+	AttributeType_String AttributeType = 3
+	// ATTRIBUTE_TYPE_URI defines an attribute value that contains a URI
+	AttributeType_Uri AttributeType = 4
+	// ATTRIBUTE_TYPE_INT defines an attribute value that contains an integer (cast as int64)
+	AttributeType_Int AttributeType = 5
+	// ATTRIBUTE_TYPE_FLOAT defines an attribute value that contains a float
+	AttributeType_Float AttributeType = 6
+	// ATTRIBUTE_TYPE_PROTO defines an attribute value that contains a serialized proto value in bytes
+	AttributeType_Proto AttributeType = 7
+	// ATTRIBUTE_TYPE_BYTES defines an attribute value that contains an untyped array of bytes
+	AttributeType_Bytes AttributeType = 8
+)
+```

docs/sdk/attribute/02_messages.md

@@ -0,0 +1,199 @@
+# Messages
+
+In this section we describe the processing of the staking messages and the corresponding updates to the state.
+
+<!-- TOC -->
+  - [MsgAddAttributeRequest](#msgaddattributerequest)
+  - [MsgUpdateAttributeRequest](#msgupdateattributerequest)
+  - [MsgUpdateAttributeExpirationRequest](#msgupdateattributeexpirationrequest)
+  - [MsgDeleteAttributeRequest](#msgdeleteattributerequest)
+  - [MsgDeleteDistinctAttributeRequest](#msgdeletedistinctattributerequest)
+  - [MsgSetAccountDataRequest](#msgsetaccountdatarequest)
+
+
+
+## MsgAddAttributeRequest
+
+An attribute record is created using the `MsgAddAttributeRequest` message.
+
+```proto
+// MsgAddAttributeRequest defines an sdk.Msg type that is used to add a new attribute to an account.
+// Attributes may only be set in an account by the account that the attribute name resolves to.
+message MsgAddAttributeRequest {
+  option (gogoproto.equal)            = false;
+  option (gogoproto.goproto_stringer) = false;
+  option (gogoproto.stringer)         = false;
+  option (gogoproto.goproto_getters)  = false;
+
+  // The attribute name.
+  string name = 1;
+  // The attribute value.
+  bytes value = 2;
+  // The attribute value type.
+  AttributeType attribute_type = 3;
+  // The account to add the attribute to.
+  string account = 4;
+  // The address that the name must resolve to.
+  string owner = 5;
+  // Time that an attribute will expire.
+  google.protobuf.Timestamp expiration_date = 6 [(gogoproto.stdtime) = true, (gogoproto.nullable) = true];
+}
+```
+
+This message is expected to fail if:
+- Any components of the request do not pass basic integrity and format checks
+- Attribute value exceeds the maximum length
+- Unable to normalize the name
+- The account does not exist
+- The name does not resolve to the owner address
+
+If successful, an attribute record will be created for the account.
+
+## MsgUpdateAttributeRequest
+
+The update attribute request method allows an existing attribute record to replace its value with a new one.
+
+```proto
+// MsgUpdateAttributeRequest defines an sdk.Msg type that is used to update an existing attribute to an account.
+// Attributes may only be set in an account by the account that the attribute name resolves to.
+message MsgUpdateAttributeRequest {
+  option (gogoproto.equal)            = false;
+  option (gogoproto.goproto_stringer) = false;
+  option (gogoproto.stringer)         = false;
+  option (gogoproto.goproto_getters)  = false;
+
+  // The attribute name.
+  string name = 1;
+  // The original attribute value.
+  bytes original_value = 2;
+  // The update attribute value.
+  bytes update_value = 3;
+  // The original attribute value type.
+  AttributeType original_attribute_type = 4;
+  // The update attribute value type.
+  AttributeType update_attribute_type = 5;
+  // The account to add the attribute to.
+  string account = 6;
+  // The address that the name must resolve to.
+  string owner = 7;
+}
+```
+
+This message is expected to fail if:
+- Any components of the request do not pass basic integrity and format checks
+- Updated attribute value exceeds the maximum length
+- Unable to normalize the original or updated attribute name
+- Updated name and the original name don't match
+- The owner account does not exist
+- The updated name does not resolve to the owner address
+- The original attribute does not exist
+
+If successful, the value of an attribute will be updated.
+
+## MsgUpdateAttributeExpirationRequest
+
+The update attribute expiration request method updates the attribute's expiration date.
+
+```proto
+// MsgUpdateAttributeExpirationRequest defines an sdk.Msg type that is used to update an existing attribute's expiration
+// date
+message MsgUpdateAttributeExpirationRequest {
+  option (gogoproto.equal)            = true;
+  option (gogoproto.stringer)         = true;
+  option (gogoproto.goproto_stringer) = false;
+
+  // The attribute name.
+  string name = 1;
+  // The original attribute value.
+  bytes value = 2;
+  // Time that an attribute will expire.
+  google.protobuf.Timestamp expiration_date = 3 [(gogoproto.stdtime) = true, (gogoproto.nullable) = true];
+  // The account to add the attribute to.
+  string account = 4;
+  // The address that the name must resolve to.
+  string owner = 5;
+}
+```
+
+This message is expected to fail if:
+- Any components of the request do not pass basic integrity and format checks
+- The owner account does not exist
+- The name does not resolve to the owner address
+- The attribute does not exist
+- The expiration date is before current block height
+
+## MsgDeleteAttributeRequest
+
+The delete distinct attribute request method removes an existing account attribute.
+
+```proto
+// MsgDeleteAttributeRequest defines a message to delete an attribute from an account
+// Attributes may only be removed from an account by the account that the attribute name resolves to.
+message MsgDeleteAttributeRequest {
+  option (gogoproto.equal)            = false;
+  option (gogoproto.goproto_stringer) = false;
+  option (gogoproto.stringer)         = false;
+  option (gogoproto.goproto_getters)  = false;
+
+  // The attribute name.
+  string name = 1;
+  // The account to add the attribute to.
+  string account = 2;
+  // The address that the name must resolve to.
+  string owner = 3;
+}
+```
+
+This message is expected to fail if:
+- Any components of the request do not pass basic integrity and format checks
+- The owner account does not exist
+- The name does not resolve to the owner address
+- The attribute does not exist
+
+## MsgDeleteDistinctAttributeRequest
+
+The delete distinct attribute request method removes an existing account attribute with a specific value.
+
+```proto
+// MsgDeleteDistinctAttributeRequest defines a message to delete an attribute with matching name, value, and type from
+// an account. Attributes may only be removed from an account by the account that the attribute name resolves to.
+message MsgDeleteDistinctAttributeRequest {
+  option (gogoproto.equal)            = false;
+  option (gogoproto.goproto_stringer) = false;
+  option (gogoproto.stringer)         = false;
+  option (gogoproto.goproto_getters)  = false;
+
+  // The attribute name.
+  string name = 1;
+  // The attribute value.
+  bytes value = 2;
+  // The account to add the attribute to.
+  string account = 3;
+  // The address that the name must resolve to.
+  string owner = 4;
+}
+```
+
+This message is expected to fail if:
+- Any components of the request do not pass basic integrity and format checks
+- The owner account does not exist
+- The name does not resolve to the owner address
+- The attribute does not exist
+
+## MsgSetAccountDataRequest
+
+The set account data request method associates some data (a string) with an account.
+
+```protobuf
+// MsgSetAccountDataRequest defines a message to set an account's accountdata attribute.
+message MsgSetAccountDataRequest {
+  option (cosmos.msg.v1.signer) = "account";
+
+  string value   = 1;
+  string account = 2;
+}
+```
+
+This message is expected to fail if:
+- The value is too long (as defined in attribute module params).
+- The message is not signed by the provided account.