Merge branch 'master' into spellcheck_github_action_update

Author: ashcherbakov

app/app.go

@@ -624,6 +624,13 @@ func New(
 		},
 	)
 
+	app.UpgradeKeeper.SetUpgradeHandler(
+		"v1.3",
+		func(ctx sdk.Context, plan upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
+			return app.mm.RunMigrations(ctx, cfg, fromVM)
+		},
+	)
+
 	return app
 }
 

cmd/dcld/cmd/genaccounts.go

@@ -19,6 +19,7 @@ import (
 	"github.com/spf13/cast"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
+	"github.com/zigbee-alliance/distributed-compliance-ledger/x/common/types"
 	dclauthtypes "github.com/zigbee-alliance/distributed-compliance-ledger/x/dclauth/types"
 	"github.com/zigbee-alliance/distributed-compliance-ledger/x/dclgenutil"
 	dclgenutiltypes "github.com/zigbee-alliance/distributed-compliance-ledger/x/dclgenutil/types"
@@ -29,6 +30,7 @@ const (
 	FlagPubKey  = "pubkey"
 	FlagRoles   = "roles"
 	FlagVID     = "vid"
+	FlagPIDs    = "pid_ranges"
 )
 
 // AddGenesisAccountCmd returns add-genesis-account cobra Command.
@@ -109,8 +111,36 @@ the address will be looked up in the local Keybase.
 				}
 			}
 
+			var pidRanges []*types.Uint16Range
+			if pidStrRanges := viper.GetString(FlagPIDs); len(pidStrRanges) > 0 { //nolint:nestif
+				var lastMax int32
+				for _, pidStrRange := range strings.Split(pidStrRanges, ",") {
+					pidRange := strings.Split(pidStrRange, "-")
+					if len(pidRange) != 2 {
+						return fmt.Errorf("failed to parse PID Range")
+					}
+					min, err := cast.ToInt32E(pidRange[0])
+					if err != nil {
+						return err
+					}
+					max, err := cast.ToInt32E(pidRange[1])
+					if err != nil {
+						return err
+					}
+					if min > max || max == 0 || min == 0 {
+						return fmt.Errorf("invalid PID Range is provided: min=%d, max=%d", min, max)
+					}
+					if max <= lastMax || min <= lastMax {
+						return fmt.Errorf("invalid PID Range is provided: {%d-%d}, ranges are overlapped, range items must be provided in increased order", min, max)
+					}
+					pid := types.Uint16Range{Min: min, Max: max}
+					pidRanges = append(pidRanges, &pid)
+					lastMax = max
+				}
+			}
+
 			// FIXME issue 99 VendorID
-			genAccount = dclauthtypes.NewAccount(ba, roles, []*dclauthtypes.Grant{}, []*dclauthtypes.Grant{}, vendorID)
+			genAccount = dclauthtypes.NewAccount(ba, roles, []*dclauthtypes.Grant{}, []*dclauthtypes.Grant{}, vendorID, pidRanges)
 
 			if err := genAccount.Validate(); err != nil {
 				return fmt.Errorf("failed to validate new genesis account: %w", err)
@@ -154,6 +184,7 @@ the address will be looked up in the local Keybase.
 	cmd.Flags().String(FlagRoles, "",
 		fmt.Sprintf("The list of roles (split by comma) to assign to account (supported roles: %v)", dclauthtypes.Roles))
 	cmd.Flags().String(FlagVID, "", "Vendor ID associated with this account. Required only for Vendor Roles")
+	cmd.Flags().String(FlagPIDs, "", "The list of Product ID ranges (split by \"-\") associated with this account (for example: 1-101,101-6554)")
 
 	cmd.Flags().String(flags.FlagHome, defaultNodeHome, "The application home directory")
 	cmd.Flags().String(flags.FlagKeyringBackend, flags.DefaultKeyringBackend, "Select keyring's backend (os|file|kwallet|pass|test)")

docker-compose.yml

@@ -122,4 +122,4 @@ networks:
     ipam:
       driver: default
       config:
-        - subnet: 192.167.10.0/16
+        - subnet: 192.167.10.0/24

docs/design/noc-root-cert-design.md

@@ -0,0 +1,123 @@
+# NOC Root Certificate Transactions Design
+
+## User Stories
+
+### 1. Add NOC Root Certificate
+A Vendor with DCL write privilege can submit a transaction to add a NOC root certificate associated with their Vendor ID.
+
+### 2. Revoke NOC Root Certificate
+A Vendor with DCL write privilege can submit a transaction to revoke a NOC root certificate associated with their Vendor ID.
+
+### 3. Remove NOC Root Certificate
+A Vendor with DCL write privilege can submit a transaction to remove a NOC root certificate associated with their Vendor ID. So that the Vendor can remove certificates that were added by mistake.
+
+## Certificate Schema
+
+To distinguesh NOC root certificates from others, an `isNOC` boolean field will be added to the [certificates](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/proto/pki/certificate.proto) schema 
+
+## Transactions
+
+### 1. ADD_NOC_X509_ROOT_CERTIFICATE
+This transaction adds a NOC root certificate owned by the Vendor.
+
+- Who can send: Vendor account
+- Validation:
+  - The provided certificate must be a root certificate:
+    - `Issuer` == `Subject`
+    - `Authority Key Identifier` == `Subject Key Identifier`
+  - No existing certificate with the same `<Certificate's Issuer>:<Certificate's Serial Number>` combination.
+  - If certificates with the same `<Certificate's Subject>:<Certificate's Subject Key ID>` combination already exist:
+    - The sender's VID must match the vid field of the existing certificates.
+  - No existing certificate with the same `<Certificate's Subject>:<Certificate's Subject Key ID>` combination already published by another vendor.
+  - The signature (self-signature) and expiration date must be valid.
+- Parameters:
+  - cert: `string` - The NOC Root Certificate, encoded in X.509v3 PEM format. Can be a PEM string or a file path.
+- In State:
+  - `pki/ApprovedCertificates/value/<Subject>/<SubjectKeyID>`
+  - `pki/ApprovedCertificatesBySubject/value/<Subject>`
+  - `pki/NOCRootCertificates/value/<VID>`
+- CLI Command:
+  - `dcld tx pki add-noc-x509-root-cert --certificate=<string-or-path> --from=<account>`
+
+### 2. REVOKE_NOC_X509_ROOT_CERTIFICATE
+This transaction revokes a NOC root certificate owned by the Vendor.
+Revoked NOC root certificates can be re-added using the `ADD_NOC_X509_ROOT_CERTIFICATE` transaction.
+
+- Who can send: Vendor account
+  - Vid field associated with the corresponding NOC root certificate on the ledger must be equal to the Vendor account's VID.
+- Validation:
+  - A NOC Root Certificate with the provided `subject` and `subject_key_id` must exist in the ledger.
+- Parameters:
+  - subject: `string` - Base64 encoded subject DER sequence bytes of the certificate.
+  - subject_key_id: `string` - Certificate's `Subject Key Id` in hex string format, e.g., `5A:88:0E:6C:36:53:D0:7F:B0:89:71:A3:F4:73:79:09:30:E6:2B:DB`.
+  - serial_number: `optional(string)` - Certificate's serial number. If not provided, the transaction will revoke all certificates that match the given `subject` and `subject_key_id` combination.
+  - info: `optional(string)` - Information/notes for the revocation.
+  - time: `optional(int64)` - Revocation time (number of nanoseconds elapsed since January 1, 1970 UTC). CLI uses the current time for that field.
+  - revokeChild: `optional(bool)` - If true, then all certificates in the chain signed by the revoked certificate (intermediate, leaf) are revoked as well. If false, only the current root cert is revoked (default: false).
+- In State:
+  - `pki/RevokedCertificates/value/<subject>/<subject_key_id>`
+  - `pki/RevokedNOCRootCertificates/value/<subject>/<subject_key_id>`
+- CLI Command:
+  - `dcld tx pki revoke-noc-x509-root-cert --subject=<base64 string> --subject-key-id=<hex string> --serial-number=<string> --info=<string> --time=<int64> --revokeChild=<bool> --from=<account>`
+
+### 3. REMOVE_NOC_X509_ROOT_CERTIFICATE
+This transaction completely removes a NOC root certificate owned by the Vendor. 
+Removed NOC root certificates can be re-added using the `ADD_NOC_X509_ROOT_CERTIFICATE` transaction.
+
+Revoked certificates that match the specified parameters will also be removed.
+
+The certificates in the chain signed by the removed certificate (intermediate, leaf) will not be removed.
+
+- Who can send: Vendor account
+  - Vid field associated with the corresponding NOC root certificate on the ledger must be equal to the Vendor account's VID.
+- Validation:
+  - A NOC root certificate with the provided `subject` and `subject_key_id` must exist in the ledger.
+- Parameters:
+  - subject: `string` - Base64 encoded subject DER sequence bytes of the certificate.
+  - subject_key_id: `string` - Certificate's `Subject Key Id` in hex string format, e.g., `5A:88:0E:6C:36:53:D0:7F:B0:89:71:A3:F4:73:79:09:30:E6:2B:DB`.
+  - serial_number: `optional(string)` - Certificate's serial number. If not provided, the transaction will remove all certificates that match the given `subject` and `subject_key_id` combination.
+  - info: `optional(string)` - Information/notes for the removal.
+- CLI Command:
+  - `dcld tx pki remove-noc-x509-root-cert --subject=<base64 string> --subject-key-id=<hex string> --serial-number=<string> --info=<string>  --from=<account>`
+
+## Query
+
+To retrieve NOC certificates by Subject and Subject Key Identifier, use the [GET_X509_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_x509_cert) or [GET_ALL_SUBJECT_X509_CERTS](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_all_subject_x509_certs:) query.
+
+To retrieve a revoked NOC certificate by Subject and Subject Key Identifier, use the [GET_REVOKED_CERT](https://github.com/zigbee-alliance/distributed-compliance-ledger/blob/master/docs/transactions.md#get_revoked_cert)
+
+### GET_NOC_X509_ROOT_CERTS_BY_VID
+
+Retrieve NOC root certificates associated with a specific VID. 
+
+- Who can send: Any account
+- Parameters:
+  - vid: `uint16` - Vendor ID (positive non-zero)
+- CLI Command:
+  - `dcld query pki get_noc_x509_root_certs --vid=<uint16>`
+- REST API:
+  - GET `/dcl/pki/noc-root-certificates/{vid}`
+
+### GET_ALL_NOC_X509_ROOT_CERTS
+
+Retrieve a list of all of NOC root certificates
+
+- Who can send: Any account
+- Parameters:
+  - Common pagination parameters
+- CLI Command:
+  - `dcld query pki get_all_noc_x509_root_certs`
+- REST API:
+  - GET `/dcl/pki/noc-root-certificates`
+
+### GET_ALL_REVOKED_NOC_X509_ROOT_CERTS
+
+Gets all revoked NOC root certificates.
+
+- Who can send: Any account
+- Parameters:
+  - Common pagination parameters
+- CLI command:
+  - `dcld query pki all-revoked-noc-x509-root-certs`
+- REST API:
+  - GET `/dcl/pki/revoked-noc-root-certificates`

docs/design/schema-compatibility.md

@@ -0,0 +1,120 @@
+# Support for forward and backward compatibility in DCL schemes
+
+Schema changes can cover a wide range of modifications with varying impacts on application compatibility and data integrity. Below are use cases with strategies to manage schema changes and ensure compatibility.
+
+## I. Multiple versions can live in parallel
+
+### 1. Strategy for Compatible Changes
+
+For changes that are backward-compatible, such as adding optional fields or extending enumerations.
+
+#### Option A: Add an optional version field to all DCL schema
+
+**Description:**
+Implement an optional version field in all DCL schemas to track the schema version. This approach is simple and quick to execute, suitable primarily for compatible updates.
+
+**Strategy steps:**
+
+- One time actions:
+  - Add an optional version field to all DCL schema
+- For each update:
+  - Update the schema by introducing compatible changes (such as adding a new optional field).
+  - Update transactions and queries if needed.
+  - DCL doesn't fulfill the Schema version automatically
+  - It will be up to the transaction submitter (Vendor) to specify a correct Schema version
+  - If Schema Version is not set - then the initial version (version 0 or 1) is assumed
+  - It will be up to the client application to process the Schema version
+
+### 2. Strategy for Non-Compatible Changes
+
+For significant changes that directly impact compatibility, such as adding mandatory fields or removing fields, splitting or merging schemas, changing enumerations.
+
+#### Option B: Separate Schemas for Each Version
+
+**Description:**
+Each version has its distinct schema, state and its own queries/requests. This strategy eliminates the need for data migration and allows different schema versions to coexist seamlessly.
+
+**Strategy steps:**
+
+- For each update:
+  - Create a new version of a Schema and state (a new .proto file)
+  - Implement transactions and queries for the new schema version.
+
+#### Option C: Generic Schema Storage (Not Recommended for Production)
+
+**Description:**
+Implement a flexible, generic schema structure that can support a wide range of data formats.
+
+While offering a robust solution for handling radical changes, this method requires careful planning and development, which can potentially take a significant amount of time.
+
+**Strategy steps:**
+
+- One time actions:
+  - Create a more flexible, generic schema structure to hold a wide range of data formats (Can be used [Any](https://github.com/protocolbuffers/protobuf/blob/main/src/google/protobuf/any.proto) as described in [ADR-19](https://docs.cosmos.network/v0.47/build/architecture/adr-019-protobuf-state-encoding#usage-of-any-to-encode-interfaces))
+  - Migrate old states to the newer, generic schema.
+  - Remove the states associated with the older schema versions.
+  - Optioanlly can be implemented queries for requesting schemas with any return type
+- For each update:
+  - Create a new Schema version (a new .proto file)
+  - Implement transactions and queries that can handle data according to its version, including mechanisms for converting generic values into the corresponding schema version.
+
+## II. New version replaces the legacy one (V2 replaces V1)
+
+### 1. Strategy for Compatible or Convertible changes
+
+For changes that are backward-compatible, such as adding optional or mandatory fields or extending enumerations
+
+#### Option D: Not keeping backward compatibility in API
+
+**Description:**
+This strategy focuses on updating the schema without ensuring backward compatibility at the API level. Since the schemas are compatible, there will likely be no need for migration.
+
+**Strategy steps:**
+
+- For each update:
+  - Update the schema by introducing compatible changes (such as adding a new optional field).
+  - Migrate old states to the newer if needed.
+  - Update transactions and queries if needed.
+
+#### Option E: Keeping backward compatibility in API
+
+**Description:**
+The main idea of this strategy is the dynamically converting newer schemas into older ones. However, this method is only possible if there is compatibility between the newer and legacy schemas, allowing them to be converted to each other. Due to the on-the-fly data conversion, this approach does not support the Light Client in legacy APIs because the converted data is not stored in the state, preventing the generation of proofs.
+
+**Strategy steps:**
+
+- For each update:
+  - Create a new version of a Schema and state (a new .proto file)
+  - Migrate older states to newer schema version.
+  - Remove the states associated with the older schema versions.
+  - Implement transactions and queries for the new schema version.
+  - Update older transactions and queries to converting data between the latest and older schema version,  ensuring backward compatibility.
+  - There will be separated API for each version of the schema, for example::
+    - models/vid/pid
+    - modelsV2/vid/pid
+    - modelsV3/vid/pid
+
+### 2. Strategy for Non-Compatible changes
+
+For significant changes that directly impact compatibility, such as adding mandatory fields or removing fields, splitting or merging schemas, changing enumerations.
+
+#### Optiona F: Not keeping backward compatibility in API
+
+**Description:**
+This strategy focuses on updating the schema without ensuring backward compatibility at the API level. Since the schemas are not compatible, migration is carried out manually through a special transaction.
+
+**Strategy steps:**
+
+- For each update:
+  - Update the schema by introducing changes.
+  - Update transactions and queries if needed.
+  - Add a new transaction to fulfill new required fields (essentially this is a manual migration via transactions)
+
+#### Option G: Keeping backward compatibility in API
+
+**Description:**
+It's not possible to replace an old version here. [Multiple versions can live in parallel: Strategy for Non-Compatible Changes](#2-strategy-for-non-compatible-changes) options should be used instead.
+
+## Conclusion
+
+To lay the foundation for future compatibility improvements, it's a good idea to start by adding a version field to each schema. For subsequent changes, we will then select the most appropriate strategy based on the nature of these changes.

docs/how-to.md

@@ -127,7 +127,7 @@ Once approved the account can be used to send transactions. See [use_case_txn_au
 ### 1. Create an Account proposal for the user
 
 ```bash
-dcld tx auth propose-add-account --address=<bench32 encoded string> --pubkey=<protobuf JSON encoded> --roles=<role1,role2,...> --vid=<uint16> --from=<account>
+dcld tx auth propose-add-account --address=<bench32 encoded string> --pubkey=<protobuf JSON encoded> --roles=<role1,role2,...> --vid=<uint16> --pid_ranges=<uint16-range,uint16-range,...> --from=<account>
 ```
 
 ### 2. Approve proposed Account
@@ -211,6 +211,7 @@ Minimal command:
 ```bash
  dcld tx model add-model --vid=<uint16> --pid=<uint16> --deviceTypeID=<uint16> --productName=<string> --from=<account>
 ```
+Note that if `account` was created with product ID ranges then the `pid` must fall within that specified range
 
 Full command:
 
@@ -229,6 +230,7 @@ Minimal command:
 dcld tx model add-model-version --vid=<uint16> --pid=<uint16> --softwareVersion=<uint32> --softwareVersionString=<string> --cdVersionNumber=<uint32>
 --minApplicableSoftwareVersion=<uint32> --maxApplicableSoftwareVersion=<uint32> --from=<account>
 ```
+Note that if `account` was created with product ID ranges then the `pid` must fall within that specified range
 
 Full command:
 
@@ -250,12 +252,14 @@ dcld tx vendorinfo update-vendor --vid=<uint16> ... --from=<account>
 ```bash
 dcld tx model update-model --vid=<uint16> --pid=<uint16> ... --from=<account>
 ```
+Note that if `account` was created with product ID ranges then the `pid` must fall within that specified range
 
 ### 7. Edit Model Version
 
 ```bash
 dcld tx model update-model-version --vid=<uint16> --pid=<uint16> --softwareVersion=<uint32> ... --from=<account>
 ```
+Note that if `account` was created with product ID ranges then the `pid` must fall within that specified range
 
 ### 8. Add PKI Revocation Distribution Point