Skip to content

Commit

Permalink
Update the Readme (#20)
Browse files Browse the repository at this point in the history 
* Update readme
* Add PR feedback for the installation sections

Signed-off-by: steve lasker <stevenlasker@hotmail.com>
  • Loading branch information
@SteveLasker
SteveLasker authored Jul 16, 2024
1 parent 17f5cd3 commit 31d6697
Showing 1 changed file with 148 additions and 65 deletions.
213 changes: 148 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,117 +1,200 @@
# veracity

Veracity is a command line tool providing support for inspecting DataTrails native `MERKLE_LOG` verifiable data.
Veracity is a command line tool providing support for inspecting the DataTrails native `MERKLE_LOG` verifiable data structures.

Familiarity with a command line environment on your chosen platform is assumed
by this README.
A general familiarity with _verifiable data structures_, and in particular binary merkle trees, would be advantageous, but is not required.

A general familiarity with verifiable data structures, and in particular binary
merkle trees, would be advantageous when using `veractity` but is not required.

## Support
## Installation

We provide pre-built native binaries for linux, mac, and windows. The
following architectures are supported:
Veracity provides native binaries for [Mac OS](#mac-install), [Linux](#linuxwsl-install) and Windows on the [releases](https://github.com/datatrails/veracity/releases) page.

| Platform | Architecture |
| :-------- | -----------: |
| MacOS(darwin) | arm64 |
| MacOS(darwin) | x86_64 |
| Linux | arm64 |
| Linux | x86_64 |
| Windows | x86_64 |
| Windows | i386 |
_Note_: For The Windows Subsystem for Linux (WSL), use the Linux binaries.

The linux binaries can also be used in Windows Subsystem for Linux.
| OS | Platform | Architecture |
| :------ | :-------- | -----------: |
| Mac | `darwin` | `arm64` |
| Mac | `darwin` | `x86_64` |
| Linux | `linux` | `arm64` |
| Linux | `linux` | `x86_64` |
| Windows | `windows` | `x86_64` |
| Windows | `windows` | `i386` |

## Installation
1. Select the desired release from the [releases page](https://github.com/datatrails/veracity/releases).
1. Download the archive for your host platform
1. Extract the archive
1. Set the file permissions
1. Move the binary to a location on your PATH

Or, follow these commands to install the latest build.

Installation is a manual process:
### Mac Install

1. Download the archive for your host platform
2. Extract the archive
3. Set the file permissions
4. Move the binary to a location on your PATH
```console
PLATFORM=$(uname -s | tr [:upper:] [:lower:])
ARCH=$(uname -m)
cd $TMPDIR
curl -sLO https://github.com/datatrails/veracity/releases/latest/download/veracity_${PLATFORM}_${ARCH}.tar.gz
tar -xf veracity_${PLATFORM}_${ARCH}.tar.gz
chmod +x ./veracity
mv ./veracity $HOME/.local/bin/
veracity --help
```

For example, for the Linux or Darwin OS the following steps would be conventional
### Linux/WSL Install

```
PLATFORM=Darwin
ARCH=arm64
```console
PLATFORM=$(uname -s | tr [:upper:] [:lower:])
ARCH=$(uname -m)
cd /tmp
curl -sLO https://github.com/datatrails/veracity/releases/latest/download/veracity_${PLATFORM}_${ARCH}.tar.gz
tar -xf veracity_${PLATFORM}_${ARCH}.tar.gz
chmod +x ./veracity
./veracity --help
mv ./veracity $HOME/.local/bin/
veracity --help
```

Set PLATFORM and ARCH according to you environment. Select the desired release
from the [releases page](https://github.com/datatrails/veracity/releases) as VERSION (Omitting the 'v').
#### Troubleshooting

The last step should report usage information. Usual practice is to move the
binary into a location on your $PATH. For example:
If `veracity --help` fails, check the following:

```
mkdir -p $HOME/bin
mv ./veracity $HOME/bin/
confirm `` includes `.local/bin`.
Either add to the path, or place in an alternate location

```console
# Check veracity exists in your $PATH
echo $PATH

# Add to the path
export PATH="$HOME/.local/bin:$PATH"
# reload the configuration
source ~/.bashrc

# Confirm which veracity binary is being used
which veracity
```

The last command will echo the location of the veracity binary if $HOME/bin is
in your $PATH
## Example Usage

### Environment Variables

# Verifying a single event
The following samples use environment variables to simplify the commands:

```console
EVENT_ID=publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa
DATATRAILS_URL=https://app.datatrails.ai
PUBLIC_TENANT_ID=tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
```

An example of verifying the following single event using api response data.
## Verifying A Single Event

https://app.datatrails.ai/archivist/v2/publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa
The following steps verify the single public event [`a022f458-8e55-4d63-a200-4172a42fc2aa`](https://app.datatrails.ai/archivist/v2/publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa) using the DataTrails API.

We use a publicly attested event so that you can check the event details directly.
Check the event details directly.

EVENT_ID=publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa
DATATRAILS_URL=https://app.datatrails.ai
PUBLIC_TENANT_ID=tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
1. Download the event from the DataTrails ledger:

curl -sL $DATATRAILS_URL/archivist/v2/$EVENT_ID | \
veracity --data-url $DATATRAILS_URL/verifiabledata --tenant=$PUBLIC_TENANT_ID verify-included
```console
curl -sL $DATATRAILS_URL/archivist/v2/$EVENT_ID > event.json
```

**By default there will be no output. If the verification has succeeded an exit code of 0 will be returned.**
1. Verify inclusion with `veracity`

If the verification command is run with `--loglevel=INFO` the output will be:
```console
cat event.json | \
veracity --data-url $DATATRAILS_URL/verifiabledata \
--tenant=$PUBLIC_TENANT_ID \
--loglevel=INFO \
verify-included
```

1. View the output, noting there are no verification errors

```output
verifying for tenant: tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
verifying: 663 334 018fa97ef269039b00 2024-05-24T08:27:00.2+01:00 publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa
verifying: 663 334 018fa97ef269039b00 2024-05-24T08:27:00.2+01:00
publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/a022f458-8e55-4d63-a200-4172a42fc2aa
leaf hash: bfc511ab1b880b24bb2358e07472e3383cdeddfbc4de9d66d652197dfb2b6633
OK|663 334|[aea799fb2a8..., proof path nodes, ...f0a52d2256c235]
```

**Note:** _To minimize veracity output, remove `--loglevel`, checking the exit code of 0 (`echo $?`) for a successful verification._

The elided proof path at time of writing was:

[aea799fb2a8c4bbb6eda1dd2c1e69f8807b9b06deeaf51b9e0287492cefd8e4c, 9f0183c7f79fd81966e104520af0f90c8447f1a73d4e38e7f2f23a0602ceb617, da21cb383d63896a9811f06ebd2094921581d8eb72f7fbef566b730958dc35f1, 51ea08fd02da3633b72ef0b09d8ba4209db1092d22367ef565f35e0afd4b0fc3, 185a9d55cf507ef85bd264f4db7228e225032c48da689aa8597e11059f45ab30, bab40107f7d7bebfe30c9cea4772f9eb3115cae1f801adab318f90fcdc204bdc, 94ca607094ead6fcd23f52851c8cdd8c6f0e2abde20dca19ba5abc8aff70d0d1, ba6d0fd8922342aafbba6073c5510103b077a7de9cb2d72fb652510110250f9e, 7fafc7edc434225afffc19b0582efa2a71b06a2d035358356df0a52d2256c235, b737375d837e67ee7bce182377304e889187ef0f335952174cb5bf707a0b4788]
```output
[aea799fb2a8c4bbb6eda1dd2c1e69f8807b9b06deeaf51b9e0287492cefd8e4c,
9f0183c7f79fd81966e104520af0f90c8447f1a73d4e38e7f2f23a0602ceb617,
a21cb383d63896a9811f06ebd2094921581d8eb72f7fbef566b730958dc35f1,
1ea08fd02da3633b72ef0b09d8ba4209db1092d22367ef565f35e0afd4b0fc3,
85a9d55cf507ef85bd264f4db7228e225032c48da689aa8597e11059f45ab30,
ab40107f7d7bebfe30c9cea4772f9eb3115cae1f801adab318f90fcdc204bdc,
4ca607094ead6fcd23f52851c8cdd8c6f0e2abde20dca19ba5abc8aff70d0d1,
a6d0fd8922342aafbba6073c5510103b077a7de9cb2d72fb652510110250f9e,
fafc7edc434225afffc19b0582efa2a71b06a2d035358356df0a52d2256c235,
737375d837e67ee7bce182377304e889187ef0f335952174cb5bf707a0b4788]
```

## Verify Tamper Resiliency

The same command accepts the result of a DataTrails list events call, e.g.
One of the many scenarios DataTrails prevents is tampering if and when information was written to the ledger.

DATATRAILS_URL=https://app.datatrails.ai
PUBLIC_TENANT_ID=tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
PUBLIC_ASSET_ID=publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8
1. To simulate backdating, the following backdates one of the events in the log:

```console
sed -i -e 's/2024-05-24T07:27:00.200Z/2024-04-24T07:27:00.200Z/g' ./event.json
```

1. Re-verify inclusion with `veracity verify-included`, noting the error

```console
cat event.json | \
veracity --data-url $DATATRAILS_URL/verifiabledata \
--tenant=$PUBLIC_TENANT_ID \
--loglevel=INFO \
verify-included
```

1. View the output

```output
...
error: the entry is not in the log. for tenant tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
```

## Verify All Events

The `veracity verify-included` command accepts the result of a DataTrails list events call

1. Pipe the `events` to veracity:

```console
PUBLIC_ASSET_ID=publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8
curl -sL $DATATRAILS_URL/archivist/v2/$PUBLIC_ASSET_ID/events | \
veracity --data-url $DATATRAILS_URL/verifiabledata --tenant=$PUBLIC_TENANT_ID verify-included
veracity --data-url $DATATRAILS_URL/verifiabledata \
--tenant=$PUBLIC_TENANT_ID \
--loglevel=INFO \
verify-included
```

## Read a Selected Node From the Log

# Read selected node from log
An example of reading a node associated with event, it's possible to visit [merkle log entry page](https://app.datatrails.ai/merklelogentry/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/999773ed-cc92-4d9c-863f-b418418705ea?public=true) for event [999773ed-cc92-4d9c-863f-b418418705ea](https://app.datatrails.ai/archivist/publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/999773ed-cc92-4d9c-863f-b418418705ea)

An example of reading node associated with specific event, it's possible to visit merkle log entry page https://app.datatrails.ai/merklelogentry/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/999773ed-cc92-4d9c-863f-b418418705ea?public=true for event https://app.datatrails.ai/archivist/publicassets/87dd2e5a-42b4-49a5-8693-97f40a5af7f8/events/999773ed-cc92-4d9c-863f-b418418705ea
On the Merkle log entry page we can see the `MMR Index` field with a value of `916` which can be used with the `node` command to retrieve the leaf directly from the merklelog using following command:

On the Merkle log entry page we can see `MMR Index` field with value `916` which can be used with `node` command to retrieve the leaf directly from merklelog by using following command
```console
veracity --data-url $DATATRAILS_URL/verifiabledata \
--tenant=$PUBLIC_TENANT_ID \
node --mmrindex 916
```

PUBLIC_TENANT_ID=tenant/6ea5cd00-c711-3649-6914-7b125928bbb4
DATATRAILS_URL=https://app.datatrails.ai

veracity --data-url $DATATRAILS_URL/verifiabledata --tenant=$PUBLIC_TENANT_ID node --mmrindex 916
The above command will output `c3323019fd1d325ac068d203c62007b504c5fa762446a9fe5d88e392ec96914b` which will match the value from the merkle log entry page.

Above command will output `c3323019fd1d325ac068d203c62007b504c5fa762446a9fe5d88e392ec96914b` which will match the value from the merkle log enty page.
## General Use Commands

# General use commands
Additional Commands include:

* `node` - read a merklelog node
* `verify-included` - verify the inclusion of an event, or list of events, in the tenant's merkle log

For more information, please visit the [DataTrails documentation](https://docs.datatrails.ai/)

0 comments on commit 31d6697

Please sign in to comment.