closer to nice

Author: turbocrime

README.md

@@ -1,66 +1,79 @@
-## Foundry
+# solidity-bsky-cbor
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+**solidity-bsky-cbor is a library for parsing and verifying record inclusion in atproto repositories.**
 
-Foundry consists of:
+The basic CBOR decoding is forked from [the filecoin CBOR code](https://github.com/Zondax/filecoin-solidity/blob/master/contracts/v0.8/utils/CborDecode.sol) by Zondax AG.
 
--   **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
--   **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
--   **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
--   **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+The atproto features were developed by reference the [atproto data model](https://atproto.com/specs/data-model).
 
-## Documentation
+## Usage
 
-https://book.getfoundry.sh/
+This library is designed for use with off-chain software which selects appropriate records and formats contract calldata.
 
-## Usage
+Your contract should know a trusted pubkey, and track the last seen repo revision to prevent replay.
 
-### Build
+### off-chain
 
-```shell
-$ forge build
-```
+You identify a new record of interest.
 
-### Test
+1. know the actor `did`, namespaced `collection`, and `rkey` identifying the record of interest
+1. query the appropriate PDS with `com.atproto.sync.getRecord` to obtain the proving MST
+2. parse the response `application/vnd.ipld.car` and separate:
+   - the MST node CBORs
+   - the record CBOR
+   - the unsigned commit CBOR
+   - the commit signature `r` and `s` components
 
-```shell
-$ forge test
-```
+Call your contract.
 
-### Format
+### on-chain
 
-```shell
-$ forge fmt
-```
+Your established contract is called.
 
-### Gas Snapshots
+4. knowing a previous repo revision, parse the commit with `verifyCommit`. a root CID and new revision return.
+5. knowing the record key and the root CID, parse the MST with `verifyInclusion`. a value CID returns.
+6. knowing the record content and the value CID, confirm the value CID refers to the record content.
+7. the record is proven. store the new revision.
 
-```shell
-$ forge snapshot
-```
+Your contract may now proceed to parse and act on the authenticated record.
 
-### Anvil
+### Example
 
-```shell
-$ anvil
-```
+Contract use of this library might look like this:
 
-### Deploy
+```sol
+function exampleUse(
+    bytes calldata commitCbor,
+    bytes calldata recordCbor,
+    bytes[] calldata mstCbors,
+    bytes32 sig_r,
+    bytes32 sig_s,
+    string calldata recordKey,
+) external {
+    Commit memory commit = commitCbor.verifyCommit(sig_r, sig_s, trustedSigner, lastRev);
+    Tree memory mst = mstCbors.readTree();
+    Cid valueCid = mst.verifyInclusion(commit.data, recordKey);
+    require(valueCid.isFor(recordCbor), "Key identifies a different record");
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
+    lastRev = commit.rev;
+    exampleAction(recordCbor);
+}
 ```
 
-### Cast
+## Record parsing
 
-```shell
-$ cast <subcommand>
-```
+~~A few record parsing utilities are provided for some common bluesky lexicons.~~
 
-### Help
+A single record parsing utility is provided for Bluesky posts.
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
-```
+- `app.bsky.feed.post`
+
+Others are planned.
+
+- ~~`app.bsky.feed.like`~~
+- ~~`app.bsky.feed.repost`~~
+- ~~`app.bsky.graph.block`~~
+- ~~`app.bsky.graph.follow`~~
+- ~~`app.bsky.richText.facet`~~
+
+Otherwise, you are responsible for implementing your own record parsing.

example.sol

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import "./src/CommitCbor.sol";
+import "./src/TreeCbor.sol";
+
+contract ExampleContract {
+    using {CommitCbor.verifyCommit} for bytes;
+    using {TreeCbor.readTree} for bytes[];
+    using {TreeCbor.verifyInclusion} for Tree;
+
+    string private lastRev;
+    address private trustedSigner;
+
+    constructor(string memory initRev, address initSigner) {
+        lastRev = initRev;
+        trustedSigner = initSigner;
+    }
+
+    function exampleUse(
+        bytes calldata commitCbor,
+        bytes calldata recordCbor,
+        bytes[] calldata mstCbors,
+        bytes32 sig_r,
+        bytes32 sig_s,
+        string calldata recordKey
+    ) external {
+        Commit memory commit = commitCbor.verifyCommit(sig_r, sig_s, trustedSigner, lastRev);
+        Tree memory mst = mstCbors.readTree();
+        Cid valueCid = mst.verifyInclusion(commit.data, recordKey);
+        require(valueCid.isFor(recordCbor), "Key identifies a different record");
+
+        lastRev = commit.rev;
+        exampleAction(recordCbor);
+    }
+
+    function exampleAction(bytes calldata recordCbor) internal pure {
+        /* no-op */
+    }
+}

src/AppBskyCbor.sol

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.28;
+
+import "./CidCbor.sol";
+
+struct AppBskyFeedPost {
+    string text;
+}
+
+library AppBsky {
+    using CBORDecoder for bytes;
+
+    bytes19 private constant nsidFeedPost = "app.bsky.feed.post";
+
+    function FeedPost(bytes memory cborData) internal pure returns (AppBskyFeedPost memory feedPost) {
+        uint byteIdx = 0;
+        (feedPost.text, byteIdx) = FeedPost(cborData, byteIdx);
+        require(byteIdx == cborData.length, "expected to read all bytes");
+        return feedPost;
+    }
+
+    function FeedPost(bytes memory cborData, uint byteIdx) internal pure returns (string memory feedPostText, uint) {
+        uint mapLen;
+        (mapLen, byteIdx) = cborData.readFixedMap(byteIdx);
+
+        require(mapLen == 4, "expected 4 fields in `app.bsky.feed.post` record");
+
+        bytes9 mapKey;
+        for (uint mapIdx = 0; mapIdx < mapLen; mapIdx++) {
+            (mapKey, byteIdx) = cborData.readStringBytes9(byteIdx);
+            if (
+                // text field is the content of a text post.
+                bytes5(mapKey) == "text"
+            ) {
+                (feedPostText, byteIdx) = cborData.readString(byteIdx);
+            } else if (
+                // $type field should be "app.bsky.feed.post"
+                bytes6(mapKey) == "$type"
+            ) {
+                bytes memory dollarType;
+                (dollarType, byteIdx) = cborData.readStringBytes(byteIdx);
+                require(bytes19(bytes(dollarType)) == nsidFeedPost, "unexpected record $type");
+            } else if (
+                // langs array unused
+                bytes6(mapKey) == "langs"
+            ) {
+                uint langsLength;
+                (langsLength, byteIdx) = cborData.readFixedArray(byteIdx);
+                for (uint j = 0; j < langsLength; j++) {
+                    byteIdx = cborData.skipString(byteIdx);
+                }
+            } else if (
+                // createdAt string unused
+                bytes9(mapKey) == "createdAt"
+            ) {
+                // createdAt is arbitrary user-defined data. the useful and
+                // verifiable timestamp is the commit's repo revision field
+                byteIdx = cborData.skipString(byteIdx);
+            } else {
+                revert("unexpected record key");
+            }
+        }
+
+        return (feedPostText, byteIdx);
+    }
+}

src/CidCbor.sol

@@ -1,80 +1,103 @@
-// SPDX-License-Identifier: MIT
+// SPDX-License-Identifier: Apache-2.0
 pragma solidity ^0.8.28;
 
 import "./CborDecode.sol";
 
-using {cidEq as ==, cidNeq as !=} for Cid global;
+using {cidEq as ==, cidNeq as !=, isNull, isFor} for Cid global;
 
-/**
- * we will only encounter Cid v1 dag-cbor sha256, so the entire hash is 32
- * bytes and will fit in a uint256
- */
+// we will only encounter CID v1 dag-cbor sha256, and sha256 fits a uint256.
+// some CID fields may be nullable, so the zero value identifies a 'null' CID.
 type Cid is uint256;
 
 function cidEq(Cid a, Cid b) pure returns (bool) {
+    require(Cid.unwrap(a) != 0 && Cid.unwrap(b) != 0, "Invalid CID comparison: null CID");
     return Cid.unwrap(a) == Cid.unwrap(b);
 }
 
 function cidNeq(Cid a, Cid b) pure returns (bool) {
-    return Cid.unwrap(a) != Cid.unwrap(b);
+    return !cidEq(a, b);
+}
+
+function isFor(Cid a, bytes memory b) pure returns (bool) {
+    require(Cid.unwrap(a) != 0, "Invalid CID check: null CID");
+    require(b.length != 0, "Invalid CID check: no content");
+    return Cid.unwrap(a) == uint256(sha256(b));
+}
+
+function isNull(Cid a) pure returns (bool) {
+    return Cid.unwrap(a) == 0;
 }
 
 library CidCbor {
     using CBORDecoder for bytes;
 
-    uint8 private constant TAG_CID = 42;
+    // any CIDv1 DAG-CBOR sha-256 will always have this 9-byte header
+    // ─────┬─────────
+    //  hex │ meaning
+    // ─────┼─────────
+    //   D8 │ CBOR major primitive, minor next byte
+    //   2A │ CBOR tag value 42 (CID)
+    //   58 │ CBOR major bytes, minor next byte
+    //   25 │ CBOR bytes length 37
+    //   00 │ multibase format
+    //   01 │ multiformat CID version 1
+    //   71 │ multicodec DAG-CBOR
+    //   12 │ multihash type sha-256
+    //   20 │ multihash size 32 bytes
+    // ─────┴─────────
+    bytes4 private constant cbor_tag42_bytes37 = hex"D82A5825";
+    bytes5 private constant multibase_cidv1_dagcbor_sha256 = hex"0001711220";
 
-    uint8 private constant MULTIBASE_FORMAT = 0x00;
-    uint8 private constant CID_V1 = 0x01;
-    uint8 private constant MULTICODEC_DAG_CBOR = 0x71;
-    uint8 private constant MULTIHASH_SHA_256 = 0x12;
-    uint8 private constant MULTIHASH_SIZE_32 = 0x20;
+    /**
+     * @notice Reads a CIDv1 DAG-CBOR sha-256 from CBOR encoded data at the specified byte index
+     * @dev Expects a 41-byte CID structure: 4 bytes CBOR header + 5 bytes multibase header + 32 bytes SHA-256 hash
+     *      Reverts when:
+     *      - The remaining bytes are less than the expected CID size
+     *      - The CBOR header is not tag 42 with 37-byte item
+     *      - The multibase header is not CIDv1 DAG-CBOR sha256
+     *      - The hash value is zero
+     * @param cborData The CBOR encoded byte array containing the CID
+     * @param byteIdx The starting index in the byte array to read from
+     * @return Cid The decoded CID
+     * @return uint The next byte index after the CID
+     */
+    function readCid(bytes memory cborData, uint byteIdx) internal pure returns (Cid, uint) {
+        bytes4 cborHead;
+        bytes5 multibaseHead;
+        uint256 cidSha256; // 32 bytes
 
-    function expectTagCid(bytes memory cborData, uint byteIdx) internal pure returns (uint) {
-        uint8 head = uint8(cborData[byteIdx]);
-        uint8 tagValue = uint8(cborData[byteIdx + 1]);
-        require(head == MajorTag << shiftMajor | MinorExtend1, "expected tag head with 1-byte extension");
-        require(tagValue == TAG_CID, "expected tag 42 for CID");
-        return byteIdx + 2;
-    }
+        require(byteIdx + 4 + 5 + 32 <= cborData.length, "Expected CID size is out of range");
+
+        assembly ("memory-safe") {
+            // cbor header at index
+            cborHead := mload(add(cborData, add(0x20, byteIdx)))
+            // multibase header at index + cbor header
+            multibaseHead := mload(add(cborData, add(0x20, add(4, byteIdx))))
+            // cid hash at index + cbor header + multibase header
+            cidSha256 := mload(add(cborData, add(0x20, add(9, byteIdx))))
+        }
 
-    function expect37Bytes(bytes memory cborData, uint byteIdx) internal pure returns (uint) {
-        require(
-            uint8(cborData[byteIdx]) == MajorBytes << shiftMajor | MinorExtend1,
-            "expected byte head with 1-byte extension"
-        );
-        require(uint8(cborData[byteIdx + 1]) == 37, "expected 37 bytes for CID");
-        byteIdx += 2;
-        return byteIdx;
+        require(cborHead == cbor_tag42_bytes37, "Expected CBOR tag 42 and 37-byte item");
+        require(multibaseHead == multibase_cidv1_dagcbor_sha256, "Expected multibase CIDv1 DAG-CBOR sha256");
+        require(cidSha256 != 0, "Expected non-zero sha256 hash");
+
+        return (Cid.wrap(cidSha256), byteIdx + 4 + 5 + 32);
     }
 
+    /**
+     * @notice Reads a CID that may be null from CBOR encoded data at the specified byte index
+     * @dev If a CBOR null primitive appears at the byte index, the byte index
+     *      is advanced appropriately and this function returns a 'zero' CID.
+     * @param cborData The CBOR bytes containing the CID or null
+     * @param byteIdx The starting index to read from
+     * @return Cid The decoded CID, or zero CID if null
+     * @return uint The next byte index after the CID or null value
+     */
     function readNullableCid(bytes memory cborData, uint byteIdx) internal pure returns (Cid, uint) {
         if (cborData.isNullNext(byteIdx)) {
             return (Cid.wrap(0), byteIdx + 1);
+        } else {
+            return readCid(cborData, byteIdx);
         }
-        return readCid(cborData, byteIdx);
-    }
-
-    function readCid(bytes memory cborData, uint byteIdx) internal pure returns (Cid, uint) {
-        bytes9 cidHead;
-        assembly ("memory-safe") {
-            cidHead := mload(add(cborData, add(0x20, byteIdx)))
-        }
-
-        // all cids encountered will contain this 9-byte header
-        // D8 2A cbor tag(42) cid
-        // 58 25 cbor bytes(37) total length
-        // 00 multibase format
-        // 01 CID version
-        // 71 multicodec DAG-CBOR
-        // 12 multihash sha-256
-        // 20 hash size 32 bytes
-        require(cidHead == hex"D82A58250001711220", "expected CIDv1 dag-cbor sha256 header sequence");
-        byteIdx += 9;
-        uint256 cidHash;
-        assembly ("memory-safe") {
-            cidHash := mload(add(cborData, add(0x20, byteIdx)))
-        }
-        return (Cid.wrap(cidHash), byteIdx + 32);
     }
 }