Skip to content

Commit

Permalink
Merge pull request #64 from mildred/ipld-spec-link-insteadof-mlink
Browse files Browse the repository at this point in the history 
Rename Merkle links key from mlink to link
  • Loading branch information
@jbenet
jbenet committed Feb 11, 2016
2 parents 4066034 + 6f5a601 commit 6e69d61
Showing 1 changed file with 40 additions and 37 deletions.
77 changes: 40 additions & 37 deletions merkledag/ipld.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ A _merkle-link_ is a link between two objects which is content-addressed with th
- **Cryptographic Integrity Checking**: resolving a link's value can be tested by hashing. In turn, this allows wide, secure, trustless exchanges of data (e.g. git or bittorrent), as others cannot give you any data that does not hash to the link's value.
- **Immutable Datastructures**: data structures with merkle links cannot mutate, which is a nice property for distributed systems. This is useful for versioning, for representing distributed mutable state (eg CRDTs), and for long term archival.

A _merkle-link_ is represented in the IPLD object model by a map containing a key `@link` mapped to a string value: the actual link. When dereferencing the link, the map itself is to be replaced by the object it points to unless the link path is invalid.

The link can either be a base58 hash, in which case it is assumed that it is a link in the `/ipfs` hierarchy, or directly the absolute path to the object. Currently, only the `/ipfs` hierarchy is allowed.

If an application wants to use the `@link` key for other purposes, the application itself is responsible to escape the keys in the IPLD object so that the application keys do not conflict with the `@link` key. When discussing application specific paths, it may be worth escaping all keys starting with `@` in case future versions of IPLD make use of other keys.

### What is a _merkle-graph_ or a _merkle-dag_?

Objects with merkle-links form a Graph (merkle-graph), which necessarily is both Directed, and which can be counted on to be Acyclic, iff the properties of the cryptographic hash function hold. I.e. a _merkle-dag_. Hence all graphs which use _merkle-linking_ (_merkle-graph_) are necessarily also Directed Acyclic Graphs (DAGs, hence _merkle-dag_).
Expand Down Expand Up @@ -147,7 +153,7 @@ Merkle-Linking between nodes is the reason for IPLD to exist. A Link in IPLD is
{
"title": "As We May Think",
"author": {
"mlink": "QmAAA...AAA" // links to the node above.
"@link": "QmAAA...AAA" // links to the node above.
}
}
```
Expand All @@ -159,7 +165,7 @@ Suppose this hashes to the multihash value `QmBBB...BBB`. This node links the _s
{
"title": "As We May Think",
"author": {
"mlink": "QmAAA...AAA" // links to the node above.
"@link": "QmAAA...AAA" // links to the node above.
}
}

Expand All @@ -185,17 +191,17 @@ For example, supposed you have a file system, and want to assign metadata like p
```js
{
"foo": {
"mlink": "QmCCC...111"
"@link": "QmCCC...111"
"mode": "0755",
"owner": "jbenet"
},
"cat.jpg": {
"mlink": "QmCCC...222"
"@link": "QmCCC...222"
"mode": "0644",
"owner": "jbenet"
},
"doge.jpg": {
"mlink": "QmCCC...333",
"@link": "QmCCC...333",
"mode": "0644",
"owner": "jbenet"
}
Expand All @@ -207,15 +213,15 @@ or in YML
```yml
---
foo:
mlink: QmCCC...111
@link: QmCCC...111
mode: 0755
owner: jbenet
cat.jpg:
mlink: QmCCC...222
@link: QmCCC...222
mode: 0644
owner: jbenet
doge.jpg:
mlink: QmCCC...333
@link: QmCCC...333
mode: 0644
owner: jbenet
```
Expand All @@ -232,23 +238,23 @@ Though we have new properties in the links that are _specific to this datastruct
{
"subfiles": [
{
"mlink": "QmPHPs1P3JaWi53q5qqiNauPhiTqa3S1mbszcVPHKGNWRh"
"@link": "QmPHPs1P3JaWi53q5qqiNauPhiTqa3S1mbszcVPHKGNWRh"
},
{
"mlink": "QmPCuqUTNb21VDqtp5b8VsNzKEMtUsZCCVsEUBrjhERRSR"
"@link": "QmPCuqUTNb21VDqtp5b8VsNzKEMtUsZCCVsEUBrjhERRSR"
},
{
"mlink": "QmS7zrNSHEt5GpcaKrwdbnv1nckBreUxWnLaV4qivjaNr3"
"@link": "QmS7zrNSHEt5GpcaKrwdbnv1nckBreUxWnLaV4qivjaNr3"
}
]
}

> ipld cat --yml QmCCC...CCC/doge.jpg
---
subfiles:
- mlink: QmPHPs1P3JaWi53q5qqiNauPhiTqa3S1mbszcVPHKGNWRh
- mlink: QmPCuqUTNb21VDqtp5b8VsNzKEMtUsZCCVsEUBrjhERRSR
- mlink: QmS7zrNSHEt5GpcaKrwdbnv1nckBreUxWnLaV4qivjaNr3
- @link: QmPHPs1P3JaWi53q5qqiNauPhiTqa3S1mbszcVPHKGNWRh
- @link: QmPCuqUTNb21VDqtp5b8VsNzKEMtUsZCCVsEUBrjhERRSR
- @link: QmS7zrNSHEt5GpcaKrwdbnv1nckBreUxWnLaV4qivjaNr3

> ipld cat --json QmCCC...CCC/doge.jpg/subfiles/1
{
Expand Down Expand Up @@ -300,7 +306,7 @@ On the subject of integers, there exist a variety of formats which represent int

## Serialized Data Formats

IPLD supports a variety of serialized data formats through [multicodec](https://github.com/jbenet/multicodec). These can be used however is idiomatic to the format, for example in `CBOR`, we can use `CBOR` type tags to represent the merkle-link, and avoid writing out the full string key `mlink`. Users are encouraged to use the formats to their fullest, and to store and transmit IPLD data in whatever format makes the most sense. The only requirement **is that there MUST be a well-defined one-to-one mapping with the IPLD Canonical format.** This is so that data can be transformed from one format to another, and back, without changing its meaning nor its cryptographic hashes.
IPLD supports a variety of serialized data formats through [multicodec](https://github.com/jbenet/multicodec). These can be used however is idiomatic to the format, for example in `CBOR`, we can use `CBOR` type tags to represent the merkle-link, and avoid writing out the full string key `@link`. Users are encouraged to use the formats to their fullest, and to store and transmit IPLD data in whatever format makes the most sense. The only requirement **is that there MUST be a well-defined one-to-one mapping with the IPLD Canonical format.** This is so that data can be transformed from one format to another, and back, without changing its meaning nor its cryptographic hashes.

### Canonical Format

Expand Down Expand Up @@ -345,16 +351,16 @@ Split into multiple independent sub-Files.
"size": "1424119",
"subfiles": [
{
"mlink": "QmAAA...",
"@link": "QmAAA...",
"size": "100324"
},
{
"mlink": "QmAA1...",
"@link": "QmAA1...",
"size": "120345",
"repeat": "10"
},
{
"mlink": "QmAA1...",
"@link": "QmAA1...",
"size": "120345"
},
]
Expand All @@ -366,17 +372,17 @@ Split into multiple independent sub-Files.
```js
{
"foo": {
"mlink": "QmCCC...111"
"@link": "QmCCC...111"
"mode": "0755",
"owner": "jbenet"
},
"cat.jpg": {
"mlink": "QmCCC...222"
"@link": "QmCCC...222"
"mode": "0644",
"owner": "jbenet"
},
"doge.jpg": {
"mlink": "QmCCC...333",
"@link": "QmCCC...333",
"mode": "0644",
"owner": "jbenet"
}
Expand All @@ -398,15 +404,15 @@ Split into multiple independent sub-Files.
```js
{
"foo": {
"mlink": "QmCCC...111"
"@link": "QmCCC...111"
"mode": "0755"
},
"cat.jpg": {
"mlink": "QmCCC...222"
"@link": "QmCCC...222"
"mode": "0644"
},
"doge.jpg": {
"mlink": "QmCCC...333",
"@link": "QmCCC...333",
"mode": "0644"
}
}
Expand All @@ -416,10 +422,10 @@ Split into multiple independent sub-Files.

```js
{
"tree": {"mlink": "e4647147e940e2fab134e7f3d8a40c2022cb36f3"},
"tree": {"@link": "e4647147e940e2fab134e7f3d8a40c2022cb36f3"},
"parents": [
{"mlink": "b7d3ead1d80086940409206f5bd1a7a858ab6c95"},
{"mlink": "ba8fbf7bc07818fa2892bd1a302081214b452afb"}
{"@link": "b7d3ead1d80086940409206f5bd1a7a858ab6c95"},
{"@link": "ba8fbf7bc07818fa2892bd1a302081214b452afb"}
],
"author": {
"name": "Juan Batiz-Benet",
Expand All @@ -441,8 +447,8 @@ Split into multiple independent sub-Files.

```js
{
"parent": {"mlink": "Qm000000002CPGAzmfdYPghgrFtYFB6pf1BqMvqfiPDam8"},
"transactions": {"mlink": "QmTgzctfxxE8ZwBNGn744rL5R826EtZWzKvv2TF2dAcd9n"},
"parent": {"@link": "Qm000000002CPGAzmfdYPghgrFtYFB6pf1BqMvqfiPDam8"},
"transactions": {"@link": "QmTgzctfxxE8ZwBNGn744rL5R826EtZWzKvv2TF2dAcd9n"},
"nonce": "UJPTFZnR2CPGAzmfdYPghgrFtYFB6pf1BqMvqfiPDam8"
}
```
Expand All @@ -454,19 +460,16 @@ This time, im YML. TODO: make this a real txn
```yml
---
inputs:
- input: {mlink: Qmes5e1x9YEku2Y4kDgT6pjf91TPGsE2nJAaAKgwnUqR82}
- input: {@link: Qmes5e1x9YEku2Y4kDgT6pjf91TPGsE2nJAaAKgwnUqR82}
amount: 100
outputs:
- output: {mlink: Qmes5e1x9YEku2Y4kDgT6pjf91TPGsE2nJAaAKgwnUqR82}
- output: {@link: Qmes5e1x9YEku2Y4kDgT6pjf91TPGsE2nJAaAKgwnUqR82}
amount: 50
- output: {mlink: QmbcfRVZqMNVRcarRN3JjEJCHhQBcUeqzZfa3zoWMaSrTW}
- output: {@link: QmbcfRVZqMNVRcarRN3JjEJCHhQBcUeqzZfa3zoWMaSrTW}
amount: 30
- output: {mlink: QmV9PkR2gXcmUgNH7s7zMg9dsk7Hy7bLS18S9SHK96m7zV}
- output: {@link: QmV9PkR2gXcmUgNH7s7zMg9dsk7Hy7bLS18S9SHK96m7zV}
amount: 15
- output: {mlink: QmP8r8fLUnEywGnRRUrHB28nnBKwmshMLiYeg8udzYg7TK}
- output: {@link: QmP8r8fLUnEywGnRRUrHB28nnBKwmshMLiYeg8udzYg7TK}
amount: 5
script: OP_VERIFY
```

0 comments on commit 6e69d61

Please sign in to comment.