You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This library does not provide tools for writing CBOR.
6
+
7
+
This project was initially forked from [filecoin's CborDecode.sol](https://github.com/Zondax/filecoin-solidity/blob/master/contracts/v0.8/utils/CborDecode.sol) by Zondax AG.
Most methods accept parameters `bytes` of CBOR data and `uint32` index, and return an updated index (and one or more values if appropriate). Since the data parameter is always first, you may sugar calls via `using` directive.
19
+
20
+
CBOR natively supports values up to `uint64`, so the typical values returned are `uint64`. Some methods return other types.
21
+
22
+
23
+
Deserialization methods are a capitalized name of the type like `UInt`, `NInt`, `Text`, `Map`, and so on for every CBOR type. These return a value of the equivalent solidity type when possible.
24
+
25
+
When specific format constraints exist, some optimized method variants are available, such as `String1` when the next should be a 1-byte string.
26
+
27
+
You can peek at the type of the next item with `isBytes` and so on.
28
+
29
+
The caller is responsible for handling the index and using it to index the appropriate data. No 'cursor' metaphor is provided, but the example below demonstrates how a caller may define and use a cursor for convenience.
30
+
31
+
32
+
```solidity
33
+
using ReadCbor for bytes;
34
+
35
+
bytes constant someBytes = hex"84616103616102";
36
+
37
+
struct Cursor {
38
+
bytes b;
39
+
uint32 i;
40
+
}
41
+
42
+
function example() pure {
43
+
Cursor memory c = Cursor(someBytes, 0);
44
+
uint32 len;
45
+
46
+
(c.i, len) = c.b.Array(c.i);
47
+
48
+
assert(len == 4);
49
+
50
+
string[] memory arrayStrs = new string[](len / 2);
51
+
uint64[] memory arrayNums = new uint64[](len / 2);
52
+
53
+
// CBOR arrays may contain items of any type.
54
+
for (uint32 arrayIdx = 0; arrayIdx < len; arrayIdx++) {
55
+
if (c.b.isString(c.i)) {
56
+
(c.i, arrayStrs[arrayIdx / 2]) = c.b.String(c.i);
57
+
} else if (c.b.isUInt(c.i)) {
58
+
(c.i, arrayNums[arrayIdx / 2]) = c.b.UInt(c.i);
59
+
}
60
+
}
61
+
62
+
c.b.requireComplete(c.i);
63
+
}
64
+
```
65
+
66
+
## Limitations
67
+
68
+
The CBOR format is very flexible and supports more types than solidity.
69
+
70
+
The caller is responsible for structure navigation and value interpretation.
71
+
72
+
### Tags
73
+
74
+
Tags must be parsed explicitly. The `Tag` method will simply return the tag value, or may be paramaterized to require a specific tag value.
75
+
76
+
### Primitives `null` and `undefined`
77
+
78
+
Solidity can't represent primitive values `null` and `undefined`.
79
+
80
+
The methods `Null` and `Undefined` will advance the index past a required value.
81
+
82
+
The methods `isNull` and `isUndefined` may be used to peek without advancing the index.
83
+
84
+
### Indefinite Length
85
+
86
+
Sequence and collection items of indefinite length are not supported.
87
+
88
+
### Collection Items
89
+
90
+
The `Array` and `Map` methods don't return fully-parsed collections, but simply return the collection size and advance the index to the first item.
91
+
92
+
Collection decoding can be quite complex, and CBOR collection types are more flexible than Solidity collection types. Since efficiency is critical in contract execution, and structures will vary widely, implementation is left up to the caller.
93
+
94
+
## Tag-specific parsers
95
+
96
+
All tagged items are valid CBOR and may be parsed manually, but [RFC 8949](https://www.rfc-editor.org/rfc/rfc8949) specifically mentions [stringref](https://cbor.schmorp.de/stringref) and [sharedref](https://cbor.schmorp.de/value-sharing) as tags which may require specialized support.
97
+
98
+
Some convenient specialized item parsers are provided in the `tags` directory.
99
+
100
+
### Tags 2 and 3: `ReadBignum`
101
+
102
+
Parses arbitrarily sized integers represented in CBOR as bytes, and returns the integer value.
103
+
104
+
Limited to `type(uint256).max` for tag 2 (positive) and `type(int256).min` for tag 3 (negative).
105
+
106
+
### Tag 42: `ReadCid`
107
+
108
+
Limited to the CID types appearing in atproto CBOR, specifically:
0 commit comments