# DAG house glossary

Early draft of what will be a user-facing glossary of terms used throughout the product & docs.

Still has lots of missing definitions; we're mostly just collecting terms at this stage.

Please add terms that you've seen people get confused by!

### General

##### IPFS

The InterPlanetary FileSystem is a system for organizing, locating, and transmitting data using cryptographic hashes to identify each piece of content. There are many IPFS implementations, which work together to form a public network (as well as specialized private networks).

web3.storage makes all uploaded content available to the IPFS network via [Bitswap](#Bitswap), as well as via HTTP through [Gateways](#Gateways).

##### Elastic IPFS (E-IPFS)

A "cloud-native" IPFS implementation developed by DAG House at Protocol Labs. Content is stored on commodity cloud storage (e.g. Amazon S3, Cloudflare R2) in [CAR](#CAR-content-archive) files, along with indexes that allow efficient location and retrieval of data within the CARs.

Elastic IPFS interoperates with the public IPFS network by making content available via [Bitswap](#Bitswap), as well as via [freeway](https://github.com/web3-storage/freeway), a specialized [gateway](#Gateways) that serves content directly from cloud storage.

##### Peers & peering

##### Bitswap
A protocol used by [IPFS](#IPFS) to distribute [blocks](#Block) of data to and from the [peers](#Peers-peering) that make up the IPFS network. Used by [Elastic IPFS](#Elastic-IPFS-E-IPFS) to communciate with the wider IPFS network.

##### Block

A chunk of binary data that can be identified by [CID](#cid). Often part of a larger [DAG](#dag) consisting of multiple blocks.

##### CID

A Content IDentifier consisting of a cryptographic hash of the data it identifies, as well as a few bytes of metadata indicating what format the content is expected to be in. See [the IPFS docs](https://docs.ipfs.tech/concepts/content-addressing/) for more details.

##### CAR (content archive)

A collection of data [blocks](#Block) in a format that's optimized for storage and transmission by protocols that aren't "IPFS native" (e.g. HTTP). Like a [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) for content-addressed data. Used extensively by w3up protocols, although most users shoudn't be exposed to them directly for the most common operations.

##### DAG

A Directed Acyclic Graph (DAG) is a data structure that represents a collection of linked objects ("nodes"), where the links between nodes ("edges") have certain properties. For example, you can't have "cycles" or loops in the graph, where following a set of edges brings you back to the node you started from.

IPFS encodes files and directories into DAGs comprised of [block](#Block)s of data, where each block can optionally link to other blocks using its [CID](#CID).

Most DAGs will have a single "root" node which represents the "top" of the graph. By starting at the root node and traversing the links, you can find all the blocks that make up the DAG.

##### DAG House

The team at Protocol Labs that develops and maintains the web3.storage platform, [Elastic IPFS](#Elastic-IPFS-E-IPFS), and other supporting technologies like [ucanto](#ucanto). We build houses for your [DAGs](#DAG).

##### Data CID

A [CID](#CID) that resolves to some user-provided data item. Use in preference to just "CID" in contexts where multiple types of CID are in play, e.g. when talking about [upload](#Upload)s, which link a data CID to one or more [CAR](#CAR-content-archive) CIDs.

##### DHT

A Distributed Hash Table allows many [peers](#Peers-amp-peering) to locate each other and coordinate to provide services. IPFS uses a DHT to advertise content to the network, making it discoverable to all peers who query the DHT. The DHT does not contain the full content - instead a small "provider record" contains addresses of peers who will serve the content on request (e.g. via [Bitswap](#Bitswap)).

Content stored with web3.storage is discoverable via the public IPFS DHT.

##### DID

A Decentralized Identity Document that provides identity information about some aspect of the system. Either contains a public key, or can be resolved to a public key via some means (e.g. https request, etc.)

Used extensively throughout w3up protocols.
Some things that are identified by DID:
- [Agents](#Agent)
- [Spaces](#Space)
- [Services](#Services)
- each service has a "principal" identity that represents the service itself

##### Gateways

Gateways allow people to request content from IPFS using HTTP, and are currently one of the primary ways people interact with IPFS via the web.

DAG House runs several gateways:

- [freeway](https://github.com/web3-storage/freeway), which serves content that was uploaded to web3.storage directly from [Elastic IPFS](#Elastic-IPFS-E-IPFS). This is usually the fastest gateway for things that were stored through us.
- w3s.link and nftstorage.link
- acts as a proxy that "races" several public gateways and returns the fastest result
- freeway is included in the race, so content stored with web3.storage is extra fast

##### IPLD

InterPlanetary Linked Data is a collection of data formats that can be linked together by [CID](#CID).

[UnixFS](#UnixFS) is an IPLD data format, but IPLD also supports JSON, CBOR, and other encodings for structured data that do not need the "file-like" metadata included in UnixFS.

##### UnixFS

A data format by IPFS to encode files and directories into a [DAG](#DAG) structure. When preparing data for IPFS, the UnixFS encoder will chunk files into [blocks](#Block) that are linked by [CID](#CID).

UnixFS is used by IPFS on all operating systems, including Windows. The name indicates that the format supports some common metadata used on Unix platforms, for example, symbolic links and modification time.

##### UCAN

Lots of related terms here that we might want to group together:
###### capability
###### proof
###### issuer
###### audience
###### delegation

#### ucanto

A remote proceedure call (RPC) framework based on [UCAN](#UCAN)s. Used by many w3up services. See [the ucanto README](https://github.com/web3-storage/ucanto) for more details.

### DAG House nomenclature

Common words that we use in very specific ways.

##### Agent

A software entity that controls private a signing key and can invoke capabilities on behalf of a user (or another Agent).

Agents are used to invoke capabilities provided by the w3up service layer, using the [ucanto](https://github.com/web3-storage/ucanto) RPC framework. Agents are created locally on an end-user's device, and users are encouraged to create new Agents for each device (or browser) that they want to use, rather than sharing Agent keys between devices.

##### Space

###### Upload

An "upload" in the context of w3up is a record of which [CAR](#CAR-content-archive) files contain the content [blocks](#block) for a particular [data CID](#Data-CID).

Uploads can be split among many CAR files, and it's also possible for one CAR to contain several uploads.

### Services

#### uploads service
Provides [CAR](#CAR-content-archive) storage capabilities and allows users to register [uploads](#Upload).

Implementation lives at https://github.com/web3-storage/upload-api/

#### access service

### Libraries and frameworks

##### ucanto

A framework for Remote Procedure Calls (RPC) based on [UCAN](#UCAN)s. Several w3up services are implemented using ucanto, including the [uploads service](#uploads-service) and [access service](#access-service).

##### w3up-client

Main client SDK for using w3up from JavaScript. Wraps the [access-client](#access-client) and [upload-client](#upload-client) and provides a simpler unified API.

##### w3ui

A collection of user interface components for using w3up, supporting several frontend UI frameworks.

##### access-client

A [ucanto](#ucanto) client for the "access" service, used internally by [w3up-client](#w3up-client).

##### upload-client

A [ucanto](#ucanto) client for the "uploads" service, used internally by [w3up-client](#w3up-client)