> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Core — AT Protocol-kernbewerkingen

> De Core-module van Laravel Bluesky. Uitleg over CBOR-encoding, inhoudsverificatie met CID, werken met CAR-bestanden en het genereren van chronologische recordsleutels met TID.

<Warning>
  Core is een geavanceerde interne implementatie. Voor gewone taken zoals posten, feeds ophalen en notificaties heb je deze niet nodig. Raadpleeg dit onderdeel als je rechtstreeks met de datastructuren van het AT Protocol wilt werken.
</Warning>

## Overzicht van het AT Protocol-datamodel

Repositories in het AT Protocol gebruiken een content-addressable datastructuur. Voor het opslaan, overdragen en verifiëren van data worden de volgende elementen gebruikt.

```mermaid theme={null}
graph TD
    A["PHP-data (array)"] --> B["CBOR-encoding<br>(DAG-CBOR)"]
    B --> C["SHA-256-hash"]
    C --> D["CID<br>(Content Identifier)"]
    D --> E["CAR-bestand<br>(verzameling blokken)"]
    E --> F["Repository<br>(Merkle Search Tree)"]
```

| Klasse   | Rol                                                 |
| -------- | --------------------------------------------------- |
| `CBOR`   | Binaire serialisatie                                |
| `CID`    | Content-adres (hash-identifier)                     |
| `CAR`    | Lezen en schrijven van repository-archieven         |
| `TID`    | Chronologische recordsleutels                       |
| `Varint` | Encoding van integers met variabele lengte (intern) |

***

## CBOR

De `CBOR`-klasse biedt encoding en decoding in het [DAG-CBOR](https://ipld.io/specs/codecs/dag-cbor/spec/)-formaat dat het AT Protocol gebruikt. Als uitbreiding op standaard CBOR worden CID-links (tag 42) ondersteund.

### Encoden

```php theme={null}
use Revolution\Bluesky\Core\CBOR;

$record = [
    '$type'     => 'app.bsky.feed.post',
    'text'      => 'Hello, Bluesky!',
    'createdAt' => '2025-01-01T00:00:00.000Z',
];

$bytes = CBOR::encode($record); // binaire string
```

### Decoden

```php theme={null}
use Revolution\Bluesky\Core\CBOR;

// Een enkel item decoden
$data = CBOR::decode($bytes);

// Het eerste item van een stream decoden en de rest teruggeven
[$item, $remainder] = CBOR::decodeFirst($bytes);

// Alle items van een stream decoden
$items = CBOR::decodeAll($bytes);
```

### Gebruik

Als je de CID van een post handmatig wilt berekenen of verifiëren, heb je CBOR-encoding nodig (zie ook de [verify-pagina](/nl/packages/laravel-bluesky/verify)).

```php theme={null}
use Revolution\Bluesky\Core\CBOR;
use Revolution\Bluesky\Core\CID;

$record = data_get($block, 'value');
$cbor   = CBOR::encode($record);
$bool   = CID::verify($cbor, data_get($block, 'cid'));
```

***

## CID (Content Identifier)

Een CID is een zelfbeschrijvende identifier op basis van de hash van data. In het AT Protocol wordt een SHA-256-hash verpakt in een multihash en vervolgens geëncodeerd met multicodec en multibase.

```mermaid theme={null}
graph LR
    A["Data (CBOR/Raw)"] --> B["SHA-256"]
    B --> C["multihash"]
    C --> D["multicodec<br>(dag-cbor / raw)"]
    D --> E["CIDv1<br>(base32 / base58btc)"]
```

### CIDv0 en CIDv1

| Versie | Encoding  | Beginteken | Gebruik                       |
| ------ | --------- | ---------- | ----------------------------- |
| v0     | base58btc | `Qm...`    | Oude specificatie (blobs)     |
| v1     | base32    | `bafy...`  | Nieuwe specificatie (records) |

### Belangrijkste API

```php theme={null}
use Revolution\Bluesky\Core\CID;

// Een CID genereren uit data
$cid = CID::encode($data, CID::DAG_CBOR); // voor records
$cid = CID::encode($data, CID::RAW);      // binair (zoals afbeeldingen)

// Een CID verifiëren
$bool = CID::verify($data, $cid, CID::DAG_CBOR);
$bool = CID::verify($file, $cid, CID::RAW);

// Een CID parsen
$decoded = CID::decode($cid); // ['version', 'codec', 'hash']

// De versie van een CID controleren
$version = CID::version($cid); // 0 or 1

// Conversie naar byte-representatie
$bytes = CID::decodeBytes($cid);
$cid   = CID::encodeBytes($bytes);
```

***

## CAR (Content Addressable aRchive)

Een CAR-bestand is een binair formaat dat een AT Protocol-repository opslaat als een reeks blokken. Data die je ophaalt met `com.atproto.sync.getRepo` heeft dit formaat.

```mermaid theme={null}
graph TD
    A["CAR-bestand"] --> B["Header<br>(root-CID)"]
    A --> C["Blokkenreeks"]
    C --> D["Signed Commit<br>(handtekening + prev-CID)"]
    C --> E["MST-nodes"]
    C --> F["Records (CBOR)"]
```

### Decoden

```php theme={null}
use Revolution\Bluesky\Core\CAR;

// Het hele CAR-bestand decoden (roots en alle blokken)
['roots' => $roots, 'blocks' => $blocks] = CAR::decode($carData);

// Alleen de root-CID's ophalen
$roots = CAR::decodeRoots($carData);

// Over de blokken itereren
foreach (CAR::blockIterator($carData) as [$cid, $block]) {
    // $cid: CID-string, $block: binaire data
}

// Ophalen als recordmap
foreach (CAR::blockMap($carData) as $key => $record) {
    // $key: recordsleutel, $record: gedecodeerde array
}
```

### Signed Commits verifiëren

Om te controleren of een CAR-bestand echt van een bepaalde gebruiker is, verifieer je de handtekening van de Signed Commit met de publieke sleutel uit het DID Document.

```php theme={null}
use Revolution\Bluesky\Core\CAR;
use Revolution\Bluesky\Crypto\DidKey;
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Support\DidDocument;

$did = 'did:plc:***';

$didDoc    = DidDocument::make(Bluesky::identity()->resolveDID($did)->json());
$publicKey = DidKey::parse($didDoc->publicKey());

$signed    = CAR::signedCommit($carData);
$bool      = CAR::verifySignedCommit($signed, $publicKey);
```

Voorbeeldimplementatie: [DownloadRepoCommand](https://github.com/invokable/laravel-bluesky/blob/main/src/Console/DownloadRepoCommand.php)

***

## TID (Timestamp Identifier)

Een TID is een chronologisch ID dat wordt gebruikt als recordsleutel in het AT Protocol. Het combineert een timestamp in microseconden met een clock-ID en encodeert dit in base32 tot een string van 13 tekens.

```
Voorbeeld: 3jujm55ngfc24
```

### Genereren en converteren

```php theme={null}
use Revolution\Bluesky\Core\TID;

// Het volgende TID genereren
$tid = TID::next();
echo $tid->toString(); // een string zoals "3jujm55ngfc24"

// Een TID maken uit een string
$tid = TID::fromStr('3jujm55ngfc24');

// Maken uit een timestamp (microseconden) en een clock-ID
$tid = TID::fromTime(microtime(true) * 1000000, 0);
```

### De structuur van een TID

```mermaid theme={null}
graph LR
    A["63-bits integer"] --> B["53 bits: timestamp<br>(microseconden)"]
    A --> C["10 bits: clock-ID"]
    B --> D["base32-encoding<br>(13 tekens)"]
    C --> D
```

Met `TID::s32encode()` en `TID::s32decode()` kun je heen en weer converteren tussen integers en strings.

***

## Varint (integer met variabele lengte)

`Varint` is een interne utility die wordt gebruikt bij het binair parsen van CAR/CBOR. Normaal gebruik je deze niet rechtstreeks.

```php theme={null}
use Revolution\Bluesky\Core\Varint;

// Een integer encoden
$bytes = Varint::encode(1234);

// Decoden uit een stream (geeft de waarde en het aantal gelezen bytes terug)
[$value, $bytesRead] = Varint::decodeStream($stream);
```

***

## Over het mocken van Core-functionaliteit

De Core-functionaliteit (CBOR/CID/CAR/TID) doet geen externe aanroepen, dus je hoeft er in tests niets voor te mocken.

```php theme={null}
// Ook in tests direct te gebruiken
$bytes = CBOR::encode(['text' => 'Hello']);
$cid   = CID::encode($bytes, CID::DAG_CBOR);
$bool  = CID::verify($bytes, $cid);
```

***

## Referenties

* [AT Protocol: Repository spec](https://atproto.com/specs/repository)
* [AT Protocol: CID spec](https://atproto.com/specs/data-model#cid-formats)
* [IPLD: DAG-CBOR spec](https://ipld.io/specs/codecs/dag-cbor/spec/)

<Info>
  Source: [src/Core/](https://github.com/invokable/laravel-bluesky/tree/main/src/Core)
</Info>


## Related topics

- [Testen](/nl/packages/laravel-bluesky/testing.md)
- [Crypto — AT Protocol-cryptografie](/nl/packages/laravel-bluesky/crypto.md)
- [VOICEVOX Core for PHP](/nl/packages/voicevox-core-php/index.md)
- [Gebruik - VOICEVOX Core for PHP](/nl/packages/voicevox-core-php/usage.md)
- [API-referentie - VOICEVOX Core for PHP](/nl/packages/voicevox-core-php/api.md)