dag.codecs package¶

Submodules¶

dag.codecs.dag_cbor module¶

DAG-CBOR codec - deterministic CBOR with IPLD CID links.

Multicodec code: 0x71

DAG-CBOR is CBOR (RFC 8949) with additional constraints:

Deterministic encoding: map keys sorted by byte length then lexicographically (RFC 7049 §3.9 canonical ordering), smallest possible integer representations, no indefinite-length items.
CID links: CIDs are encoded using CBOR tag 42 wrapping the CID bytes prefixed with a 0x00 identity multibase byte.
No additional CBOR tags are allowed (only tag 42).

Reference implementations: - https://github.com/ipld/js-dag-cbor - https://ipld.io/specs/codecs/dag-cbor/spec/

class dag.codecs.dag_cbor.DagCborCodec[source]¶

Bases: BlockCodec

DAG-CBOR codec (0x71).

Encodes IPLD data-model values into deterministic CBOR with CID links represented as CBOR tag 42.

property code: int¶: Multicodec code (e.g. 0x71).

Decode DAG-CBOR bytes into an IPLD value.

CBOR tag 42 values are converted back into CID objects.

Encode an IPLD value to DAG-CBOR bytes.

CIDs are encoded as Tag(42, 0x00 || cid_bytes). Map keys are sorted using canonical CBOR ordering.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

dag.codecs.dag_cbor.codec = <dag.codecs.dag_cbor.DagCborCodec object>¶: Module-level singleton codec instance.

Decode DAG-CBOR bytes into an IPLD value.

CBOR tag 42 values are converted back into CID objects.

Encode an IPLD value to DAG-CBOR bytes.

CIDs are encoded as Tag(42, 0x00 || cid_bytes). Map keys are sorted using canonical CBOR ordering.

dag.codecs.dag_json module¶

DAG-JSON codec - deterministic JSON with IPLD CID links.

Multicodec code: 0x0129

DAG-JSON is JSON with special representations for IPLD types that JSON cannot natively express:

CID links are encoded as {"/": "<cid-multibase-string>"}
Bytes are encoded as {"/": {"bytes": "<base64-string>"}}
Map keys are sorted lexicographically (by UTF-8 bytes).
No whitespace between tokens.

The {"/": ...} namespace is reserved: - {"/": "<string>"} → CID link - {"/": {"bytes": "..."}} → bytes value - Any other {"/": ...} is an error in strict mode.

Reference implementations: - https://github.com/ipld/js-dag-json - https://ipld.io/specs/codecs/dag-json/spec/

class dag.codecs.dag_json.DagJsonCodec[source]¶

Bases: BlockCodec

DAG-JSON codec (0x0129).

Encodes IPLD data-model values into deterministic JSON with CID links as {"/": "bafy..."} and bytes as {"/": {"bytes": "..."}}.

property code: int¶: Multicodec code (e.g. 0x71).

Decode DAG-JSON bytes into an IPLD value.

Recognizes {"/": ...} sentinel objects and converts them back to CID or bytes values.

Encode an IPLD value to DAG-JSON bytes.

CIDs → {"/": "<cid-string>"}
bytes → {"/": {"bytes": "<base64-no-pad>"}}
Map keys are sorted.
No whitespace.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

dag.codecs.dag_json.codec = <dag.codecs.dag_json.DagJsonCodec object>¶: Module-level singleton codec instance.

Decode DAG-JSON bytes into an IPLD value.

Recognizes {"/": ...} sentinel objects and converts them back to CID or bytes values.

Encode an IPLD value to DAG-JSON bytes.

CIDs → {"/": "<cid-string>"}
bytes → {"/": {"bytes": "<base64-no-pad>"}}
Map keys are sorted.
No whitespace.

dag.codecs.dag_pb module¶

DAG-PB codec - Protobuf-based Merkle DAG nodes.

Multicodec code: 0x70

DAG-PB uses Protocol Buffers for encoding. It is the codec used by legacy IPFS (UnixFS). A DAG-PB node (PBNode) consists of:

Data - optional raw bytes payload
Links - a list of PBLink entries, each containing: - Hash - a CID (as raw bytes) - Name - an optional UTF-8 string name - Tsize - an optional integer (total cumulative size)

Protobuf schema (proto2):

message PBLink {
    optional bytes  Hash  = 1;
    optional string Name  = 2;
    optional uint64 Tsize = 3;
}

message PBNode {
    optional bytes   Data  = 1;
    repeated PBLink  Links = 2;
}

Wire format field tags: - PBLink.Hash: field 1, wire type 2 (length-delimited) → tag byte 0x0a - PBLink.Name: field 2, wire type 2 (length-delimited) → tag byte 0x12 - PBLink.Tsize: field 3, wire type 0 (varint) → tag byte 0x18 - PBNode.Data: field 1, wire type 2 (length-delimited) → tag byte 0x0a - PBNode.Links: field 2, wire type 2 (length-delimited) → tag byte 0x12

Links MUST be sorted: first by Name (bytes), then by those without names. Encoding is done right-to-left to match the reference implementation.

Reference implementations: - https://github.com/ipld/js-dag-pb - https://ipld.io/specs/codecs/dag-pb/spec/

class dag.codecs.dag_pb.DagPbCodec[source]¶

Bases: BlockCodec

DAG-PB codec (0x70).

Encodes/decodes PBNode structures to/from Protocol Buffers wire format.

property code: int¶: Multicodec code (e.g. 0x71).

decode(data: bytes) → None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1[source]¶: Decode DAG-PB bytes into a dict with Data and Links keys.

encode(node: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1) → bytes[source]¶: Encode a PBNode (or equivalent dict) to DAG-PB bytes.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

class dag.codecs.dag_pb.PBLink(hash: CIDv0 | CIDv1 | None = None, name: str | None = None, tsize: int | None = None)[source]¶

Bases: object

A link within a DAG-PB node.

Attributes¶

hash:: The CID that this link points to.
name:: Optional name for the link.
tsize:: Optional total cumulative size of the target DAG.

hash: CIDv0 | CIDv1 | None = None¶

name: str | None = None¶

tsize: int | None = None¶

class dag.codecs.dag_pb.PBNode(data: bytes | None = None, links: list[~dag.codecs.dag_pb.PBLink] = <factory>)[source]¶

Bases: object

A DAG-PB node.

Attributes¶

data:: Optional raw bytes payload.
links:: List of links to other nodes.

data: bytes | None = None¶

links: list[PBLink]¶

dag.codecs.dag_pb.codec = <dag.codecs.dag_pb.DagPbCodec object>¶: Module-level singleton codec instance.

dag.codecs.dag_pb.decode(data: bytes) → None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1¶: Decode DAG-PB bytes into a dict with Data and Links keys.

dag.codecs.dag_pb.encode(node: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1) → bytes¶: Encode a PBNode (or equivalent dict) to DAG-PB bytes.

dag.codecs.raw module¶

Raw codec - identity codec for raw binary data.

Multicodec code: 0x55

The raw codec performs no transformation: encode returns the bytes as-is, and decode returns the bytes as-is. It is used when the block content is opaque binary data with no internal structure.

Reference: https://github.com/multiformats/js-multiformats

class dag.codecs.raw.RawCodec[source]¶

Bases: BlockCodec

Raw binary codec (0x55).

Passes bytes through unchanged.

property code: int¶: Multicodec code (e.g. 0x71).

Decode raw bytes (identity operation).

Returns the bytes unchanged.

Encode raw bytes (identity operation).

node must be a bytes or bytearray instance.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

dag.codecs.raw.codec = <dag.codecs.raw.RawCodec object>¶: Module-level singleton codec instance.

Decode raw bytes (identity operation).

Returns the bytes unchanged.

Encode raw bytes (identity operation).

node must be a bytes or bytearray instance.

Module contents¶

IPLD codec implementations.

This sub-package provides the built-in IPLD codecs:

dag_cbor - DAG-CBOR (0x71)
dag_json - DAG-JSON (0x0129)
dag_pb - DAG-PB (0x70)
raw - Raw (0x55)

All codecs are auto-registered when this package is imported.

class dag.codecs.DagCborCodec[source]¶

Bases: BlockCodec

DAG-CBOR codec (0x71).

Encodes IPLD data-model values into deterministic CBOR with CID links represented as CBOR tag 42.

property code: int¶: Multicodec code (e.g. 0x71).

Decode DAG-CBOR bytes into an IPLD value.

CBOR tag 42 values are converted back into CID objects.

Encode an IPLD value to DAG-CBOR bytes.

CIDs are encoded as Tag(42, 0x00 || cid_bytes). Map keys are sorted using canonical CBOR ordering.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

class dag.codecs.DagJsonCodec[source]¶

Bases: BlockCodec

DAG-JSON codec (0x0129).

Encodes IPLD data-model values into deterministic JSON with CID links as {"/": "bafy..."} and bytes as {"/": {"bytes": "..."}}.

property code: int¶: Multicodec code (e.g. 0x71).

Decode DAG-JSON bytes into an IPLD value.

Recognizes {"/": ...} sentinel objects and converts them back to CID or bytes values.

Encode an IPLD value to DAG-JSON bytes.

CIDs → {"/": "<cid-string>"}
bytes → {"/": {"bytes": "<base64-no-pad>"}}
Map keys are sorted.
No whitespace.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

class dag.codecs.DagPbCodec[source]¶

Bases: BlockCodec

DAG-PB codec (0x70).

Encodes/decodes PBNode structures to/from Protocol Buffers wire format.

property code: int¶: Multicodec code (e.g. 0x71).

decode(data: bytes) → None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1[source]¶: Decode DAG-PB bytes into a dict with Data and Links keys.

encode(node: None | bool | int | float | str | bytes | list[IPLDNode] | dict[str, IPLDNode] | CIDv0 | CIDv1) → bytes[source]¶: Encode a PBNode (or equivalent dict) to DAG-PB bytes.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

class dag.codecs.RawCodec[source]¶

Bases: BlockCodec

Raw binary codec (0x55).

Passes bytes through unchanged.

property code: int¶: Multicodec code (e.g. 0x71).

Decode raw bytes (identity operation).

Returns the bytes unchanged.

Encode raw bytes (identity operation).

node must be a bytes or bytearray instance.

property name: str¶: Human-readable codec name (e.g. 'dag-cbor').

dag.codecs package¶

Submodules¶

dag.codecs.dag_cbor module¶

dag.codecs.dag_json module¶

dag.codecs.dag_pb module¶

Attributes¶

Attributes¶

dag.codecs.raw module¶

Module contents¶

py-ipld-dag

Navigation

Related Topics