Merge pull request #62 from Concordium/CIS6-track-and-trace-standard

Add CIS6 standard

Author: DOBEN

.github/workflows/lint.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
-    container: sphinxdoc/sphinx
+    container: sphinxdoc/sphinx:7.0.0
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v2.3.1
@@ -22,15 +22,15 @@ jobs:
         run: |
           apt-get update
           apt-get install -y git rsync
-          pip3 install -r requirements.txt
+          pip3 install -r requirements.txt      
 
       - name: Lint 🔍
         shell: bash
         run: doc8 source
 
   build:
     runs-on: ubuntu-latest
-    container: sphinxdoc/sphinx
+    container: sphinxdoc/sphinx:7.0.0
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v2.3.1

requirements.txt

@@ -34,3 +34,4 @@ sphinxcontrib-serializinghtml==1.1.5
 stevedore==3.4.0
 tornado==6.1
 urllib3==1.26.6
+

source/CIS/cis-6.rst

@@ -0,0 +1,118 @@
+.. _CIS-6:
+
+===============================
+CIS-6: Track-and-Trace Standard
+===============================
+
+.. list-table::
+   :stub-columns: 1
+
+   * - Created
+     - Apr 25, 2024
+   * - Final
+     - Apr 26, 2024
+   * - Supported versions
+     - | Smart contract version 1 or newer
+       | (Protocol version 4 or newer)
+   * - Standard identifier
+     - ``CIS-6``
+   * - Requires
+     - :ref:`CIS-0<CIS-0>`
+
+
+Abstract
+========
+
+A standard interface that defines the logged events for tracking items in a smart contract.
+The interface defines two events:
+
+- *ItemCreatedEvent* logs the ``item_id``, ``metadata_url``, and the ``initial_status``;
+- *ItemStatusChangedEvent* logs the ``item_id``, ``new_status``, and the ``additional_data``;
+
+Specification
+=============
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in :rfc:`2119`.
+
+
+General types and serialization
+-------------------------------
+
+.. _CIS-6-ItemId:
+
+``ItemId``
+^^^^^^^^^^
+
+Each item MUST have a unique ``ItemId``.
+An ``ItemId`` is a variable-length ASCII string up to 255 characters.
+
+The identifier is serialized as: 1 byte for the length (``n``) followed by this many bytes for the ASCII encoding of the identifier::
+
+  ItemId ::= (n: Byte) (id: Byteⁿ)
+
+.. _CIS-6-MetadataUrl:
+
+``MetadataUrl``
+^^^^^^^^^^^^^^^
+
+A URL and optional checksum for metadata stored outside of this contract.
+
+It is serialized as: 2 bytes for the length (``n``) of the metadata URL in little-endian and then this many bytes for the URL to the metadata (``url``) followed by an optional checksum.
+The checksum is serialized by 1 byte to indicate whether a hash of the metadata is included.
+If its value is 0, then there is no hash; if the value is 1, then 32 bytes for a SHA256 hash (``hash``) follows::
+
+  MetadataChecksum ::= (0: Byte)
+                     | (1: Byte) (hash: Byte³²)
+
+  MetadataUrl ::= (n: Byte²) (url: Byteⁿ) (checksum: MetadataChecksum)
+
+.. _CIS-6-Status:
+
+``Status``
+^^^^^^^^^^
+
+The status defined by this specification is serialized using one byte to discriminate the different statuses that an item can have.
+The smart contract can have up to 255 different statuses defined for an item.
+
+It is serialized as: a byte of value (``n``)::
+
+  Status ::= (n: Byte)
+
+.. _CIS-6-AdditionalData:
+
+``AdditionalData``
+^^^^^^^^^^^^^^^^^^
+
+Additional bytes to include in the event ``ItemStatusChangedEvent``, which can be used to add additional use-case-specific data (e.g. temperature, longitude, latitude, ...) to the event.
+
+It is serialized as: the first 2 bytes encode the length (``n``) of the data, followed by this many bytes for the data (``data``)::
+
+  AdditionalData ::= (n: Byte²) (data: Byteⁿ)
+
+Logged events
+-------------
+
+The events defined by this specification are serialized using one byte to discriminate the different events.
+A custom event SHOULD NOT have a first byte colliding with any of the events defined by this specification.
+
+.. _CIS-6-events-ItemCreatedEvent:
+
+``ItemCreatedEvent``
+^^^^^^^^^^^^^^^^^^^^
+
+A ``ItemCreatedEvent`` event MUST be logged when a new item is created in the smart contract.
+
+The ``ItemCreatedEvent`` event is serialized as: first a byte with the value of 237, followed by the :ref:`CIS-6-ItemId` (``id``), the :ref:`CIS-6-MetadataUrl` (``metadata``), and then the :ref:`CIS-6-Status` (``initial_status``)::
+
+  ItemCreatedEvent ::= (237: Byte) (item_id: ItemId) (metadata: MetadataUrl) (initial_status: Status)
+
+.. _CIS-6-events-ItemStatusChangedEvent:
+
+``ItemStatusChangedEvent``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A ``ItemStatusChangedEvent`` event MUST be logged when an item status is updated in the smart contract state.
+
+The ``ItemStatusChangedEvent`` event is serialized as: first a byte with the value of 236, followed by the :ref:`CIS-6-ItemId` (``id``), the :ref:`CIS-6-Status` (``new_status``), and then the :ref:`CIS-6-AdditionalData` (``additional_data``)::
+
+  ItemStatusChangedEvent ::= (236: Byte) (item_id: ItemId) (new_status: Status) (additional_data: AdditionalData)

source/index.rst

@@ -21,4 +21,5 @@ Concordium Interoperability Specifications
    CIS/cis-2
    CIS/cis-3
    CIS/cis-4
+   CIS/cis-6
    ID/concordium-did.rst