Skip to content

Latest commit

 

History

History
324 lines (246 loc) · 16.5 KB

README.md

File metadata and controls

324 lines (246 loc) · 16.5 KB

RESO Distributed Ledger Event Model

Request for Comment

Submitted to RESO Distributed Ledger Worgroup by the Real Estate Blockchain Initiative

Version 1.3 - April 2019


Table of Contents


Overview

An event is a record of occurrence that relects the state of a document, process, system, or object as of a point in time. Events expressed with a standard approach are easier to store and pass between systems. The RESO Distributed Ledger Event Model represents a standard approach that can be used to reliably record, playback, and communicate events.

The Event Model is an application communication standard that is independent of the underlying systems on each side. It is ideal for integrating traditional systems with distributed ledgers in a business-to-business (B2B) arrangement.
The model can also be used to connect websites with distributed ledgers in a business-to-consumer (B2C) scenario.

Field Responsibility Scope Description
TransactionId System Assigned Unique within the ledger A unique identifier created for each recording in an immutable ledger
EventSubject Application Supplied Opaque to the ledger Uniquely identifies the object of the event. e.g. Unique Property Identifier, Unique Agent Identifier, Unique Organization Identifier, etc.
System Lookup System Value Classification of the business system generating the event. The type of user is handled by the Entity lookup.
SubjectType Lookup SubjectType Value Classification of the object the event is being applied to; the noun. Related to the EventSubject.
Entity Lookup Entity Value Classification of the what generated the event; the actor. A person uses a System to record events.
Event Lookup Event Value Describes a document, occurrence , or incident. Typically has associated documentation. Further classified by State.
State Lookup State Value A verb identifying the occurrence being recorded. Expressed in terms of the Event argument.
Recorder Application Supplied Opaque to the ledger An identifier of the entity who is responsible for creating the event.
Timestamp System Assigned UTC timestamp The underlying distributed ledger assigns this field.
Version System Assigned Version of this standard The underlying distributed ledger assigns this field
Application Application Supplied Opaque to the ledger Identifies the application or system used to record the event; the system of record.

There is a section of this document that describes each of the Lookup types (System, Resource, etc.).

All of the components of the model are expressed as JSON formatted objects conforming to RFC 8259 and ECMA-404.

Notes

  1. System Assigned fields TransactionId, Timestamp, and Version are created by the distributed ledger. They should not proprietary to the distributed ledger being used.

  2. Application Supplied field EventSubject and Application have meaning to the recording application. The ledger does not operate on these fields and should pass them unaltered.

  3. The Version field governs which version of the standard was used when the event was recorded. The set of lookups can change between versions and and applications are responsible for reconciling records created these differences.

  4. The Recorder field value can be used to lookup the identity of the entity that created the event.


Usage

The RESO Event Model is a communications format and is not dependent on systems that create or consume events.

Events are created by Event Producers and be either traditional systems or distributed ledgers. After the event is created, it is formatted into the RESO Event Model format and transmitted to other applications.

                                                     .---------------.
                                                     |  Distributed  |
  .---------------.                            .---->|    Ledger     |
  |  Distributed  |                            |     '---------------'
  |    Ledger     |---.                        |     .---------------.
  '---------------'   |                        |     | Web or Mobile |
                      |------------------------|---->|  Application  |
  .---------------.   |       RESO Event       |     '---------------'
  |  Traditional  |---'          Model         |     .---------------.
  |    System     |                            |     |  Traditional  |
  '---------------'                            '---->|    System     |
                                                     '---------------'

        Event                                              Event
      Producers                                          Consumers

Applications that consumer RESO Event Model formatted events are called Event Consumers. An Event Consumer can be a web application, mobile app, traditional system, or a distributed ledger.


Examples

This section presents normative examples of the event model. These are simple examples intended to demonstrate the model. All of the records use the EventSubject field to represent the same property; RESO UPI (US-42049-49888-1213666-R-N).

History of a home being sold

Each record represents an event. The records have been sorted by the Timestamp field to present the chronological sequencing of the history.

In this example, all of the events were created by the same entity because all of the Recorder fields have the same value; "ae1643".

TransactionId EventSubject System SubjectType Entity Event State Recorder Timestamp Application
4b46aadd-0f2a-4e79-b3a6-e2e45927d2a2 US-42049-49888-1213666-R-N Property Listing Service Property Broker Listing Recorded ae1643 Sun, 03 Jun 2018 13:04:05 GMT 87478-a43
c7e5a353f-d3b4-2f48-8f02-604bbe507805 US-42049-49888-1213666-R-N Property Listing Service Property Broker Listing Changed ae1643 Sat, 21 Jul 2018 18:34:22 GMT 87478-a43
cd7a53f-d3b4-4e48-845b-604bbe507805 US-42049-49888-1213666-R-N Property Marketing Service Property Agent Openhouse Published ae1643 Sun, 19 Aug 2018 12:01:45 GMT 15435-dd6
2ad753f4-d3b4-4e47-8402-604bbe7886434 US-42049-49888-1213666-R-N Property Listing Service Property Broker Offer Received ae1643 Tue, 28 Aug 2018 18:11:22 GMT 87478-a43
e27a353f-d3b4-32e8-8629-604bbe237802 US-42049-49888-1213666-R-N Transaction Management Service Property Broker Contract Signed ae1643 Wed, 03 Oct 2018 12:011:48 GMT 438-f32

Construction project

Each record represents an event. The records have been sorted by the Timestamp field to present the chronological sequencing of the history.

In this example, the same entity (cf67de) records events through both a Tax Assessment System and Property Recording System. Different recorders have provided events using a Mortgage Industry Service (975fb) and through Manual Inout (a4b762).

TransactionId EventSubject System SubjectType Entity Event State Recorder Timestamp Application
4b46aadd-0f2a-4e79-b3a6-e2e45927d2a2 US-42049-49888-1213666-R-N Tax Assessment System Tax County Assessment Received cf67de Thu, 14 Jun 2017 13:04:05 GMT 87478-a43
c7e5a353f-d3b4-2f48-8f02-604bbe507805 US-42049-49888-1213666-R-N Mortgage Industry Service Loan Builder Estimate Received 975fb Sat, 21 Jul 2018 18:34:22 GMT 87478-a43
cd7a53f-d3b4-4e48-845b-604bbe507805 US-42049-49888-1213666-R-N Property Recording System Loan Builder Lien Placed cf67de Sun, 19 Aug 2018 12:01:45 GMT 15435-dd6
2ad753f4-d3b4-4e47-8402-604bbe7886434 US-42049-49888-1213666-R-N Manual Input Loan Builder Construction Completed a4b762 Tue, 28 Aug 2018 18:11:22 GMT 87478-a43
e27a353f-d3b4-32e8-8629-604bbe237802 US-42049-49888-1213666-R-N Property Recording System Loan Builder Lien Removed cf67de Wed, 03 Oct 2018 12:011:48 GMT 438-f32
7646aaef-ec2a-4e79-b5a6-e2e39827d0a5 US-42049-49888-1213666-R-N Tax Assessment System Tax County Assessment Received cf67de Thu, 13 Dec 2018 14:08:23 GMT 87478-a43

Lookup Fields

Lookups are used to avoid freeform text in event fields. Users are typically presented the options for these fields as drop-downs. Lookup values are not codified, therefore the entire text value is used in the record.

Values in addition those presented are not valid. In order to add values to lookup fields, the specification should bbe revised with a new version.

Entity Lookup

The Entity Lookup is the clasification of what kind of person is acting as a recorder. The person records events using a System.

Entity Values

  • Agent
  • Broker
  • Builder
  • Buyer
  • City
  • County
  • Escrow
  • Lender
  • MLS
  • Owner
  • Vendor

Event Lookup

The Event Lookup classifies a document or documented occurrence that is associated with the record. Further classified by State.

Event Values

  • Application
  • Appraisal
  • Assessment
  • Construction
  • Contract
  • Deed
  • Estimate
  • Identity
  • Improvement
  • Lien
  • Listing
  • Offer
  • Openhouse
  • Permit
  • Price
  • Referral
  • Status

State Lookup

The State Lookup classifies what specifically is being recorded about the Event. It represents an action or verb.

State Values

  • Accepted
  • Changed
  • Closed
  • Completed
  • Created
  • Funded
  • Placed
  • Received
  • Recorded
  • Rejected
  • Removed
  • Signed
  • Published

SubjectType Lookup

The SubjectType Lookup classifies what is being modified by the record. It identifies what is in the Event Subject Field.

SubjectType Values

  • Agent
  • Loan
  • Office
  • Property
  • Referral
  • Tax
  • Transaction

System Lookup

The System Lookup classifies the system generating the record. It is related to the Application field which identifies the software creating the record. It is also related to the Entity lookup which identifies what kind of user is creating the record.

System Values

  • Property Listing Service
  • Property Registration Service
  • Broker Referral Tracking
  • Mortgage Industry Service
  • Property Marketing Service
  • Property Recording System
  • Tax Assessment System
  • Transaction Management Service
  • Manual Input

Assigned Fields

Assigned event fields contain freeform text. These fields are assigned by applications.

Application

EventSubject is comprised of alphanumeric digits and hyphens only. Letters are not case-sensitive. Identifies the application or system used to record the event. It represents the system of record.

EventSubject

EventSubject is comprised of alphanumeric digits and hyphens only. Letters are not case-sensitive. This format is compatible with the RESO Universal Property Identifier format. An EventSubject can also represent other RESO values such as the Universal Agent Identifier and Universal Organization Identifier.

Recorder

Recorder is an identifier of the entity that created the event. It can be an individual or company. An Registry of Recorders can be used to identify the recorder. Applications can use the registry, along with information from the event to find more information anbout the record.

If the Recorder field value is not present in the Registry of Recorders, then there is no eneity that will stnd behind the authenticity of the event.

Timestamp

The underlying distributed ledger assigns this field and it should represent UTC time.

TransactionId

A unique identifier created by the ledger for each recording. The value should be independent of the distribbuted ledger.

Version

Version represent which verson of the standard is be used for the event. The set of lookups can change between versions of the standard and applications are responsible for reconciling records with different versions.

Additional lookup values (to the values presented in this docuemnt) are not valid. Add additional values to lookup fields requires a revision of the specification.