> ## 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 — operaciones core de AT Protocol

> Módulo Core de Laravel Bluesky. Explica la codificación CBOR, la verificación de contenido con CID, las operaciones con archivos CAR y la generación de claves de record cronológicas con TID.

<Warning>
  Core es una implementación interna avanzada. No es necesaria para las operaciones habituales como publicar, obtener feeds o notificaciones. Consúltala cuando manipules directamente las estructuras de datos del AT Protocol.
</Warning>

## Visión general del modelo de datos de AT Protocol

El repositorio de AT Protocol adopta una estructura de datos direccionable por contenido. Para almacenar, transferir y verificar los datos se emplean los siguientes elementos.

```mermaid theme={null}
graph TD
    A["Datos PHP (array)"] --> B["Codificación CBOR<br>(DAG-CBOR)"]
    B --> C["Hash SHA-256"]
    C --> D["CID<br>(Content Identifier)"]
    D --> E["Archivo CAR<br>(conjunto de bloques)"]
    E --> F["Repositorio<br>(Merkle Search Tree)"]
```

| Clase    | Rol                                                           |
| -------- | ------------------------------------------------------------- |
| `CBOR`   | Serialización binaria                                         |
| `CID`    | Direccionamiento por contenido (identificador basado en hash) |
| `CAR`    | Lectura/escritura del archivo del repositorio                 |
| `TID`    | Clave de record cronológica                                   |
| `Varint` | Codificación de enteros de longitud variable (interno)        |

***

## CBOR

La clase `CBOR` ofrece codificación y decodificación en el formato [DAG-CBOR](https://ipld.io/specs/codecs/dag-cbor/spec/) que adopta AT Protocol. Como extensión de CBOR estándar, admite enlaces CID (tag 42).

### Codificar

```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); // cadena binaria
```

### Decodificar

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

// Decodifica un único elemento
$data = CBOR::decode($bytes);

// Decodifica el primer elemento del stream y devuelve el resto
[$item, $remainder] = CBOR::decodeFirst($bytes);

// Decodifica todos los elementos del stream
$items = CBOR::decodeAll($bytes);
```

### Uso

Si quieres calcular o verificar manualmente el CID de una publicación, necesitas la codificación CBOR (ver también la [página verify](/es/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)

El CID es un identificador autodescriptivo basado en el hash de los datos. En AT Protocol se envuelve el hash SHA-256 con multihash y, adicionalmente, se codifica con multicodec y multibase.

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

### CIDv0 y CIDv1

| Versión | Codificación | Prefijo   | Uso                            |
| ------- | ------------ | --------- | ------------------------------ |
| v0      | base58btc    | `Qm...`   | Especificación antigua (blobs) |
| v1      | base32       | `bafy...` | Especificación nueva (records) |

### API principal

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

// Genera un CID a partir de los datos
$cid = CID::encode($data, CID::DAG_CBOR); // para records
$cid = CID::encode($data, CID::RAW);      // binario (imágenes, etc.)

// Verifica un CID
$bool = CID::verify($data, $cid, CID::DAG_CBOR);
$bool = CID::verify($file, $cid, CID::RAW);

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

// Comprueba la versión del CID
$version = CID::version($cid); // 0 o 1

// Conversión a representación de bytes
$bytes = CID::decodeBytes($cid);
$cid   = CID::encodeBytes($bytes);
```

***

## CAR (Content Addressable aRchive)

El archivo CAR es un formato binario que almacena el repositorio del AT Protocol como una secuencia de bloques. Los datos obtenidos con `com.atproto.sync.getRepo` vienen en este formato.

```mermaid theme={null}
graph TD
    A["Archivo CAR"] --> B["Cabecera<br>(root CID)"]
    A --> C["Secuencia de bloques"]
    C --> D["Signed Commit<br>(firma + prev CID)"]
    C --> E["Nodos MST"]
    C --> F["Records (CBOR)"]
```

### Decodificar

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

// Decodifica todo el archivo CAR (raíz y todos los bloques)
['roots' => $roots, 'blocks' => $blocks] = CAR::decode($carData);

// Obtener solo los root CID
$roots = CAR::decodeRoots($carData);

// Iterar por bloques
foreach (CAR::blockIterator($carData) as [$cid, $block]) {
    // $cid: cadena CID, $block: datos binarios
}

// Obtener como mapa de records
foreach (CAR::blockMap($carData) as $key => $record) {
    // $key: clave del record, $record: array decodificado
}
```

### Verificación del Signed Commit

Para comprobar que el archivo CAR pertenece a esa persona usuaria, verifica la firma del Signed Commit con la clave pública del 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);
```

Ejemplo de implementación: [DownloadRepoCommand](https://github.com/invokable/laravel-bluesky/blob/main/src/Console/DownloadRepoCommand.php)

***

## TID (Timestamp Identifier)

El TID es un ID cronológico que se usa como clave de record en AT Protocol. Combina una marca temporal en microsegundos con un ID de reloj y se codifica en base32 como una cadena de 13 caracteres.

```
Ejemplo: 3jujm55ngfc24
```

### Generación y conversión

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

// Genera el siguiente TID
$tid = TID::next();
echo $tid->toString(); // Cadena tipo "3jujm55ngfc24"

// Crea un TID desde una cadena
$tid = TID::fromStr('3jujm55ngfc24');

// Crea desde marca temporal (microsegundos) e ID de reloj
$tid = TID::fromTime(microtime(true) * 1000000, 0);
```

### Estructura del TID

```mermaid theme={null}
graph LR
    A["Entero de 63 bits"] --> B["53 bits: marca temporal<br>(microsegundos)"]
    A --> C["10 bits: ID de reloj"]
    B --> D["Codificación base32<br>(13 caracteres)"]
    C --> D
```

Con `TID::s32encode()` y `TID::s32decode()` puedes convertir entre entero y cadena.

***

## Varint (entero de longitud variable)

`Varint` es una utilidad interna que se usa en el parsing binario de CAR / CBOR. Normalmente no se utiliza directamente.

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

// Codifica un entero
$bytes = Varint::encode(1234);

// Decodifica desde un stream (devuelve valor y bytes consumidos)
[$value, $bytesRead] = Varint::decodeStream($stream);
```

***

## Sobre el mock de las funciones Core

Las funciones Core (CBOR/CID/CAR/TID) no realizan accesos externos, por lo que no es necesario mockearlas en las pruebas.

```php theme={null}
// Se pueden usar directamente en las pruebas
$bytes = CBOR::encode(['text' => 'Hello']);
$cid   = CID::encode($bytes, CID::DAG_CBOR);
$bool  = CID::verify($bytes, $cid);
```

***

## Enlaces de referencia

* [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

- [Referencia de API - VOICEVOX Core for PHP](/es/packages/voicevox-core-php/api.md)
- [Paquete core y drivers personalizados - Feedable](/es/packages/feedable/core.md)
- [Service providers diferidos](/es/advanced/deferred-provider.md)
- [Core Versions](/es/packages/laravel-voicevox/engine-api/other/core-versions.md)
- [Crypto — criptografía de AT Protocol](/es/packages/laravel-bluesky/crypto.md)