# Examples of Tools Interoperation

## Looking at a Seed

Let's start by exporting a seed from the Gordian SeedTool iOS app. This is the seed we'll use. It has both a creation date and a human-readable note:


We tap Authenticate > Backup > Backup as Gordian Envelope...


We get several export options...


We want to get a textual Gordian Envelope, so we tap Share. The Share Sheet appears and we tap Copy to Clipboard. The result pasted is here, and we'll assign it to a shell variable `ENVELOPE`:

$ ENVELOPE=ur:envelope/lptpcsgdhkwzdtfthptokigtvwnnjsqzcxknsktdoyadcsspoybetpcssecyhnencyahoybdtpcskpfyhsjpjecxgdkpjpjojzihcxfpjskphscxgsjlkoihoyaatpcsjsghisinjkcxinjkcxjyisihcxjtjljyihdmolbwjoso

This URI is the same text you would get by scanning the QR code. It's a "Uniform Resource" (UR) of type "envelope". The remaining letters are the ByteWords-encoded data of the envelope.

The contents of the UR are a binary format called CBOR. We can ask the `envelope` command line tool to show us the decoded binary as hexadecimal:

$ envelope --cbor $ENVELOPE
d8c885d8185059f2293a5bce7d4de59e71b4207ac5d2a10118c8a110d818c11a60361a05a10bd818754461726b20507572706c652041717561204c6f7665a104d818715468697320697320746865206e6f74652e

This doesn't really help us understand the Envelope's structure. So one level up is "CBOR diagnostic notation", which clearly shows the hierarchical nature of the Envelope, and how it's encoded in CBOR

$ envelope --diag $ENVELOPE
200(   / envelope /
   [
      24(   / leaf /
         h'59f2293a5bce7d4de59e71b4207ac5d2'
      ),
      {1: 200},
      {
         16:
         24(   / leaf /
            1(2021-02-24T09:19:01Z)
         )
      },
      {
         11:
         24(   / leaf /
            "Dark Purple Aqua Love"
         )
      },
      {
         4:
         24("This is the note.")   / leaf /
      }
   ]
)

It's still hard to make out the meaning of the Envelope's CBOR. So finally we format the envelope in "Envelope notation", which is a high-level view of the contents of an Envelope:

$ envelope $ENVELOPE
Bytes(16) [
    isA: Seed
    date: 2021-02-24T09:19:01Z
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

Now it's much easier to see the meaning: First there is the envelope's *subject* `Bytes(16)` which is the data of seed itself, and the envelope contains four *assertions* about those 16 bytes. Each assertion is a *predicate: object* pair.

* The subject represents a cryptographic seed (`isA: Seed`)
* It has a primary datestamp (`date: 2021-02-24T09:19:01Z`)
* It has a name (`hasName: "Dark Purple Aqua Love"`), and
* It has human-readable note. (`note: "This is the note."`)

The envelope tool has a built-in dictionary of "known value" to "name" translations, so `{1: 200}` in CBOR becomes `isA: Seed` in Envelope notation.

One thing the CBOR diagnostic notation shows that the Envelope notation doesn't is the actual binary of the seed itself: `59f2293a5bce7d4de59e71b4207ac5d2`.

## Constructing the Seed Ourselves

Let's construct an Envelope containing the same data as the example.

Every Envelope has a subject. In some cases, that's *all* it has. So we'll start by defining the subject of our envelope as the raw data from the seed. We'll also assign the result to the shell variable $MY_ENVELOPE:

$ MY_ENVELOPE_1=`envelope subject --data '59f2293a5bce7d4de59e71b4207ac5d2'`
$ echo $MY_ENVELOPE_1
ur:envelope/tpcsgdhkwzdtfthptokigtvwnnjsqzcxknsktddntnbwfr

Let's print this in Envelope notation to see what we've got so far:

$ envelope $MY_ENVELOPE_1
Bytes(16)

OK, now we need to add the four assertions. Let's start with the name:

$ MY_ENVELOPE_2=`envelope assertion --known hasName --string "Dark Purple Aqua Love" $MY_ENVELOPE_1`
$ envelope $MY_ENVELOPE_2
Bytes(16) [
    hasName: "Dark Purple Aqua Love"
]

Now the note:

$ MY_ENVELOPE_3=`envelope assertion --known note --string "This is the note." $MY_ENVELOPE_2`
$ envelope $MY_ENVELOPE_3
Bytes(16) [
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

Now the type declaration:

$ MY_ENVELOPE_4=`envelope assertion --known isA --known Seed $MY_ENVELOPE_3`
$ envelope $MY_ENVELOPE_4
Bytes(16) [
    isA: Seed
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

And finally the date:

$ MY_ENVELOPE_5=`envelope assertion --known date --date "2021-02-24T09:19:01Z" $MY_ENVELOPE_4`
$ envelope $MY_ENVELOPE_5
Bytes(16) [
    isA: Seed
    date: 2021-02-24T09:19:01Z
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

There you have it. Now let's look at the raw UR form of the envelope we just made:

$ echo $MY_ENVELOPE_5
ur:envelope/lptpcsgdhkwzdtfthptokigtvwnnjsqzcxknsktdoyadcsspoybetpcssecyhnencyahoybdtpcskpfyhsjpjecxgdkpjpjojzihcxfpjskphscxgsjlkoihoyaatpcsjsghisinjkcxinjkcxjyisihcxjtjljyihdmolbwjoso

And compare it to the one we exported from iOS Gordian Seed Tool App:

$ echo $ENVELOPE
ur:envelope/lptpcsgdhkwzdtfthptokigtvwnnjsqzcxknsktdoyadcsspoybetpcssecyhnencyahoybdtpcskpfyhsjpjecxgdkpjpjojzihcxfpjskphscxgsjlkoihoyaatpcsjsghisinjkcxinjkcxjyisihcxjtjljyihdmolbwjoso

Notice that they are identical, even though we added the assertions in a different order than they appear in the CBOR diagnostic notation *or* the Envelope notation. With Envelope, as long as you encode the same information, it doesn't matter the order you encode it in: you will get the exact same binary representation. This property is one aspect of *deterministic encoding*.

## Adding an Attachment

An *attachment* is a standard way of adding discoverable third-party data to Gordian Envelopes that support them. The Seed envelope is one such format. Attachments are described in [BCR-2023-006](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2023-006-envelope-attachment.md).

Here's our example seed with an attachment added:

Bytes(16) [
    isA: Seed
    attachment: {
        "Attachment Data"
    } [
        conformsTo: "https://example.com/seed-envelope-attachment/v1"
        vendor: "com.example"
    ]
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

The attachment is signified by an `attachment` assertion (there can be more than one). The object of the assertion is a wrapped Envelope containing the "payload" (in this case the string `"Attachment Data"`, but it can be any kind of Envelope. There are also two assertions: `vendor` and `conformsTo`. Only the `vendor` assertion is required, but the `conformsTo` assertion is helpful to point to documentation when an attachment conforms to an open specification.

Let's compose the attachment shown:

$ ATTACHMENT=`envelope subject "Attachment Data" | \
    envelope subject --wrapped | \
    envelope assertion --known vendor --string "com.example" | \
    envelope assertion --known conformsTo --string "https://example.com/seed-envelope-attachment/v1"`
$ envelope $ATTACHMENT
{
    "Attachment Data"
} [
    conformsTo: "https://example.com/seed-envelope-attachment/v1"
    vendor: "com.example"
]

To complete the process, we add the `$ATTACHMENT` envelope as the object of an `attachment` assertion:

$ ENVELOPE_WITH_ATTACHMENT=`envelope assertion --known attachment --envelope $ATTACHMENT $ENVELOPE`
$ envelope $ENVELOPE_WITH_ATTACHMENT
Bytes(16) [
    isA: Seed
    attachment: {
        "Attachment Data"
    } [
        conformsTo: "https://example.com/seed-envelope-attachment/v1"
        vendor: "com.example"
    ]
    date: 2021-02-24T09:19:01Z
    hasName: "Dark Purple Aqua Love"
    note: "This is the note."
]

## Storing a Seed with Attachments in SeedTool

Here is the UR form of the Envelope with attachment that we composed above:

$ echo $ENVELOPE_WITH_ATTACHMENT
ur:envelope/lntpcsgdhkwzdtfthptokigtvwnnjsqzcxknsktdoycseylstpsptpcsjlfpjyjyhsiaisjnihjtjycxfyhsjyhsoycseetpcsksdlisjyjyjojkftdldlihkshsjnjojzihdmiajljndljkihihiedpihjtkoihjzjljoihdphsjyjyhsiaisjnihjtjydlkoehoycseotpcsjeiajljndmihkshsjnjojzihoyadcsspoybetpcssecyhnencyahoybdtpcskpfyhsjpjecxgdkpjpjojzihcxfpjskphscxgsjlkoihoyaatpcsjsghisinjkcxinjkcxjyisihcxjtjljyihdmmwgrgdhl

The Gordian SeedTool app 1.6 (70) and later supports attachments for seeds, so we can import the UR above into it:


Scrolling to the bottom of the seed detail view, you can see that it shows the Envelope notation for the seed, including the attachment:


This seed including its attachments can now be exported from Gordian SeedTool, or backed up using SSKR.