An AT Protocol application has to speak several formats before it can post a single message: records are DAG-CBOR, addressed by CIDs, stored in a Merkle Search Tree and exported as CAR files, and every call to a server goes over XRPC with an authenticated session. The record types themselves are published as Lexicon schemas.

Each of those formats has one job. CBOR is a binary encoding of JSON-like values (RFC 8949), and DAG-CBOR its deterministic subset, in which a link to another block is a tagged CID. A CID (content identifier) names a block by the hash of its bytes, prefixed with codes for the hash function and the encoding. A Merkle Search Tree is a search tree whose shape is fixed by the keys themselves (a key's level is the number of leading zero bits of its hash), so two repositories holding the same records have the same tree and the same root hash; each node is hashed as in a Merkle tree. A CAR file is a header naming root CIDs followed by the blocks, each with its CID. XRPC is the protocol's remote-call convention: an HTTP GET for a query or a POST for a procedure at /xrpc/<method id>, with JSON bodies whose types the Lexicon schemas give.

This repository implements those layers in OCaml, generates typed OCaml codecs from the Lexicon schemas with hermest, and uses them in three small clients: bsky for Bluesky, tangled for the Tangled git forge and standard-site for Standard.site publications.

Status #

The libraries work well enough for personal use and are not complete. The clients cover a few commands each: bsky only posts, with links, images and hashtags. There is no Personal Data Server (PDS) here, the server that hosts a user's repository of records and signing key, answers XRPC calls on the user's behalf and publishes the repository's changes for the rest of the network to read; futur.blue/pegasus has a more complete one. Part of the code, including the RPC code generation and the MST, comes from Pegasus, and those files keep their MPL licence.

Installation #

Install with opam:

$ opam install atp bsky tangled standard-site

If opam cannot find the packages, they have probably not reached the public opam-repository yet. Add the overlay repository, then install them:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install atp bsky tangled standard-site

The upstream aoah overlay can also be used:

$ opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git
$ opam install atp bsky tangled standard-site

Or pin directly from git:

$ opam pin add -y https://tangled.org/@anil.recoil.org/ocaml-atp.git

Packages #

Core libraries #

Package	Description
`atp`	CIDs, DAG-CBOR, the Merkle Search Tree, CAR files and identity resolution
`atp-xrpc`	XRPC client for AT Protocol PDS communication
`atp-xrpc-server`	XRPC HTTP server for AT Protocol
`xrpc-auth`	Login, sessions and profiles for command-line applications

Code generation #

Package	Description
`hermest`	Lexicon code generator for OCaml
`hermest-cli`	CLI for the hermest generator

Generated lexicon libraries #

Package	Description
`atp-lexicon-atproto`	`com.atproto.*` types
`atp-lexicon-bsky`	`app.bsky.*` types (Bluesky)
`atp-lexicon-tangled`	`sh.tangled.*` types
`atp-lexicon-standard-site`	`site.standard.*` types

Applications #

Package	Description
`bsky`	A command-line tool that posts to Bluesky
`tangled`	Client library and CLI for the Tangled git forge
`standard-site`	Client library and CLI for Standard.site publications and documents

Requirements #

OCaml >= 5.1
Dune >= 3.21

Usage #

The three clients share their login commands, under auth, and keep one session per profile in their XDG config directory.

Bluesky #

$ # Log in (the session is stored under ~/.config/bsky/)
$ bsky auth login alice.bsky.social

$ # Post a message
$ bsky post "Hello from OCaml!"

$ # Post with an image and a hashtag
$ bsky post "Look at this" --image photo.jpg --image-alt "A photo" --tag OCaml

Tangled #

$ # Log in
$ tangled auth login alice.bsky.social

$ # List repositories
$ tangled repo list

Standard.site #

$ # Log in
$ standard-site auth login alice.bsky.social

$ # List your documents
$ standard-site document list

Building from source #

$ git clone https://tangled.org/@anil.recoil.org/ocaml-atp.git
$ cd ocaml-atp
$ opam install . --deps-only
$ dune build

Licence #

ISC, except for the files taken from Pegasus, which are under the MPL.

Clone this repository

ocaml-atp #