Chaincode Structure - OpenScienceChain/OSC-IS_Doc GitHub Wiki

OSC-IS Chaincode

In Hyperledger Fabric, a chaincode is a program that implements the business logic of an application on the blockchain. The role and purpose of the chaincode in a channel is to define and enforce the rules and policies for the transactions within the channel.

Some of the main functions that a chaincode provides are:

  1. Define the data model: Chaincode defines the data model for the channel, which specifies the types of data that can be stored on the blockchain and how it can be accessed.
  2. Define the business logic: Chaincode implements the business logic for the transactions on the channel. This includes validating the transactions, enforcing access control policies, and updating the state of the ledger.
  3. Maintain the ledger: Chaincode maintains the current state of the ledger, which includes the current balances and other data relevant to the transactions on the channel.
  4. Ensure transaction confidentiality: Chaincode ensures the confidentiality of the transactions by encrypting the data and providing access control mechanisms to prevent unauthorized access.
  5. Enable versioning and upgradability: Chaincode enables versioning and upgradability of the application logic, which allows for updates and improvements to be made without disrupting the existing transactions on the channel.

While a chaincode is not strictly an object-oriented program with classes, you can define a data struct within the chaincode that can be used to represent a data structure and operate on it within the functions of the chaincode. In OSC-IC, we will handle these data structs as if they were classes in the classical object-oriented sense, though these data structs don't incorporate functions as a class normally would do.

The main entities or data structs that our OSC-IS chaincode will handle are: Data, Schema, User, and Group.

Chaincode Data Structs

Data

Data struct, a.k.a Asset, represents the data that users will submit to the ledger. This information is intended to be kept public in the network, so each organization will be able to see what other organizations are submitting in the ledger. The Data Struct will be defined by the following attributes:

  • OrgName: Name of the Organization owning the Data/Asset
  • ProjectName: Name of the Project that will own this data. More on Projects later in this document.
  • JsonContent: Content of the Json File containing the relevant data for the research group. When a user submits data to the ledger, a JSON file is required. This JSON file contains relevant information for the group.
  • ContentHash: When the JSON file is submitted, a hash on that file is calculated. This Hash value is used as the key for storing the data in the ledger.
  • Comment: Just a small comment users use to identify/characterize their submission.
  • APIUserID: An email address would be the most common form of this attribute. Generally, it's provided by the Orgs portal/API or OSC-IS portal/API.
  • UUID: The Unique Identifier of the User that subscribed the data struct to the blockchain in the 1st place.
  • Date: Date data is submitted/modified.

Schema

Type Schema describes the data struct used to validate the content of Json Files when a user tries to submit new data to the ledger. Schema Data structs are submitted to the org's Private Data Collection (PDC), not to the Ledger. We will discuss on PDCs later. Its attributes are:

  • JsonSchemaContent: Content of the JSON file that contains the schema against which incoming data needs to be validated.
  • SchemaId: String that uniquely identifies a Schema.
  • Project: Name of the Project that will own this data.

User

Type User describes the attributes of a person using the HLfabric to perform transactions. This data struct will also go to the respective org's PDC, not the public ledger. It's attributes are:

  • UUID: Unique user identifier. This will uniquely identify a user in the organization.
  • APIUserId: Same as explained in Data Struct.
  • Groups: List of groups the user is part of.
  • Projects: List of projects the user is part of.
  • Org: Organization the user is part of. We will have a 1 to 1 relationship between UUID and Org, meaning that if a person is part of 2 or more orgs, that person will have one UUID for each org she is part of.

Group

  • GID: Group Identifier. GID = "OrgName.ProjectName.GroupName". It is unique for each group. A group can be a project. In that case, PID = GID = "OrgName.ProjectName.ProjectName"
  • GroupName: Name of the group., Could be either 'Admin' or 'Users'. Members of the 'Admin' group generally have more privileges. There is the possibility to create more groups in a project.
  • Project: A.k.a Project identifier (PID) of the project the group belongs to. PID = "OrgName.ProjectName"
  • Org: Org name the group is part of.
  • Users: Array of Users belonging to Group
  • Groups: Used when creating a Project. A project will hold information about groups. In case a group is a project, this attribute will contain a list of groups that are part of the project. Otherwise, it is empty.

Namespace

In the next figure, we explain the namespace used to reference every entity/Struct/Class in the chaincode. We use an example organization that in this case we will call "CaseWestrnU", referencing the Case Western University. This organization will be composed of one or more projects. A project is a team or a set of people within the organization that carries out a specific research work. For example, let's say that the Nanomagnetism research group of Professor X of the Case Western University wants to participate in the OSC-IS network to keep their data provenance safe. In that case, Professor X and her colleagues may subscribe their research group as a project to the OSC-IS network. The project is part of the Case Western University organization. The project will have at least 2 Groups: 'Admin' and 'Users'. The identifier of a project, or PID, is to be constructed like this: PID = "OrgName.ProjectName". In the example above, we have PID = "CaseWestrnU.NanomagnetismProject", where NanomagnetismProject is the name of the project referencing the team of Professor X. The identifier of every group, or GID, is to be constructed in a similar manner: GID = "OrgName.ProjectName.GroupName". Continuing with the example, we would have the Admin and Users groups as: "CaseWestrnU.NanomagnetismProject.Admin", and "CaseWestrnU.NanomagnetismProject.Users".

The figure below should summarize the namespace for a general case:

Projects as Groups (Disclaimer)

If you're a developer of the OSC-IS initiative, you need to be aware of this subtle technicality: Projects in the chaincode are created using the Groups struct. Inside the chaincode, a Project is, in essence, a Group that will host at least 2 different groups, namely: Admins and Users.

For practical purposes, you can think of a project as a different entity in the network, but you should keep the above technicality in mind in case you want to do development work on the chaincode.