{"id":107612,"date":"2023-08-09T21:43:46","date_gmt":"2023-08-09T21:43:46","guid":{"rendered":"https:\/\/wp.dash.org\/?p=107612"},"modified":"2023-08-12T03:24:10","modified_gmt":"2023-08-12T03:24:10","slug":"dash-platform-data-contracts","status":"publish","type":"post","link":"https:\/\/wp.dash.org\/blog\/dash-platform-data-contracts\/","title":{"rendered":"Dash Platform Data Contracts"},"content":{"rendered":"
Everyone in Web3 already knows of\u00a0smart contracts<\/span>,\u00a0the groundbreaking innovation of Ethereum that popularized the concept of a\u00a0dapp. However, few are aware of Dash Platform\u2019s new supplement to smart contracts that will make dapp development more accessible to the masses:\u00a0data contracts<\/span>.<\/span><\/p>\n Data contracts are a powerful tool already used widely across the Web2 data services\u00a0landscape due to their many benefits to user and developer experience. They\u2019re relatively simple JSON schemas that define the structures of data a dapp can store. Utilizing them in Dash Platform allows us to take advantage of their traditional benefits\u00a0while\u00a0also enabling Web2 developers to store their app data on a decentralized Web3 platform without needing to\u00a0learn a smart\u00a0contract language like Solidity. Rather, they can easily do so just by using constructs they\u2019re already familiar with.<\/span><\/p>\n In addition to greater accessibility and smoother user experience, data contracts also enable a variety of other useful features, such as easy indexing, versioning, and\u00a0built-in documentation. Ultimately, they will assist in the cultivation of a diverse ecosystem of Dash-based dapps, and more widespread adoption for crypto as a whole.<\/p>\n This article accompanies the release of\u00a0dashpay.io<\/a><\/span>, a web app where users can automatically generate a data contract based on descriptions of their intended dapp using AI. We will begin by walking through the high-level architecture and applications of data contracts before going back and diving deeper into the architecture details.<\/span><\/p>\n At a high level, a Dash Platform data contract is a JSON schema that defines the structures of the data a dapp will store. It\u00a0defines the\u00a0allowed properties<\/span>, such as \u201ccity\u201d or \u201ccuisine\u201d for a restaurant dapp, the\u00a0validation logic<\/span>, such as the \u201cmaxLength\u201d of a string property, and the\u00a0indexes<\/span>\u00a0created on the properties. Developers must submit their data contracts to Platform for system-level validation before the users of their dapps may submit documents to their data contracts for dapp-level validation. This ensures that the dapp data will play nicely with the rest of the system while giving developers control over the structure and types of data that can be submitted to their dapps. Data contracts are therefore useful for a number of reasons beyond just enabling an easy transition from Web2 to Web3:<\/span><\/p>\n While smart contracts, which are a top priority following the launch of v1, will synergize with data contracts to enable a much wider range of capabilities for dapps on Dash Platform, there are still many possibilities with data contracts alone. Dash Incubator developer Pshenmic has provided us with a few examples he\u2019s personally excited about:<\/span><\/p>\n If you\u2019re interested in reading more about possible applications that data contracts enable on Dash Platform, check out this awesome 2021 article from Hackernoon:\u00a0Building dapps On Dash: An Interview With readme<\/a><\/span>.<\/span><\/p>\n Now, onto the architecture.<\/span><\/p>\n As already stated above, a Dash Platform data contract is a JSON schema that defines the structures of the data a dapp can store. It\u00a0defines the\u00a0allowed properties,\u00a0the\u00a0validation logic, and the\u00a0indexes\u00a0created on the properties.<\/span><\/p>\n A Dash Platform data contract\u00a0JSON\u00a0schema must define at least one\u00a0document type<\/span>. A document type defines a type of\u00a0document<\/a><\/span>\u00a0that can be submitted to a data contract. They require three fields:\u00a0 Figure 1: A Dash Platform data contract with one document type, \u201cnft\u201d.<\/em><\/p>\n Document types<\/span>\u00a0in Dash Platform are JSON objects, and therefore must specify\u00a0<\/span> Figure 2: A valid document (with some truncated fields) that could be submitted to the data contract in Figure 1.<\/em><\/p>\n In this document, all the properties listed in the data contract\u2019s\u00a0<\/span> In addition to the user-defined properties, like\u00a0<\/span> See the\u00a0<\/span>DPNS<\/a><\/span>\u00a0and\u00a0<\/span>Dashpay<\/a><\/span>\u00a0data contracts for two real-world examples that utilize more than one document type.<\/span><\/p>\n Before leaving off with Additional Architecture Details, which might be too involved for some readers, I\u2019ll wrap up now by saying you may also be interested in checking out the data contract\u00a0<\/span>documentation<\/a><\/span>\u00a0for further information, and as always, the community, including Dash Core Group and myself, is available to field questions and suggestions on the\u00a0<\/span>Dash Discord<\/a><\/span>.<\/span><\/p>\n Finally, don\u2019t forget to check out\u00a0<\/span>dashpay.io<\/a><\/span>\u00a0(Github repo\u00a0<\/span>here<\/a><\/span>), where you can use AI to automatically generate a data contract based on a description of your intended dapp, use a dynamic form to tweak it to perfection, and save time and money by validating your data contract before submitting it to Dash Platform.<\/span><\/p>\n The data contract in Figure 1 defines three indices:\u00a0<\/span> <\/p>\n Figure 3: The structure of a document type tree in Dash Platform.<\/em><\/p>\n In the GroveDB structure of Dash Platform, all data contracts and their corresponding documents are stored in the Contract Documents tree, which is a subtree of the Root tree. The diagram below shows the path from the Root tree to the \u201cnft\u201d document type tree shown in the diagram above.<\/span><\/p>\n <\/p>\n Figure 4: The path from the Dash Platform Root Tree to the \u201cnft\u201d document type tree from Figure 3.<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"Everyone in Web3 already knows of\u00a0smart contracts,\u00a0the groundbreaking innovation of Ethereum that popularized the concept of a\u00a0dapp. However, few are aware of Dash Platform\u2019s new supplement to smart contracts that will make dapp development more accessible to the masses:\u00a0data contracts. Data contracts are a powerful tool already used widely across the Web2 data services\u00a0landscape due…","protected":false},"author":70,"featured_media":107591,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"inline_featured_image":false,"footnotes":"","_links_to":"","_links_to_target":""},"categories":[290],"tags":[],"class_list":["post-107612","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog"],"acf":[],"yoast_head":"\nApplication<\/span><\/h3>\n
\n
\n
\n
\n
\n
\n
Architecture<\/h3>\n
type<\/code>,\u00a0
properties<\/code>, and\u00a0
additionalProperties<\/code>, and support two optional fields:\u00a0
indices<\/code>\u00a0and\u00a0
required<\/code>. A data contract with one document type,\u00a0nft, that employs all five fields, might look like this, for example:<\/p>\n
{\r\n \"nft\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"name\": {\r\n \"type\": \"string\",\r\n \"description\": \"Name of the NFT token\",\r\n \"maxLength\": 63\r\n },\r\n \"description\": {\r\n \"type\": \"string\",\r\n \"description\": \"Description of the NFT token\",\r\n \"maxLength\": 256\r\n },\r\n \"imageUrl\": {\r\n \"type\": \"string\",\r\n \"description\": \"URL of the image associated with the NFT token\",\r\n \"maxLength\": 2048,\r\n \"format\": \"uri\"\r\n },\r\n \"imageHash\": {\r\n \"type\": \"array\",\r\n \"description\": \"SHA256 hash of the bytes of the image specified by tokenImageUrl\",\r\n \"byteArray\": true,\r\n \"minItems\": 32,\r\n \"maxItems\": 32\r\n },\r\n \"imageFingerprint\": {\r\n \"type\": \"array\",\r\n \"description\": \"dHash the image specified by tokenImageUrl\",\r\n \"byteArray\": true,\r\n \"minItems\": 8,\r\n \"maxItems\": 8\r\n },\r\n \"price\": {\r\n \"type\": \"number\",\r\n \"description\": \"Price of the NFT token in Dash\",\r\n \"minimum\": 0\r\n },\r\n \"quantity\": {\r\n \"type\": \"integer\",\r\n \"description\": \"Number of tokens in circulation\",\r\n \"minimum\": 0\r\n },\r\n \"metadata\": {\r\n \"type\": \"array\",\r\n \"description\": \"Any additional metadata associated with the NFT token\",\r\n \"byteArray\": true,\r\n \"minItems\": 0,\r\n \"maxItems\": 2048\r\n }\r\n },\r\n \"indices\": [\r\n {\r\n \"name\": \"price\",\r\n \"properties\": [\r\n {\r\n \"price\": \"asc\"\r\n }\r\n ]\r\n },\r\n {\r\n \"name\": \"quantity\",\r\n \"properties\": [\r\n {\r\n \"quantity\": \"asc\"\r\n }\r\n ]\r\n },\r\n {\r\n \"name\": \"priceAndQuantity\",\r\n \"properties\": [\r\n {\r\n \"price\": \"asc\"\r\n },\r\n {\r\n \"quantity\": \"asc\"\r\n }\r\n ]\r\n }\r\n ],\r\n \"required\": [\r\n \"name\",\r\n \"price\",\r\n \"quantity\"\r\n ],\r\n \"additionalProperties\": false\r\n }\r\n}<\/code><\/pre>\n<\/div>\n
\"type\":\"object\"<\/code>. They must also specify\u00a0a set of\u00a0<\/span>
properties<\/code>\u00a0containing\u00a0<\/span>at least one property<\/span>,\u00a0<\/span>and\u00a0<\/span>
\"additionalProperties\":false<\/code>. Optionally, they may also include a list of\u00a0<\/span>
indices<\/code>\u00a0and a list of\u00a0<\/span>
required<\/code>\u00a0properties. Here is an example of a valid\u00a0<\/span>
nft<\/code>\u00a0document (with some truncated fields) that could be submitted to the above data contract:<\/span><\/p>\n
{\r\n\u00a0<\/span>\"name\"<\/span>:\u00a0<\/span><\/span>\"Dash Cat 001\"<\/span>,\r\n\u00a0<\/span>\"description\"<\/span>:\u00a0<\/span><\/span>\"The original Dash Cat. Meow.\"<\/span>,\r\n\u00a0<\/span>\"imageUrl\"<\/span>:\u00a0<\/span><\/span>\"https:\/\/ipfs.io\/ipfs\/Qme7ss3ARVgxv6rXqVPiikL\u2026\"<\/span>,\r\n\u00a0<\/span>\"imageHash\"<\/span>:\u00a0<\/span><\/span>[0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, \u2026]<\/span>,\r\n\u00a0<\/span>\"price\"<\/span>:\u00a0<\/span><\/span>50<\/span>,\r\n\u00a0<\/span>\"quantity\"<\/span>:\u00a0<\/span><\/span>1<\/span>\r\n}<\/span><\/code><\/pre>\n<\/div>\n
required<\/code>\u00a0field are present. There are no\u00a0<\/span>
additionalProperties<\/code>\u00a0(properties that aren\u2019t defined in the contract\u2019s\u00a0<\/span>
properties<\/code>\u00a0set), and each property value conforms to that individual property\u2019s validation rules (for example,\u00a0<\/span>
imageUrl<\/code>\u2018s length is under the set\u00a0<\/span>
maxLength<\/code>\u00a0of 2048, and is of URI\u00a0<\/span>format<\/span>). References to this document are automatically stored in the corresponding indexes defined in\u00a0<\/span>
indices<\/code>, while the document itself is serialized and stored in the contract\u2019s primary index.<\/span><\/p>\n
System Properties<\/span><\/h3>\n
name<\/code>\u00a0and\u00a0<\/span>
price<\/code>, there are some additional \u201csystem properties\u201d that data contracts may include in\u00a0<\/span>
indices<\/code>. These are $ownerId, $createdAt, and $updatedAt.\u00a0<\/span>$createdAt and $updatedAt<\/span>\u00a0may also be included in the list of\u00a0<\/span>
required<\/code>\u00a0properties, as they are optional when submitting a document at the system level, but $ownerId is always required, so it\u2019s not allowed in the user-defined\u00a0<\/span>
required<\/code>\u00a0list.<\/span><\/p>\n
Additional Architecture Details<\/span><\/h2>\n
Indices<\/span><\/h3>\n
price<\/code>,
quantity<\/code>, and\u00a0<\/span>
priceAndQuantity<\/code>. When a document is\u00a0<\/span>submitted to the data contract<\/span>, the full serialized document will go into the\u00a0<\/span>
primary index<\/code>, which is a subtree with key 0 in the \u201cnft\u201d tree, and references to the document will automatically be inserted into the three\u00a0<\/span>
secondary index<\/code>\u00a0subtrees. This is illustrated in the diagram below, where solid lines are actual parent-child relationships within a tree, and the dashed lines point to the node where the root hash of that tree is stored.<\/span><\/p>\n
Contract Documents Tree<\/span><\/h3>\n