├── .github └── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── config.yml │ ├── documentation_needed.md │ └── feature_request.md ├── .gitignore ├── .remarkrc ├── LICENSE ├── README.md ├── encoding.pdf ├── encoding.tex ├── protocol.pdf ├── protocol.tex ├── scheme.pdf └── scheme.tex /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve the XYO Android SDK 4 | title: "[BUG]" 5 | labels: bug 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Observed behavior** 11 | A clear and concise description of what exactly happened. 12 | 13 | **Expected behavior** 14 | A clear and concise description of what you expected to happen. 15 | 16 | **To Reproduce** 17 | Steps to reproduce the behavior: 18 | 1. Go to '...' 19 | 2. Click on '....' 20 | 3. Scroll down to '....' 21 | 4. See error 22 | 23 | **Screenshots** 24 | If applicable, add screenshots to help explain your problem. 25 | 26 | **Smartphone (please complete the following information):** 27 | - Device: [e.g. Samsung Galaxy, Google Pixel] 28 | - OS: [e.g. Android 10] 29 | - Browser [e.g. stock browser, chrome] 30 | 31 | **Additional context** 32 | Add any other context about the problem here. -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | contact_links: 3 | - name: XYO Developer Portal 4 | url: https://developers.xyo.network/ 5 | about: XYO Foundation Developer Portal 6 | - name: XYO Foundation Site 7 | url: https://xyo.network/ 8 | about: Check out the fundamentals of our Foundation here -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/documentation_needed.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Documentation needed 3 | about: Suggest documentation that is needed 4 | title: "[DOCUMENTATION]:" 5 | labels: documentation 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your documentation request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the documentation and format you would like** 14 | A clear and concise description of what documentation you would like to see and what type for format. 15 | Ex. Step-by-step, Paragraph explainer, screenshots, etc. 16 | 17 | **Additional context** 18 | Add any other context or screenshots about the document request here. -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for XYO SDK Android 4 | title: "[FEATURE]" 5 | labels: enhancement 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. This could include specific devices, android versions, etc. 21 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /build 2 | .DS_Store 3 | .DS_Store? 4 | .DS_Store 5 | *.log 6 | *.fls 7 | *.fdb_latexmk 8 | *.aux 9 | *.synctex.gz 10 | .vscode 11 | -------------------------------------------------------------------------------- /.remarkrc: -------------------------------------------------------------------------------- 1 | { 2 | 3 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU LESSER GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | 9 | This version of the GNU Lesser General Public License incorporates 10 | the terms and conditions of version 3 of the GNU General Public 11 | License, supplemented by the additional permissions listed below. 12 | 13 | 0. Additional Definitions. 14 | 15 | As used herein, "this License" refers to version 3 of the GNU Lesser 16 | General Public License, and the "GNU GPL" refers to version 3 of the GNU 17 | General Public License. 18 | 19 | "The Library" refers to a covered work governed by this License, 20 | other than an Application or a Combined Work as defined below. 21 | 22 | An "Application" is any work that makes use of an interface provided 23 | by the Library, but which is not otherwise based on the Library. 24 | Defining a subclass of a class defined by the Library is deemed a mode 25 | of using an interface provided by the Library. 26 | 27 | A "Combined Work" is a work produced by combining or linking an 28 | Application with the Library. The particular version of the Library 29 | with which the Combined Work was made is also called the "Linked 30 | Version". 31 | 32 | The "Minimal Corresponding Source" for a Combined Work means the 33 | Corresponding Source for the Combined Work, excluding any source code 34 | for portions of the Combined Work that, considered in isolation, are 35 | based on the Application, and not on the Linked Version. 36 | 37 | The "Corresponding Application Code" for a Combined Work means the 38 | object code and/or source code for the Application, including any data 39 | and utility programs needed for reproducing the Combined Work from the 40 | Application, but excluding the System Libraries of the Combined Work. 41 | 42 | 1. Exception to Section 3 of the GNU GPL. 43 | 44 | You may convey a covered work under sections 3 and 4 of this License 45 | without being bound by section 3 of the GNU GPL. 46 | 47 | 2. Conveying Modified Versions. 48 | 49 | If you modify a copy of the Library, and, in your modifications, a 50 | facility refers to a function or data to be supplied by an Application 51 | that uses the facility (other than as an argument passed when the 52 | facility is invoked), then you may convey a copy of the modified 53 | version: 54 | 55 | a) under this License, provided that you make a good faith effort to 56 | ensure that, in the event an Application does not supply the 57 | function or data, the facility still operates, and performs 58 | whatever part of its purpose remains meaningful, or 59 | 60 | b) under the GNU GPL, with none of the additional permissions of 61 | this License applicable to that copy. 62 | 63 | 3. Object Code Incorporating Material from Library Header Files. 64 | 65 | The object code form of an Application may incorporate material from 66 | a header file that is part of the Library. You may convey such object 67 | code under terms of your choice, provided that, if the incorporated 68 | material is not limited to numerical parameters, data structure 69 | layouts and accessors, or small macros, inline functions and templates 70 | (ten or fewer lines in length), you do both of the following: 71 | 72 | a) Give prominent notice with each copy of the object code that the 73 | Library is used in it and that the Library and its use are 74 | covered by this License. 75 | 76 | b) Accompany the object code with a copy of the GNU GPL and this license 77 | document. 78 | 79 | 4. Combined Works. 80 | 81 | You may convey a Combined Work under terms of your choice that, 82 | taken together, effectively do not restrict modification of the 83 | portions of the Library contained in the Combined Work and reverse 84 | engineering for debugging such modifications, if you also do each of 85 | the following: 86 | 87 | a) Give prominent notice with each copy of the Combined Work that 88 | the Library is used in it and that the Library and its use are 89 | covered by this License. 90 | 91 | b) Accompany the Combined Work with a copy of the GNU GPL and this license 92 | document. 93 | 94 | c) For a Combined Work that displays copyright notices during 95 | execution, include the copyright notice for the Library among 96 | these notices, as well as a reference directing the user to the 97 | copies of the GNU GPL and this license document. 98 | 99 | d) Do one of the following: 100 | 101 | 0) Convey the Minimal Corresponding Source under the terms of this 102 | License, and the Corresponding Application Code in a form 103 | suitable for, and under terms that permit, the user to 104 | recombine or relink the Application with a modified version of 105 | the Linked Version to produce a modified Combined Work, in the 106 | manner specified by section 6 of the GNU GPL for conveying 107 | Corresponding Source. 108 | 109 | 1) Use a suitable shared library mechanism for linking with the 110 | Library. A suitable mechanism is one that (a) uses at run time 111 | a copy of the Library already present on the user's computer 112 | system, and (b) will operate properly with a modified version 113 | of the Library that is interface-compatible with the Linked 114 | Version. 115 | 116 | e) Provide Installation Information, but only if you would otherwise 117 | be required to provide such information under section 6 of the 118 | GNU GPL, and only to the extent that such information is 119 | necessary to install and execute a modified version of the 120 | Combined Work produced by recombining or relinking the 121 | Application with a modified version of the Linked Version. (If 122 | you use option 4d0, the Installation Information must accompany 123 | the Minimal Corresponding Source and Corresponding Application 124 | Code. If you use option 4d1, you must provide the Installation 125 | Information in the manner specified by section 6 of the GNU GPL 126 | for conveying Corresponding Source.) 127 | 128 | 5. Combined Libraries. 129 | 130 | You may place library facilities that are a work based on the 131 | Library side by side in a single library together with other library 132 | facilities that are not Applications and are not covered by this 133 | License, and convey such a combined library under terms of your 134 | choice, if you do both of the following: 135 | 136 | a) Accompany the combined library with a copy of the same work based 137 | on the Library, uncombined with any other library facilities, 138 | conveyed under the terms of this License. 139 | 140 | b) Give prominent notice with the combined library that part of it 141 | is a work based on the Library, and explaining where to find the 142 | accompanying uncombined form of the same work. 143 | 144 | 6. Revised Versions of the GNU Lesser General Public License. 145 | 146 | The Free Software Foundation may publish revised and/or new versions 147 | of the GNU Lesser General Public License from time to time. Such new 148 | versions will be similar in spirit to the present version, but may 149 | differ in detail to address new problems or concerns. 150 | 151 | Each version is given a distinguishing version number. If the 152 | Library as you received it specifies that a certain numbered version 153 | of the GNU Lesser General Public License "or any later version" 154 | applies to it, you have the option of following the terms and 155 | conditions either of that published version or of any later version 156 | published by the Free Software Foundation. If the Library as you 157 | received it does not specify a version number of the GNU Lesser 158 | General Public License, you may choose any version of the GNU Lesser 159 | General Public License ever published by the Free Software Foundation. 160 | 161 | If the Library as you received it specifies that a proxy can decide 162 | whether future versions of the GNU Lesser General Public License shall 163 | apply, that proxy's public statement of acceptance of any version is 164 | permanent authorization for you to choose that version for the 165 | Library. 166 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | [logo]: https://cdn.xy.company/img/brand/XYO_full_colored.png 2 | 3 | [![logo]](https://xyo.network) 4 | 5 | # XYO Core Object Model 6 | 7 | (spec-coreobjectmodel-tex) 8 | 9 | [![Codacy Badge](https://api.codacy.com/project/badge/Grade/945b869c0d214489a4fc0c4ef0e8cab7)](https://www.codacy.com/gh/XYOracleNetwork/spec-coreobjectmodel-tex?utm_source=github.com&utm_medium=referral&utm_content=XYOracleNetwork/spec-coreobjectmodel-tex&utm_campaign=Badge_Grade) 10 | 11 | > The XYO Foundation provides this source code available in our efforts to advance the understanding of the XYO Procotol and its possible uses. We continue to maintain this software in the interest of developer education. Usage of this source code is not intended for production. 12 | 13 | ## Table of Contents 14 | 15 | - [Title](#xyo-core-object-model) 16 | - [Description](#description) 17 | - [Maintainers](#maintainers) 18 | - [License](#license) 19 | - [Credits](#credits) 20 | 21 | ## Description 22 | 23 | It is important to have an efficient way of encoding objects in the XYO Network given the limited space and computational power on IoT devices. To solve this, we utilize a typed based encoding system where all object interpretation knowledge is held outside of the object. 24 | 25 | ## Maintainers 26 | 27 | - Carter Harrison 28 | 29 | ## License 30 | 31 | See the [LICENSE](LICENSE) file for license details. 32 | 33 | ## Credits 34 | 35 | Made with 🔥and ❄️ by [XYO](https://www.xyo.network) 36 | -------------------------------------------------------------------------------- /encoding.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/XYOracleNetwork-v1/spec-coreobjectmodel-tex/6d3437475ef60e49cf46bfd9b92bf24fe0ec6f91/encoding.pdf -------------------------------------------------------------------------------- /encoding.tex: -------------------------------------------------------------------------------- 1 | \documentclass[11pt]{article} 2 | 3 | \usepackage{float} 4 | \title{XYO Network Encoding} 5 | 6 | \date{April, 2019} 7 | \begin{document} 8 | \maketitle 9 | 10 | 11 | \section{Overview} 12 | When communicating with applications across the XYO Network it is important to have a standard for encoding binary data so that all applications can be sure that they are talking about the same entity/object. The XYO Network only encodes binary data to a string when talking over HTTP/HTTPS or when using a protocol that does not allow arbitrary binary data -- Otherwise it is left untouched. 13 | 14 | 15 | \section{Public Keys and Hashes} 16 | When referencing to a public key or hash as a string, it should be shown in base58 with the encoding header. A public key or a hash should never be shown without its encoding header defined in the Object Model Scheme document. 17 | 18 | \subsection{Base 58} 19 | The XYO Network uses the alphabet below for its base 58 encoding. It is the same base58 encoding used in Bitcoin and other popular cryptocurrencies, but not the base58 that Flicker uses. 20 | 21 | \ 22 | 23 | \noindent 24 | 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz 25 | 26 | 27 | \end{document} 28 | -------------------------------------------------------------------------------- /protocol.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/XYOracleNetwork-v1/spec-coreobjectmodel-tex/6d3437475ef60e49cf46bfd9b92bf24fe0ec6f91/protocol.pdf -------------------------------------------------------------------------------- /protocol.tex: -------------------------------------------------------------------------------- 1 | \documentclass[11pt]{article} 2 | \author{XYO} 3 | \usepackage{float} 4 | \usepackage{bytefield} 5 | 6 | 7 | \title{XYO Network Interaction Protocol v2.0} 8 | 9 | \date{December, 2018} 10 | \begin{document} 11 | \maketitle 12 | 13 | \section{Overview} 14 | The XYO Interaction Protocol determines how devices can interact with each other though XYO. 15 | The protocol is broken into three layers, Transport, Exchange, and Data. 16 | 17 | \section{Transport Layer} 18 | The transport layer determines how devices speak to each other via Bluetooth, TCP/IP, 19 | or other transport. All these will have a similar structures, but will have transport 20 | specific differences. 21 | 22 | % Bluetooth Start 23 | \subsection{Bluetooth (BLE)} 24 | The Bluetooth transfer layer essentially abstracts GATT (Generic Attributes) characteristics to an input and output stream. Both client and server can send send any data to each other. 25 | 26 | \subsubsection{Primary Service} 27 | This service contains 2 characteristics, a read characteristic and a write characteristic. The XYO Primary Service UUID indicates that a device is capable of XYO functionality. The UUIDs for the service are listed below.\\ 28 | 29 | \noindent 30 | \textbf{XYO Primary Service UUID:} d684352e-df36-484e-bc98-2d5398c5593e \\ 31 | \textbf{-- Pipe Characteristic UUID:} 727a3639-0eb4-4525-b1bc-7fa456490b2d \\ 32 | 33 | \subsubsection{Sending Data} 34 | Transferring data between two XYO BLE devices consists of reading and writing to characteristics. All data is chunked into individual packets that can be reconstructed by the client or the server. When the connection is established, the client must subscribe to the read characteristic, so it can be notified of the server's data. 35 | 36 | \noindent 37 | \textbf{Client Sending to Server}\\ 38 | \indent 39 | After the two parties have established a connection. A client client can send information to the server by writing the respected bytes to the write characteristic. 40 | 41 | \noindent 42 | \textbf{Server Sending to Client}\\ 43 | \indent 44 | After the two parties have established a connection. A server can send to the client by sending a BLE notification's of the data to send. 45 | 46 | \subsubsection{Advertising and Device Discovery} 47 | XYO Enabled BLE devices should be advertising the XYO Primary Service UUID to identify them as available for a connection session. If the device is not available for a connection, it should not be advertising the primary service. This means unless a device can support mutable XYO connections at once, it should stop advertising after a connection has been established. \\ 48 | 49 | \subsubsection{Chunking Data} 50 | When sending any data between two devices, it is necessary to chunk all of the data wishing to be sent into smaller segments so large amounts of data can be transacted. \\ 51 | 52 | \noindent 53 | To chunk data, a device must prepend a 4 byte unsigned integer (Big Endian) with the value of the size of the entire data wishing to be sent, in bytes. This size includes itself. After the size has been prepended, the device may chunk it up into as many portions as wanted, as long as the largest packet is smaller than or equal to the MTU of the connection. 54 | \\ 55 | 56 | 57 | \noindent 58 | \begin{bytefield}[bitwidth=1.1em]{32} 59 | 60 | \begin{rightwordgroup}{0th Packet} 61 | \bitheader{0-31} \\ 62 | \bitbox{4}{Size} 63 | \bitbox[tr]{28}{Value} \\ 64 | \wordbox[blr]{2}{$\cdots$} \\ 65 | \end{rightwordgroup} \\ 66 | 67 | \end{bytefield} 68 | 69 | \noindent 70 | \begin{bytefield}[bitwidth=1.1em]{32} 71 | 72 | \begin{rightwordgroup}{n Packet} 73 | \bitheader{0-31} \\ 74 | \bitbox[lrt]{32}{Value} \\ 75 | \wordbox[blr]{2}{$\cdots$} \\ 76 | \end{rightwordgroup} \\ 77 | 78 | \end{bytefield} 79 | 80 | \noindent 81 | We can infer that the packet is done being sent once the number of value bytes is equal to the $size - 4$. 82 | 83 | 84 | % TCP/IP Start 85 | \subsection{TCP/IP} 86 | The TCP/IP network is a simple way to transact information between devices. 87 | 88 | \subsubsection{Connection Session} 89 | During a TCP connection between two devices, a socket is only established once. After the connection session is over, the socket is closed by either party. 90 | 91 | \subsubsection{Transacting Data} 92 | To send data between nodes, a 4 byte unsigned integer (Big Endian) must be sent through the socket (size includes itself), then the value wishing to be sent. We can infer that the packet is done being sent once the number of value bytes is equal to the $size - 4$. \\ 93 | 94 | \noindent 95 | \begin{bytefield}[bitwidth=1.1em]{32} 96 | 97 | \begin{rightwordgroup}{TCP Packet} 98 | \bitheader{0-31} \\ 99 | \bitbox{4}{Size} 100 | \bitbox[tr]{28}{Value} \\ 101 | \wordbox[blr]{2}{$\cdots$} \\ 102 | \end{rightwordgroup} \\ 103 | 104 | \end{bytefield} 105 | 106 | % Start Exchange Layer 107 | \section{Exchange Layer} 108 | The exchange layer determines the packet sequencing expectations for an interaction 109 | between devices. This is consistent regardless of transport. 110 | 111 | \subsection{Bound Witness Sequence} 112 | For clarity, we will refer to the parties as 0, 1, etc... Bound witness follow the idea of a fetter and a witness. A fetter is an object that contains all signed metadata with the public keys of the device. A witness is an object that contains all unsigned metadata along with the signature of the bound witness. Parties in a bound witness follow a first in, lat out basis. The signature signs all of the fetters contacted together. \\ 113 | 114 | \noindent 115 | \textbf{Single Party Bound Witness} \\ 116 | \begin{center} 117 | \begin{tabular}{ |l|l|l| } 118 | \hline 119 | \textbf{Step} & \textbf{Party} & \textbf{Description} \\ 120 | \hline 121 | 122 | 1 & 0 & Fetter \\ 123 | 1 & 0 & Witness \\ 124 | 125 | \hline 126 | \end{tabular} 127 | \end{center} 128 | 129 | 130 | \noindent 131 | \textbf{Two Party Bound Witness} \\ 132 | \begin{center} 133 | \begin{tabular}{ |l|l|l| } 134 | \hline 135 | \textbf{Step} & \textbf{Party} & \textbf{Description} \\ 136 | \hline 137 | 138 | 1 & 0 & Fetter \\ 139 | 2 & 1 & Fetter \\ 140 | 3 & 1 & Witness \\ 141 | 4 & 0 & Witness \\ 142 | 143 | \hline 144 | \end{tabular} 145 | \end{center} 146 | 147 | \noindent 148 | \textbf{Three Party Bound Witness} \\ 149 | \begin{center} 150 | \begin{tabular}{ |l|l|l| } 151 | \hline 152 | \textbf{Step} & \textbf{Party} & \textbf{Description} \\ 153 | \hline 154 | 155 | 1 & 0 & Fetter \\ 156 | 2 & 1 & Fetter \\ 157 | 3 & 2 & Fetter \\ 158 | 4 & 2 & Witness \\ 159 | 5 & 1 & Witness \\ 160 | 6 & 0 & Witness \\ 161 | 162 | \hline 163 | \end{tabular} 164 | \end{center} 165 | 166 | 167 | 168 | 169 | % Start Data Layer 170 | \section{Data Layer} 171 | The data layer specifies how data blocks are interpreted by devices. All numbers are passed in Big Endian. There is no padding between items being passed. Everything that is encoded is a superset of an \textit{Object}. An object is defined by having an object header that contains information about how to unpack that object. This information includes how to read the size of the object, if the object is Iterable (typed and untyped), and the ID of the object. 172 | 173 | \section{Object Structure} 174 | \begin{center} 175 | \begin{tabular}{ |l|l| } 176 | \hline 177 | \textbf{Name} & \textbf{Description} \\ 178 | \hline 179 | Object Header & Info about the object and size \\ 180 | Size & Size of the object \\ 181 | Payload & The raw contents of the object. \\ 182 | \hline 183 | \end{tabular} 184 | \end{center} 185 | 186 | \section{Object Header} 187 | The object header is prepended to every object to obtain information about the object. This is broken into two primary sections, the encoding catalogue and ID. \\ 188 | 189 | \noindent 190 | \begin{bytefield}[bitwidth=17.6em]{2} 191 | 192 | \begin{rightwordgroup}{Object \\ Header} 193 | 194 | \bitheader{0-1} \\ 195 | \bitbox{1}{ID} 196 | \bitbox{1}{Encoding Catalogue} 197 | 198 | \end{rightwordgroup} 199 | 200 | \end{bytefield} 201 | 202 | \subsection{Encoding catalogue (1 Byte)} 203 | The encoding catalogue gives information about the size of the size and if the object is Iterable (typed and untyped).\\ 204 | 205 | \noindent 206 | \begin{bytefield}[bitwidth=4.4em]{8} 207 | 208 | \begin{rightwordgroup}{Encoding \\ Catalogue \\ 8 bits} 209 | 210 | \bitheader{0-7} \\ 211 | \bitbox{2}{Size identifier size} 212 | \bitbox{2}{Iterable} 213 | \bitbox{4}{Reserved} 214 | 215 | 216 | \end{rightwordgroup} 217 | 218 | \end{bytefield} 219 | 220 | 221 | \subsubsection{Size identifier size (2 bits)} 222 | These two bits are used to determine how many bytes to read to obtain the size of the object after the header of the object. The states of the Size identifier size flags are listed below. Note: \textit{All sizes include themes, are big endian, and are unsigned.} 223 | 224 | \begin{center} 225 | \begin{tabular}{ |l|l| } 226 | \hline 227 | \textbf{Flag} & \textbf{Name} \\ 228 | \hline 229 | 00b & 1 Byte Size. \\ 230 | 01b & 2 Byte Size. \\ 231 | 10b & 4 Byte Size. \\ 232 | 11b & 8 Byte Size. \\ 233 | \hline 234 | \end{tabular} 235 | \end{center} 236 | 237 | \subsubsection{Iterable (2 bits)} 238 | This flag is the 3-4th most significant bits. The flags follow the table below: 239 | 240 | \begin{center} 241 | \begin{tabular}{ |l|l| } 242 | \hline 243 | \textbf{Flag} & \textbf{Name} \\ 244 | \hline 245 | 00b & Not Iterable. \\ 246 | 01b & Associative Array. \\ 247 | 10b & Untyped Iterable. \\ 248 | 11b & Typed Iterable. \\ 249 | \hline 250 | \end{tabular} 251 | \end{center} 252 | 253 | 254 | 255 | 256 | \subsection{ID (1 Byte)} 257 | Used as a ID for the value/payload. This value is appended to the Encoding catalogue. 258 | 259 | \section{Iterable Objects} 260 | Iterable Objects are objects that contain a set of child objects. If an object is iterable, the proper flag will be set in the object header. There are two types of iterable objects: typed iterable objects, and untyped Iterable Objects. If an iterable is typed, the proper flag will be set in the object header. 261 | 262 | \subsection{Untyped Iterable Objects} 263 | Untyped Iterable Objects are objects that contain a set of objects that have more than one type of header. Untyped iterable objects are created by concatenating many objects together do not that share one header. 264 | 265 | \subsubsection{Example Structure} 266 | 267 | \begin{bytefield}[bitwidth=4.4em]{8} 268 | 269 | \bitheader{0-7} \\ 270 | \bitbox{1}{\tiny Encoding Catalogue} 271 | \bitbox{1}{ID} 272 | \bitbox{4}{Size of the iterable object (n bytes)} 273 | \bitbox{1}{\tiny [0] Encoding Catalogue} 274 | \bitbox{1}{\tiny [0] ID} \\ 275 | \bitbox{4}{[0] Size of first element} 276 | 277 | \bitbox[tr]{4}{[0] Value of first element} \\ 278 | \wordbox[blr]{2}{$\cdots$} \\ 279 | 280 | \bitbox{1}{\tiny [1] Encoding Catalogue} 281 | \bitbox{1}{\tiny [1] ID} 282 | \bitbox{4}{[1] Size of second element} 283 | \bitbox[tr]{2}{\tiny [1] Value of second element} \\ 284 | \wordbox[blr]{2}{$\cdots$} \\ 285 | 286 | \bitbox{1}{\tiny [n] Encoding Catalogue} 287 | \bitbox{1}{\tiny [n] ID} 288 | \bitbox{4}{[1] Size of second element} 289 | \bitbox[tr]{2}{\tiny [1] Value of nth element} \\ 290 | \wordbox[blr]{2}{$\cdots$} \\ 291 | 292 | \end{bytefield} 293 | 294 | \subsection{Typed Iterable Objects} 295 | Typed Iterable Objects are objects that contain a set of objects that all share the same header. Typed iterable objects are created by concatenating many objects without their header together and prepending it with the shared header. 296 | 297 | \subsubsection{Example Structure} 298 | 299 | \noindent 300 | \begin{bytefield}[bitwidth=4.4em]{8} 301 | 302 | \bitheader{0-7} \\ 303 | \bitbox{1}{\tiny Encoding Catalogue} 304 | \bitbox{1}{ID} 305 | \bitbox{4}{Size of the iterable object (n bytes)} 306 | \bitbox{1}{\tiny Encoding Catalogue for all} 307 | \bitbox{1}{\tiny ID for all} \\ 308 | 309 | \bitbox{4}{[0] Size of first element} 310 | \bitbox[tr]{4}{[0] Value of first element} \\ 311 | \wordbox[blr]{2}{$\cdots$} \\ 312 | 313 | \bitbox{4}{[1] Size of second element} 314 | \bitbox[tr]{4}{[1] Value of second element} \\ 315 | \wordbox[blr]{2}{$\cdots$} \\ 316 | 317 | 318 | \bitbox{4}{[n] Size of second element} 319 | \bitbox[tr]{4}{[n] Value of nth element} \\ 320 | \wordbox[blr]{2}{$\cdots$} \\ 321 | 322 | \end{bytefield} 323 | 324 | \subsection{Associative Array} 325 | Associative Arrays are just like untyped arrays with the condition that every elements id in the array must be unique, similar to an "object" in JSON. 326 | 327 | \subsubsection{Example Structure} 328 | 329 | \begin{bytefield}[bitwidth=4.4em]{8} 330 | 331 | \bitheader{0-7} \\ 332 | \bitbox{1}{\tiny Encoding Catalogue} 333 | \bitbox{1}{ID} 334 | \bitbox{4}{Size of the iterable object (n bytes)} 335 | \bitbox{1}{\tiny [0] Encoding Catalogue} 336 | \bitbox{1}{\tiny [0] ID} \\ 337 | \bitbox{4}{[0] Size of first element} 338 | 339 | \bitbox[tr]{4}{[0] Value of first element} \\ 340 | \wordbox[blr]{2}{$\cdots$} \\ 341 | 342 | \bitbox{1}{\tiny [1] Encoding Catalogue} 343 | \bitbox{1}{\tiny [1] ID} 344 | \bitbox{4}{[1] Size of second element} 345 | \bitbox[tr]{2}{\tiny [1] Value of second element} \\ 346 | \wordbox[blr]{2}{$\cdots$} \\ 347 | 348 | \bitbox{1}{\tiny [n] Encoding Catalogue} 349 | \bitbox{1}{\tiny [n] ID} 350 | \bitbox{4}{[1] Size of second element} 351 | \bitbox[tr]{2}{\tiny [1] Value of nth element} \\ 352 | \wordbox[blr]{2}{$\cdots$} \\ 353 | 354 | 355 | \end{bytefield} 356 | 357 | 358 | 359 | \subsection{First Class Objects} 360 | \noindent 361 | \textbf{Array} \\ 362 | \indent \textbf{Id:} 1 \\ 363 | \indent \textbf{Iterable:} True \\ 364 | \indent \textbf{Descreption:} A general array type, this iterable type can be typed, untyped, or an Associative Array. \\ 365 | 366 | \noindent 367 | \textbf{Bound Witness} \\ 368 | \indent \textbf{Id:} 2 \\ 369 | \indent \textbf{Iterable:} True \\ 370 | \indent \textbf{Descreption:} An XYO Bound Witness. \\ 371 | 372 | \noindent 373 | \textbf{Origin Index} \\ 374 | \indent \textbf{Id:} 3 \\ 375 | \indent \textbf{Iterable:} False \\ 376 | \indent \textbf{Descreption:} The index (height) of the current bound witness in an origin chain. This value is a 4 byte unsigned integer in big endian.\\ 377 | 378 | \noindent 379 | \textbf{Next Public Key} \\ 380 | \indent \textbf{Id:} 4 \\ 381 | \indent \textbf{Iterable:} True \\ 382 | \indent \textbf{Descreption:} The next key to use in an origin chain. This object wraps an any key object and is an array of 1. \\ 383 | 384 | \noindent 385 | \textbf{Bridge Block Set} \\ 386 | \indent \textbf{Id:} 5 \\ 387 | \indent \textbf{Iterable:} True \\ 388 | \indent \textbf{Descreption:} An array of blocks. Used when bridging. \\ 389 | 390 | \noindent 391 | \textbf{Bridge Hash Set} \\ 392 | \indent \textbf{Id:} 6 \\ 393 | \indent \textbf{Iterable:} True \\ 394 | \indent \textbf{Descreption:} An array of hashes of blocks. Used when bridging. \\ 395 | 396 | \noindent 397 | \textbf{Payment Key} \\ 398 | \indent \textbf{Id:} 7 \\ 399 | \indent \textbf{Iterable:} No \\ 400 | \indent \textbf{Descreption:} The payment key of the device, any length. \\ 401 | 402 | \noindent 403 | \textbf{Previous Hash} \\ 404 | \indent \textbf{Id:} 8 \\ 405 | \indent \textbf{Iterable:} True \\ 406 | \indent \textbf{Descreption:} The previous Bound Witness hash. This object wraps any hash object and is an array of 1.\\ 407 | 408 | \noindent 409 | \textbf{ECDSA Signature with Sha256 on Secp256k1} \\ 410 | \indent \textbf{Id:} 9 \\ 411 | \indent \textbf{Iterable:} False \\ 412 | \indent \textbf{Descreption:} ECDSA Signature with Sha256 on the curve: Secp256k1. \\ 413 | \indent \textbf{Structure:} \\ 414 | 415 | \begin{bytefield}[bitwidth=4.4em]{8} 416 | 417 | \bitheader{0-7} \\ 418 | \bitbox{1}{\tiny Size of R} 419 | \bitbox[tr]{7}{R value of Signature} \\ 420 | \wordbox[blr]{2}{$\cdots$} \\ 421 | \bitbox{1}{\tiny Size of S} 422 | \bitbox[tr]{7}{S value of Signature} \\ 423 | \wordbox[blr]{2}{$\cdots$} \\ 424 | 425 | \end{bytefield} 426 | 427 | \noindent 428 | \textbf{RSA Signature} \\ 429 | \indent \textbf{Id:} 10 \\ 430 | \indent \textbf{Iterable:} False \\ 431 | \indent \textbf{Descreption:} The modulus of the RSA signature. \\ 432 | 433 | \noindent 434 | \textbf{Stub Signature} \\ 435 | \indent \textbf{Id:} 11 \\ 436 | \indent \textbf{Iterable:} False \\ 437 | \indent \textbf{Descreption:} A signature used for development. \\ 438 | 439 | \noindent 440 | \textbf{EC Secp256k1 Uncompressed Public Key} \\ 441 | \indent \textbf{Id:} 12 \\ 442 | \indent \textbf{Iterable:} False \\ 443 | \indent \textbf{Descreption:} EC Uncompressed Public key on the curve Secp256k1. \\ 444 | 445 | \begin{bytefield}[bitwidth=1.1em]{32} 446 | 447 | \bitheader{0-31} \\ 448 | \bitbox{32}{X Value} \\ 449 | \bitbox{32}{Y Value} \\ 450 | 451 | \end{bytefield} 452 | 453 | \noindent 454 | \textbf{RSA Public Key} \\ 455 | \indent \textbf{Id:} 13 \\ 456 | \indent \textbf{Iterable:} False \\ 457 | \indent \textbf{Descreption:} RSA Public Key. The modulus of the RSA signature. \\ 458 | 459 | \noindent 460 | \textbf{Stub Public Key} \\ 461 | \indent \textbf{Id:} 14 \\ 462 | \indent \textbf{Iterable:} False \\ 463 | \indent \textbf{Descreption:} A stub public key used for development. \\ 464 | 465 | \noindent 466 | \textbf{Stub Hash} \\ 467 | \indent \textbf{Id:} 15 \\ 468 | \indent \textbf{Iterable:} False \\ 469 | \indent \textbf{Descreption:} A stub hash used for development. \\ 470 | 471 | \noindent 472 | \textbf{SHA 256} \\ 473 | \indent \textbf{Id:} 16 \\ 474 | \indent \textbf{Iterable:} False \\ 475 | \indent \textbf{Descreption:} A SHA 256 Hash. \\ 476 | 477 | \noindent 478 | \textbf{SHA 3} \\ 479 | \indent \textbf{Id:} 17 \\ 480 | \indent \textbf{Iterable:} False \\ 481 | \indent \textbf{Descreption:} A SHA 3 Hash. \\ 482 | 483 | \noindent 484 | \textbf{GPS} \\ 485 | \indent \textbf{Id:} 18 \\ 486 | \indent \textbf{Iterable:} Yes \\ 487 | \indent \textbf{Descreption:} GPS Location, associative array of [Latitude, Longitude]. \\ 488 | 489 | \noindent 490 | \textbf{RSSI} \\ 491 | \indent \textbf{Id:} 19 \\ 492 | \indent \textbf{Iterable:} No \\ 493 | \indent \textbf{Descreption:} RSSI of the Bluetooth Connection. A signed byte. \\ 494 | 495 | \noindent 496 | \textbf{Unix Time} \\ 497 | \indent \textbf{Id:} 20 \\ 498 | \indent \textbf{Iterable:} No \\ 499 | \indent \textbf{Descreption:} The Unix time of the bound witness in milliseconds. Number format: Unsigned Long. \\ 500 | 501 | \noindent 502 | \textbf{Fetter} \\ 503 | \indent \textbf{Id:} 21 \\ 504 | \indent \textbf{Iterable:} Yes \\ 505 | \indent \textbf{Descreption:} A bound witness fetter. \\ 506 | 507 | \noindent 508 | \textbf{Fetter Set} \\ 509 | \indent \textbf{Id:} 22 \\ 510 | \indent \textbf{Iterable:} Yes \\ 511 | \indent \textbf{Descreption:} A set of fetters. \\ 512 | 513 | \noindent 514 | \textbf{Witness} \\ 515 | \indent \textbf{Id:} 23 \\ 516 | \indent \textbf{Iterable:} Yes \\ 517 | \indent \textbf{Descreption:} A bound witness witness. \\ 518 | 519 | \noindent 520 | \textbf{Witness Set} \\ 521 | \indent \textbf{Id:} 24 \\ 522 | \indent \textbf{Iterable:} Yes \\ 523 | \indent \textbf{Descreption:} A set of witnesses. \\ 524 | 525 | \noindent 526 | \textbf{Key Set} \\ 527 | \indent \textbf{Id:} 25 \\ 528 | \indent \textbf{Iterable:} Yes \\ 529 | \indent \textbf{Descreption:} A set of public keys. \\ 530 | 531 | \noindent 532 | \textbf{Signature Set} \\ 533 | \indent \textbf{Id:} 26 \\ 534 | \indent \textbf{Iterable:} Yes \\ 535 | \indent \textbf{Descreption:} A set of signatures. \\ 536 | 537 | \noindent 538 | \textbf{Bound Witness Fragment} \\ 539 | \indent \textbf{Id:} 27 \\ 540 | \indent \textbf{Iterable:} Yes \\ 541 | \indent \textbf{Descreption:} A witnesses and fetters. \\ 542 | 543 | \noindent 544 | \textbf{Latitude} \\ 545 | \indent \textbf{Id:} 28 \\ 546 | \indent \textbf{Iterable:} No \\ 547 | \indent \textbf{Descreption:} Latitude. Number format: Signed Double.\\ 548 | 549 | \noindent 550 | \textbf{Longitude} \\ 551 | \indent \textbf{Id:} 29 \\ 552 | \indent \textbf{Iterable:} No \\ 553 | \indent \textbf{Descreption:} Longitude. Number format: Signed Double. \\ 554 | 555 | \noindent 556 | \textbf{RSSI at 1m} \\ 557 | \indent \textbf{Id:} 30 \\ 558 | \indent \textbf{Iterable:} No \\ 559 | \indent \textbf{Descreption:} RSSI at 1m, signed byte. \\ 560 | 561 | \noindent 562 | \textbf{JSON Blob} \\ 563 | \indent \textbf{Id:} 254 \\ 564 | \indent \textbf{Iterable:} No \\ 565 | \indent \textbf{Descreption:} An arbitrary json blob \\ 566 | 567 | 568 | \end{document} -------------------------------------------------------------------------------- /scheme.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/XYOracleNetwork-v1/spec-coreobjectmodel-tex/6d3437475ef60e49cf46bfd9b92bf24fe0ec6f91/scheme.pdf -------------------------------------------------------------------------------- /scheme.tex: -------------------------------------------------------------------------------- 1 | \documentclass[11pt]{article} 2 | 3 | \usepackage{float} 4 | \title{XYO Network Object Model} 5 | 6 | \date{November, 2018} 7 | \begin{document} 8 | \maketitle 9 | 10 | 11 | \section{Overview} 12 | Everything that is encoded is a superset of an \textit{Object}. An object is defined by having an object header that contains information about how to unpack that object. This information includes how to read the size of the object, if the object is Iterable (typed and untyped), and the ID of the object. 13 | 14 | \section{Object Structure} 15 | \begin{center} 16 | \begin{tabular}{ |l|l| } 17 | \hline 18 | \textbf{Name} & \textbf{Description}\\ 19 | \hline 20 | Object Header & Info about the object and size \\ 21 | Size & Size of the object \\ 22 | Payload & The raw contents of the object. \\ 23 | \hline 24 | \end{tabular} 25 | \end{center} 26 | 27 | \section{Object Header} 28 | The object header is prepended to every object to obtain information about the object. This is broken into two primary sections, the encoding catalogue and ID. 29 | 30 | \begin{center} 31 | \begin{tabular}{ |l|l| } 32 | \hline 33 | \textbf{Name} & \textbf{Size}\\ 34 | \hline 35 | Encoding catalogue & 1 Byte. \\ 36 | ID & 1 Byte. \\ 37 | \hline 38 | \end{tabular} 39 | \end{center} 40 | 41 | 42 | \subsection{Encoding catalogue (1 Byte)} 43 | The encoding catalogue gives information about the size of the size and if the object is Iterable (typed and untyped). 44 | 45 | \subsubsection{Structure} 46 | \begin{center} 47 | \begin{tabular}{ |l|l| } 48 | \hline 49 | \textbf{Size} & \textbf{Name}\\ 50 | \hline 51 | 2 bits & Size identifier size \\ 52 | 1 bit & Is Iterable \\ 53 | 1 bit & Is a typed iterable \\ 54 | 4 bits & Reserved for future use \\ 55 | \hline 56 | \end{tabular} 57 | \end{center} 58 | 59 | \subsubsection{Size identifier size (2 bits)} 60 | These two bits are used to determine how many bytes to read to obtain the size of the object after the header of the object. The states of the Size identifier size flags are listed below. Note: \textit{All sizes include themes, are big endian, and are unsigned.}. 61 | 62 | \begin{center} 63 | \begin{tabular}{ |l|l| } 64 | \hline 65 | \textbf{Flag} & \textbf{Name}\\ 66 | \hline 67 | 00b & 1 Byte Size. \\ 68 | 01b & 2 Byte Size. \\ 69 | 10b & 4 Byte Size. \\ 70 | 11b & 8 Byte Size. \\ 71 | \hline 72 | \end{tabular} 73 | \end{center} 74 | 75 | \subsubsection{Is Iterable} 76 | This flag is the 3rd most significant bit. If the bit is set, the following object after the object header will be Iterable. 77 | 78 | \subsection{Is a typed iterable} 79 | This flag is the 4rd most significant bit. If the bit is set, the following Iterable object will only contain one header for all items in the set. For more information refer to the Iterable objects section. 80 | 81 | 82 | \subsection{ID (1 Byte)} 83 | Used as a ID for the value/payload. This value is appended to the Encoding catalogue. 84 | 85 | \section{Iterable Objects} 86 | Iterable Objects are objects that contain a set of child objetcs. If an object is iterable, the proper flag will be set in the object header. There are two types of iterable objects: typed iterable objects, and untyped Iterable Objects. If an iterable is typed, the proper flag will be set in the object header. 87 | 88 | \subsection{Untyped Iterable Objects} 89 | Untyped Iterable Objects are objects that contain a set of objects that have more than one type of header. Untyped iterable objects are created by concatenating many objects together that share one header. 90 | 91 | \subsubsection{Example Structure} 92 | 93 | \begin{center} 94 | \begin{tabular}{ |l|l| } 95 | \hline 96 | \textbf{Name} & \textbf{Description}\\ 97 | \hline 98 | Encoding catalogue & Encoding catalogue for entire set. \\ 99 | ID & ID for entire set. \\ 100 | Size & Size of entire set. \\ 101 | Object 0 (With header) & The first element in the set. \\ 102 | Object 1 (With header) & The second element on the set. \\ 103 | Object n (With header) & The n'th object in the set. \\ 104 | \hline 105 | \end{tabular} 106 | \end{center} 107 | 108 | \subsection{Typed Iterable Objects} 109 | Typed Iterable Objects are objects that contain a set of objects that all share the same header. Typed iterable objects are created by concatenating many objects without their header together and prepending it with the shared header. 110 | 111 | \subsubsection{Example Structure} 112 | 113 | \begin{center} 114 | \begin{tabular}{ |l|l| } 115 | \hline 116 | \textbf{Name} & \textbf{Description}\\ 117 | \hline 118 | Encoding catalogue & Encoding catalogue for entire set. \\ 119 | ID & ID for entire set. \\ 120 | Size & Size of entire set. \\ 121 | Shared Header & The header the objects 0-n share. \\ 122 | Object 0 (No header) & The first element in the set. \\ 123 | Object 1 (No header) & The second element on the set. \\ 124 | Object n (No header) & The n'th object in the set. \\ 125 | \hline 126 | \end{tabular} 127 | \end{center} 128 | 129 | 130 | 131 | \end{document} 132 | --------------------------------------------------------------------------------