diff --git a/content/developers/api-reference/blockchain-api/index.md b/content/developers/api-reference/blockchain-api/index.md deleted file mode 100644 index 61ddd97d7..000000000 --- a/content/developers/api-reference/blockchain-api/index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "Blockchain API (v1alpha2)" -description: "Blockchain API Reference" -lead: "Blockchain API Reference" -date: 2021-06-09T13:57:04+01:00 -lastmod: 2021-06-09T13:57:04+01:00 -draft: false -images: [] -menu: - developers: - parent: "api-reference" -weight: 105 -toc: true -aliases: - - /docs/api-reference/blockchain-api/ ---- -{{< note >}} -**Note:** This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. -If you are looking for a simple way to test our API you might prefer our [Postman collection](https://www.postman.com/datatrails-inc/workspace/datatrails-public/overview), the [YAML runner](/developers/yaml-reference/story-runner-components/) or the [Developers](https://app.datatrails.io) section of the web UI. - -Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section. -{{< /note >}} -## Blockchain API Examples - -Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions. - -### Fetch Transactions for an event (v1alpha2) - -Blockchain transactions can be fetched from the blockchain endpoint using the Asset's Event ID as a parameter: - -```bash -assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -``` - -To fetch all transactions for an Asset's Events GET the blockchain resource: - -```bash -curl -v -X GET \ - -H "@$HOME/.datatrails/bearer-token.txt" \ - https://app.datatrails.ai/archivist/v1alpha2/blockchain/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -``` - -Depending on the type of [proof mechanism](/platform/overview/advanced-concepts/#proof-mechanisms) used, the response will be: - -#### Simple Hash: - -```json -{ - "transactions":[ - { - "transaction":{ - "hash":"0x4bb529697a096b23947e13f78492d90a66e2e9d76c5feb015cd321590b00e72a", - "nonce":"402", - "blockhash":"0x9ea557196d44e6433be7676ca5bdef5f8753fa6d92bbb5e7456fe3979f84ea40", - "block_number":"861180", - "transaction_index":0, - "r":"0xcb4282065fb5c0b6c674bf7d3b7fb9ee4c49f135b02b9b1cf1c607bb3ff406a", - "s":"0x5fa50214efdbc1cf13f98bb962ddf3224f1d5ba77cb19aafac5171b6ae1e8074", - "from":"0xED3939b59D1fC93dD3158522E728Df483BC9998d", - "to":"0x4c07935361B497EBD5801E3b4D2cF29C2179069e", - "value":"0", - "gas":"500000000", - "gas_price":"0", - "input":"0xa7ea3ea7607b464c8c5d4172880146c1c303329600000000000000000000000000000000ab6e28d836193ad54e941e9ff09b27946bdc7838c46fcf91bc11026e6737afb6000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000001a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000635bc6bb00000000000000000000000000000000000000000000000000000000000001e000000000000000000000000000000000000000000000000000000000000002200000000000000000000000000000000000000000000000000000000000000014313937302d30312d30315430303a30303a30305a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000014323032322d31302d32385431323a31303a33355a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000003677465000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000026c74000000000000000000000000000000000000000000000000000000000000", - "v":"0xea" - }, - "simple_hash_details":{ - "api_query":"https://app.datatrails.ai/archivist/v2/assets/-/events?order_by=SIMPLEHASHV1&proof_mechanism=SIMPLE_HASH×tamp_accepted_since=1970-01-01T00:00:00Z×tamp_accepted_before=2022-10-28T12:10:35Z", - "start_time":"1970-01-01T00:00:00Z", - "end_time":"2022-10-28T12:10:35Z", - "hash_schema_version":1, - "anchor_hash":"ab6e28d836193ad54e941e9ff09b27946bdc7838c46fcf91bc11026e6737afb6", - "event_count":6 - }, - "kind":"SIMPLE_HASH" - } - ], - "next_page_token":"" -} -``` - -{{< note >}} -**Note:** Please see our guide for [Verifying Assets and Events with Simple Hash](/developers/developer-patterns/verifying-with-simple-hash/). -{{< /note >}} - -## Blockchain OpenAPI Docs - -{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/master/doc/blockchainv1alpha2.swagger.json" >}} diff --git a/content/glossary/common-datatrails-terms/index.md b/content/glossary/common-datatrails-terms/index.md index 1966db93f..5c6dc634b 100644 --- a/content/glossary/common-datatrails-terms/index.md +++ b/content/glossary/common-datatrails-terms/index.md @@ -46,7 +46,7 @@ Select a term for more information. | [organization](/platform/administration/verified-domain/)| any entity with a distinct DataTrails account who publishes or verifies provenance information on the platform| | [principal_accepted](/platform/overview/advanced-concepts/#user-principals-on-events)| the actual user principal information belonging to the credential used to access the DataTrails REST interface| | [principal_declared](/platform/overview/advanced-concepts/#user-principals-on-events)| an optional user-supplied value that tells who performed an Event| -| [proof mechanism](/platform/overview/advanced-concepts/#proof-mechanisms) | method by which information on the DataTrails blockchain can be verified; selected when an Asset is created | +| [proof mechanism](/platform/overview/core-concepts/#proof-mechanisms) | method by which information on the DataTrails blockchain can be verified; selected when an Asset is created | | [provenance](https://en.wiktionary.org/wiki/provenance) | the version and ownership history of a piece of data. With DataTrails this is an immutable audit trail to prove Who Did What When to any piece of data | | [public asset](/platform/overview/public-attestation/) | Assets that can be used to publicly assert data, accessible by URL without the need for a DataTrails account | | [selector](/platform/overview/creating-an-asset/#creating-an-asset) | identifying attribute the Yaml Runner will use to check if your Asset exists already before attempting to create it | diff --git a/content/platform/overview/advanced-concepts/index.md b/content/platform/overview/advanced-concepts/index.md index 82c08acb7..dc8836e1a 100644 --- a/content/platform/overview/advanced-concepts/index.md +++ b/content/platform/overview/advanced-concepts/index.md @@ -119,14 +119,6 @@ Once committed to the DataTrails system, each lifecycle Event record carries 2 s For more detailed information on Events, and how to implement them, please refer to the [Events API Reference](/developers/api-reference/events-api/). -## Proof Mechanisms - -Assets and Events are core to the DataTrails platform, and being able to quickly demonstrate proof that these artifacts have not been tampered is key to being able to use them. - -When [creating an Asset](/platform/overview/creating-an-asset/), DataTrails uses a proof mechanism for that Asset and its Events. This determines how your data is recorded on the DataTrails blockchain. - -Our Simple Hash proof mechanism takes all the Events within a past time period (the default is the last 30 days) and commits them to the blockchain as one hash. This hash value can then be used to compare the current state of the Asset, and identify if any changes have occurred. With Simple Hash, you will not be able to see exactly what those changes were, only that something has changed. - ## Access Policies Sharing the right amount of information with your value chain partners is critical to creating a trustworthy shared history for Assets. It is important that every participant be able to see and contribute to the management of Assets without compromising security, commercial, or private personal information. For example, competing vendors should not see each other’s information, but both should be able to freely collaborate with their mutual customer or industry regulator. diff --git a/content/platform/overview/core-concepts/index.md b/content/platform/overview/core-concepts/index.md index 161bab466..b5d22bab5 100644 --- a/content/platform/overview/core-concepts/index.md +++ b/content/platform/overview/core-concepts/index.md @@ -37,6 +37,29 @@ Events are things that happen during an Asset's lifecycle. Each Event Record con Events can never be deleted or modified. Events provide details on Asset attributes, such as updating the weight of a shipment, and/or details about the event itself, such as a recording a new document version. +## Proof Mechanisms + +Assets and Events are core to the DataTrails platform, and being able to quickly demonstrate proof that these artifacts have not been tampered is key to being able to use them. + +When [creating an Asset](/platform/overview/creating-an-asset/), DataTrails uses a proof mechanism for that Asset and its Events. This determines how your data is recorded on the DataTrails blockchain. + +DataTrails attestations are committed to immutable storage that is underpinned by cryptographically verifiable Merkle Mountain Range data structures for long term verifiability, even when offline. + +{{< img src="merkleflow.png" alt="Rectangle" caption="" class="border-0" >}} + +**Four Increasing Trust Levels** + +In the customer's environment, data can be tampered, shredded, backdated... + +Once `STORED` in DataTrails and shared with partners, no party to the transaction can tamper, back-date or shred evidence. However there could be a suspicion that DataTrails (or a hacker in our systems, or Microsoft under subpœna) could tamper with the data, or make it unavailable or something. + +Once `COMMITTED` in the customer's Tenancy Merkle tree in public blob storage, customers can prove their Events to 3rd parties, AND any tampering by DataTrails is detectable (as long people check). Because this data is public, anyone can keep and maintain a copy just in case DataTrails' version disappears. If this checking is weak, and/or copies are not made, then in principle Data Trails could create forks. + +By adding all Tenancies to the Merkle Mountain Range (MMR) and signing the root, Events move to the `CONFIRMED` stage. The signature on to root holds DataTrails to account and prevents forks, and also prevents a kind of sybil attack that could otherwise be mounted by 3rd party verifiers. Even so, a tiny chance of tampering remains: DataTrails could possibly sign multiple MMRs and maintain multiple split histories, then present whichever version of the history is most advantageous. + +To make the whole history and individual events `UNEQUIVOCAL`, the root hash of the Committed MMR is periodically broadcast to single, well known location outside of DataTrails control (such as a smart contract address on Ethereum, or an official X account). + + ## Access Policies Sharing the right amount of information with the consumers of your data is critical to creating a trustworthy shared history for any Asset. It is important that every participant be able to see and contribute to the management of those Assets without compromising security and private information. To ensure stakeholders can access only the Assets and attributes relevant to them, transactions are private by default, unless the Asset was created as a [Public Asset](./#the-public-view). An Administrator defines how many of the Asset's attributes the Access Policy permits a user to see so that they only see what they need to complete a task. diff --git a/content/platform/overview/core-concepts/merkleflow.png b/content/platform/overview/core-concepts/merkleflow.png new file mode 100644 index 000000000..d4fd4fcbe Binary files /dev/null and b/content/platform/overview/core-concepts/merkleflow.png differ diff --git a/content/platform/overview/introduction/index.md b/content/platform/overview/introduction/index.md index ad2cd01b1..2114ffabe 100644 --- a/content/platform/overview/introduction/index.md +++ b/content/platform/overview/introduction/index.md @@ -33,3 +33,4 @@ DataTrails permanently records evidence into an **Immutable Audit Trail** to bri DataTrails delivers assured metadata in a single line of code in a way that makes recording and auditing the full lifecycle of a piece of data simple. Any authorized participant (including a user, a software agent or an endpoint device) can register the Events that they are involved in.
Users of the data can see a full picture of the data’s origin and history and by understanding *Who Did What When*, human actors and software/AI systems can make stronger real-time judgments about the trustworthiness of your data. +{{< img src="intro.png" alt="Rectangle" caption="DataTrails Functionality" class="border-0" >}} \ No newline at end of file diff --git a/content/platform/overview/introduction/intro.png b/content/platform/overview/introduction/intro.png new file mode 100644 index 000000000..6971bb4f3 Binary files /dev/null and b/content/platform/overview/introduction/intro.png differ diff --git a/content/platform/overview/registering-a-document-profile-asset/index.md b/content/platform/overview/registering-a-document-profile-asset/index.md index 8fc563567..22c187154 100644 --- a/content/platform/overview/registering-a-document-profile-asset/index.md +++ b/content/platform/overview/registering-a-document-profile-asset/index.md @@ -134,7 +134,7 @@ In the file you created earlier, begin adding metadata for your Asset: * `Document Type` - This is the class of the object; while it is arbitrary, it is best to have consistency amongst the type of Documents you use i.e. if it is a purchase order, the type could be `Purchase Order`, which will then be pre-populated for future Documents to use as their own types. * `Proof Mechanism` - The method used to commit the blockchain transaction. - Please see our [Advanced Concepts](/platform/overview/advanced-concepts/#proof-mechanisms) section for more information on selecting a Proof Mechanism for your Document + Please see our [Advanced Concepts](/platform/overview/core-concepts/#proof-mechanisms) section for more information on the Proof Mechanism for your Document {{< tabs name="add_asset_details_min" >}} {{{< tab name="UI" >}} {{< img src="RegDocAdvancedOptions.png" alt="Rectangle" caption="Advanced Options" class="border-0" >}}