Skip to content

Commit

Permalink
Add table to describe the individual SCDL metadata attributes
Browse files Browse the repository at this point in the history
  • Loading branch information
@ghareeb-falazi
ghareeb-falazi committed Jun 23, 2024
1 parent 18d1dfd commit b96a34e
Show file tree
Hide file tree
Showing 2 changed files with 39 additions and 1 deletion.
40 changes: 39 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,44 @@ The metamodel does not explicitly provide any **extensibility** points. If addit

As for now, the specification assumes that there exists a suitable agreement between the provider and the consumer regarding the *costs* the provider may incur when executing smart contracts on behalf of the external consumer (internal consumers are charged directly by the blockchain platform).

The table below summarizes SCDL metadata attributes and their semantics:

| Attribute | Type | Description |
|-------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| SCDLVersion | Integer | the SCDL language version used. For compatibility with the current specification, this value must be "2.0.0". |
| Address | URL | the SCL address of the smart contract instance. |
| CreationDate | Date | the date in which the SCD was created. |
| Description | String | human-readable description of the smart contract. |
| LatestVersion | URL | a URL to the latest SCD that describes this smart contract instance in case multiple SCDs exist for it. |
| BCType | String | the hosting blockchain system type, e.g., "hyperledger-fabric". |
| BCVersion | String | the specific protocol version of the blockchain system hosting the smart contract instance. The transaction processing guarantees and other characteristics of blockchain transactions might differ based on the specific blockchain protocol version. |
| BCInternalAddress | String | the smart contract instance address within the hosting blockchain system. The format depends on BCType. |
| SCName | String | the name of the smart contract. |
| SCState | enum | the state of the smart contract instance. Possible values are "READY" and "DESTROYED". |
| SCVersion | String | the version of the smart contract. |
| SCAuthor | String | the name of the smart contract author. |
| SCLanguage | String | the programming language used to implement the smart contract. For some platforms, the specific choice of programming language affects the supported features. |
| SCLanguageVersion | String | the language version used for programming the smart contract. |
| SCMetadata | URL | a URL to the machine-readable metadata that is produced when the smart contract is compiled and packaged. |
| Functions | Function[] | non-private smart contract functions. |
| Event | Event[] | the events that might be emitted during function execution. |
| SCCodeHash | String | the SHA256 hash of the smart contract code. This can be used to verify the integrity of a given source code file.
| __Entity-Specific Attributes__ |||
| Function.OnlyExternal | Boolean | a Boolean that takes the value _true_ iff the function is only accessible via external consumers. |
| Function.SideEffects | Boolean | a Boolean that takes the value _true_ iff executing the function might result in altering the smart contract instance state. |
| Function.SupportsTx | Boolean | a Boolean that takes the value _true_ iff the function can be invoked as part of an atomic distributed transaction. |
| Function.Inputs | Parameter[] | an ordered array of input parameters for the function. |
| Function.Outputs | Parameter[] | an ordered array of output parameters for the function. |
| Function.Events | Event[] | a set of events that might be emitted during function execution. |
| Function.Description | String | a human-readable description of the function. |
| Event.Name | String | the name of the smart contract event. |
| Event.Params | EventParameter[] | the parameters that accompany the occurrences of the event. |
| Event.Description | String | a human-readable description of the event. |
| Parameter.Name | String | the name of the parameter. |
| Parameter.Type | SCDLDataType | the type of the parameter (see \cref{ch3-sec:handling-data-types-in-scdl} for more details). |
| Parameter.Description | String | a human-readable description of the parameter. |
| EventParameter.Indexed | Boolean | a Boolean that takes the value _true_ iff the event parameter is indexed, i.e., the blockchain system allows searching for event occurrences using this parameter as a filter. | |

## JSON binding
The default syntax for the documents that follow the SCDL metamodel, i.e., Smart Contract Descriptors (SCDs), uses JSON.
The reason behind this choice is that clients of all analyzed smart contract platforms are required to communicate with the blockchain nodes using JSON payloads in order to interact with the hosted smart contracts.
Expand Down Expand Up @@ -78,7 +116,7 @@ Note that some SCDL Data Types do not necessarily have corresponding datatypes i
For example, the SCDL Data Type that represents a Boolean value does not have a corresponding datatype in Hyperledger Fabric.
This does not constitute a problem, since any given SCD is specific to a particular smart contract instance hosted on a fixed blockchain system, which means it will only contain SCDL Data Types that do have mappings to this system.

These mappings are used when generating an SCD based on the code of a given smart contract and also when a software component, e.g., the gateway presented in \cref{sec:ch3-concept}, needs to communicate with a smart contract instance with the help of a given SCD.
These mappings are used when generating an SCD based on the code of a given smart contract and also when a software component needs to communicate with a smart contract instance with the help of a given SCD.

Using JSON Schema as a basis for SCDL Data Types enables client applications to use existing JSON Schema validation libraries to validate user-provided data before trying to communicate with actual smart contract instances using [SCIP](https://github.com/lampajr/scip).
Of course, client applications must have access to the SCDs that describe the target smart contract instances in order to extract the SCDL Data Types from them.
Expand Down
Binary file modified metamodel.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit b96a34e

Please sign in to comment.