{"action":"created","issue":{"url":"https://api.github.com/repos/mediachain/mediachain/issues/17","repository_url":"https://api.github.com/repos/mediachain/mediachain","labels_url":"https://api.github.com/repos/mediachain/mediachain/issues/17/labels{/name}","comments_url":"https://api.github.com/repos/mediachain/mediachain/issues/17/comments","events_url":"https://api.github.com/repos/mediachain/mediachain/issues/17/events","html_url":"https://github.com/mediachain/mediachain/issues/17","id":150197401,"number":17,"title":"Transactor interface description","user":{"login":"yusefnapora","id":678715,"avatar_url":"https://avatars.githubusercontent.com/u/678715?v=3","gravatar_id":"","url":"https://api.github.com/users/yusefnapora","html_url":"https://github.com/yusefnapora","followers_url":"https://api.github.com/users/yusefnapora/followers","following_url":"https://api.github.com/users/yusefnapora/following{/other_user}","gists_url":"https://api.github.com/users/yusefnapora/gists{/gist_id}","starred_url":"https://api.github.com/users/yusefnapora/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yusefnapora/subscriptions","organizations_url":"https://api.github.com/users/yusefnapora/orgs","repos_url":"https://api.github.com/users/yusefnapora/repos","events_url":"https://api.github.com/users/yusefnapora/events{/privacy}","received_events_url":"https://api.github.com/users/yusefnapora/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":15,"created_at":"2016-04-21T21:38:19Z","updated_at":"2016-04-25T09:57:52Z","closed_at":null,"body":"This is subject to change as we hash things out :)\r\n\r\n\r\n\r\n# Transactor interfaces\r\n\r\nThe Transactor peer nodes are responsible for writing data to the system\r\nand ensuring consistency.  \r\n\r\nTransactors have two main client-facing interfaces:\r\n\r\n- writing data to persistent storage (e.g. IPFS) on behalf of clients\r\n- informing clients of changes to the Journal when updates are made\r\n\r\nAs well as \"internal\" responsibilities:\r\n\r\n- maintaining the chain of updates for metadata entries\r\n- communication with other transactor nodes to achieve consensus\r\n\r\n\r\n## Writing data\r\n\r\nThe transactor accepts data in the format described by [RFC-1][rfc-1], with the\r\nimportant exception that the `chain` field for the various `ChainCell`s is not\r\nfilled in by the client.\r\n\r\nSince non-Transactor peers do not participate in the consensus process, they\r\ncannot know with certainty whether their pointer to the head of a given chain\r\nwill still be correct when the transaction is committed and written to the\r\nJournal.  \r\n\r\n[RFC-2][rfc-2] describes a strategy for resolving conflicting updates with\r\n\"merge\" cells that resolve forks into a single chain while preserving the \r\ndata from both forks.  \r\n\r\nIn the short term, our plan is for client nodes to defer the \"chaining\" of\r\nupdates to the Transactor peers.  A client will therefore submit updates\r\nwith all information except the `chain` field, which will be determined by\r\nthe Transactor when the update is committed.\r\n\r\nThis has implications for signing, in that the `chain` field will need to be\r\nomitted when verifying signatures for a cell, as it is unavailable to the client\r\nwhen signing.\r\n\r\n### Data types and services\r\nThere are two fundamental write operations that clients can submit:\r\n- creation of a new Canonical metadata entry (`Entity` or `Artefact`)\r\n- updates to an existing entry\r\n\r\nIn both cases, RPC messages are sent to a service endpoint requesting that the\r\ndata be added to the system.  The format of the messages should track closely\r\nto that described in [RFC-1][rfc-1]. \r\n\r\nThe server will respond synchronously with either an \"acknowledgement\" response,\r\nor a validation error if the message cannot be parsed or otherwise fails an \r\ninitial validation pass.  \r\n\r\nImportantly, the initial validation does not ensure that the data is guaranteed \r\nto be accepted, only that it is consistent with the expected format, and that it\r\nhas no \"dangling references\", etc.  For example, attempting to issue an update\r\nto a non-existent `Artefact` would immediately fail.  Other causes of validation\r\nfailure might include failing to conform to an expected schema (an invalid \r\n`timestamp` format, for example), or trying to submit an `EntityUpdateCell` that\r\nrefers to an `Artefact` instead of an `Entity`.\r\n\r\nIn other words, initial validation only covers what can be known at the \r\nimmediate time of submission.  However, since the block consensus protocol for\r\nconfirming a transaction may take an indeterminate amount of time, it is\r\nundesirable to \"block\" the connection until confirmation occurs.  Instead, the\r\ntransactor returns an immediate validation response, and the client must track\r\njournal updates to confirm that the data was written successfully.  \r\n\r\nAlternatively, the acknowledgement response could include a unique token that\r\nidentifies the write request.  When the transaction completes (successfully or\r\notherwise), the Transactor can send a message to the client with the status and\r\ninclude the token.  The client can then either mark the transaction as \r\nsuccessful, or retry on failure if possible.\r\n\r\n[rfc-1]: https://github.com/mediachain/mediachain/blob/master/rfc/mediachain-rfc-1.md\r\n[rfc-2]: https://github.com/mediachain/mediachain/blob/master/rfc/mediachain-rfc-2.md\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/mediachain/mediachain/issues/comments/214242418","html_url":"https://github.com/mediachain/mediachain/issues/17#issuecomment-214242418","issue_url":"https://api.github.com/repos/mediachain/mediachain/issues/17","id":214242418,"user":{"login":"vyzo","id":36426,"avatar_url":"https://avatars.githubusercontent.com/u/36426?v=3","gravatar_id":"","url":"https://api.github.com/users/vyzo","html_url":"https://github.com/vyzo","followers_url":"https://api.github.com/users/vyzo/followers","following_url":"https://api.github.com/users/vyzo/following{/other_user}","gists_url":"https://api.github.com/users/vyzo/gists{/gist_id}","starred_url":"https://api.github.com/users/vyzo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vyzo/subscriptions","organizations_url":"https://api.github.com/users/vyzo/orgs","repos_url":"https://api.github.com/users/vyzo/repos","events_url":"https://api.github.com/users/vyzo/events{/privacy}","received_events_url":"https://api.github.com/users/vyzo/received_events","type":"User","site_admin":false},"created_at":"2016-04-25T09:57:52Z","updated_at":"2016-04-25T09:57:52Z","body":"A slightly different approach with the Journal Interface: \r\n```scala\r\n  abstract class JournalBlock {\r\n    def index: BigInt\r\n    def chain: Reference\r\n    def entries: Seq[JournalEntry]\r\n  }\r\n  \r\n  trait Journal {\r\n    def insert(rec: CanonicalRecord): Xor[JournalError, CanonicalEntry]\r\n    def update(ref: Reference, cell: ChainCell): Xor[JournalError, ChainEntry]\r\n    def chain(ref: Reference) : Option[Reference]\r\n    def currentBlock: JournalBlock\r\n  }\r\n```\r\n\r\nThis transactor interface provides access to the current block being generated.\r\nThis allows clients to bootstrap by requesting the current block from the transactor, and fetching previous blocks from the store while receiving updates through the JournalClient interface."}}