8bit.lol
forked from
futur.blue/pegasus
objective categorical abstract machine language personal data server
futur.blue
1# ipld
2
3is a mostly [DASL-compliant](https://dasl.ing/) implementation of [CIDs](https://dasl.ing/cid.html), [CAR](https://dasl.ing/car.html), and [DAG-CBOR](https://dasl.ing/drisl.html) for OCaml.
4
5This library implements the core IPLD primitives needed for atproto.
6
7## components
8
9- **CID** - Content Identifiers (CIDv1) with SHA-256 digests
10- **CAR** - Content Addressable aRchives for storing and transferring IPLD data
11- **DAG-CBOR** - Deterministic CBOR encoding for content-addressed data
12
13## installation
14
15Add to your `dune-project`:
16
17```lisp
18(depends
19 ipld)
20```
21
22## usage
23
24### working with CIDs
25
26```ocaml
27open Ipld
28
29(* Create a CID from data *)
30let cid = Cid.create Cid.Dcbor data_bytes
31
32(* Encode CID to base32 string *)
33let cid_string = Cid.to_string cid
34(* => "bafyreihffx5a2e7k5uwrmmgofbvzujc5cmw5h4espouwuxt3liqoflx3ee" *)
35
36(* Decode CID from string *)
37match Cid.of_string cid_string with
38| Ok cid -> (* use cid *)
39| Error msg -> failwith msg
40
41(* Convert to/from bytes *)
42let bytes = Cid.to_bytes cid
43match Cid.of_bytes bytes with
44| Ok cid -> (* use cid *)
45| Error msg -> failwith msg
46```
47
48### DAG-CBOR encoding
49
50```ocaml
51open Dag_cbor
52
53(* Create CBOR values *)
54let value = `Map (String_map.of_list [
55 ("name", `String "Alice");
56 ("age", `Integer 30L);
57 ("verified", `Boolean true);
58 ("profile_cid", `Link some_cid);
59])
60
61(* Encode to bytes *)
62let encoded = Dag_cbor.encode value
63
64(* Decode from bytes *)
65let decoded = Dag_cbor.decode encoded
66```
67
68### CAR files
69
70CAR (Content Addressable aRchive) files store multiple IPLD blocks with their CIDs.
71
72```ocaml
73open Car
74
75(* Write blocks to a CAR file *)
76let blocks = [
77 (cid1, data1);
78 (cid2, data2);
79 (cid3, data3);
80] in
81Car.write ~roots:[root_cid] blocks output_channel
82
83(* Read blocks from a CAR file *)
84let (roots, blocks) = Car.read input_channel
85```
86
87## types
88
89### CID
90
91```ocaml
92type Cid.t = {
93 version: int; (* Always 1 for CIDv1 *)
94 codec: codec; (* Raw or Dcbor *)
95 digest: digest; (* SHA-256 hash *)
96 bytes: bytes; (* Serialized CID *)
97}
98
99type codec = Raw | Dcbor
100```
101
102### DAG-CBOR
103
104```ocaml
105type Dag_cbor.value =
106 | `Null
107 | `Boolean of bool
108 | `Integer of int64
109 | `Float of float
110 | `String of string
111 | `Bytes of bytes
112 | `Array of value array
113 | `Map of value String_map.t
114 | `Link of Cid.t
115 | `Tag of int * value
116```