├── .github └── workflows │ └── build-deploy-docs.yml ├── .gitignore ├── LICENSE ├── README.md ├── babel.config.js ├── docs ├── composedb │ ├── core-concepts.mdx │ ├── create-ceramic-app.mdx │ ├── create-your-composite.mdx │ ├── examples │ │ ├── index.mdx │ │ ├── taco-access-control.mdx │ │ ├── tutorials-and-examples.mdx │ │ └── verifiable-credentials.mdx │ ├── getting-started.mdx │ ├── guides │ │ ├── composedb-client │ │ │ ├── authenticate-users.mdx │ │ │ ├── composedb-client.mdx │ │ │ ├── javascript-client.mdx │ │ │ ├── user-sessions.mdx │ │ │ ├── using-apollo.mdx │ │ │ └── using-relay.mdx │ │ ├── composedb-server │ │ │ ├── access-mainnet.mdx │ │ │ ├── composedb-server.mdx │ │ │ ├── data-storage.mdx │ │ │ ├── running-in-the-cloud.mdx │ │ │ ├── running-locally.mdx │ │ │ └── server-configurations.mdx │ │ ├── data-interactions │ │ │ ├── data-interactions.mdx │ │ │ ├── mutations.mdx │ │ │ └── queries.mdx │ │ ├── data-modeling │ │ │ ├── composites.mdx │ │ │ ├── data-modeling.mdx │ │ │ ├── introduction-to-modeling.mdx │ │ │ ├── model-catalog.mdx │ │ │ ├── relations-combine-items.mdx │ │ │ ├── relations-container-of-items.mdx │ │ │ ├── relations.mdx │ │ │ ├── schemas.mdx │ │ │ └── writing-models.mdx │ │ └── index.mdx │ ├── interact-with-data.mdx │ ├── introduction.mdx │ ├── next-steps.mdx │ └── set-up-your-environment.mdx ├── dids │ ├── authorization.md │ ├── configuration.md │ ├── guides │ │ ├── add-chain-support.md │ │ ├── concepts-overview.md │ │ ├── upgrading-did-session.md │ │ └── using-with-composedb-client.md │ ├── installation.mdx │ ├── introduction.md │ └── managing-sessions.md ├── ecosystem │ └── community.mdx ├── introduction │ ├── ceramic-roadmap.md │ ├── composedb-overview.md │ ├── did-overview.md │ ├── intro.md │ ├── protocol-overview.md │ ├── technical-reqs.md │ └── why-ceramic.md ├── protocol │ ├── ceramic-one │ │ ├── README.mdx │ │ ├── concepts.mdx │ │ └── usage │ │ │ ├── consume.mdx │ │ │ ├── installation.mdx │ │ │ ├── produce.mdx │ │ │ └── query.mdx │ └── js-ceramic │ │ ├── accounts │ │ ├── accounts-index.md │ │ ├── authorizations.md │ │ ├── decentralized-identifiers.md │ │ └── object-capabilities.md │ │ ├── api.md │ │ ├── guides │ │ ├── ceramic-clients │ │ │ ├── authentication │ │ │ │ ├── did-jsonrpc.md │ │ │ │ ├── did-session.md │ │ │ │ └── key-did.md │ │ │ ├── clients-overview.md │ │ │ ├── javascript-clients │ │ │ │ ├── ceramic-http.md │ │ │ │ ├── http-api.md │ │ │ │ ├── pinning.md │ │ │ │ └── queries.md │ │ │ └── stream-api │ │ │ │ └── caip10-link.md │ │ ├── ceramic-nodes │ │ │ ├── running-cloud.md │ │ │ └── running-locally.md │ │ └── guides-index.md │ │ ├── networking │ │ ├── data-feed-api.md │ │ ├── event-fetching.md │ │ ├── networking-index.md │ │ ├── networks.md │ │ ├── tip-gossip.md │ │ └── tip-queries.md │ │ ├── nodes │ │ ├── overview.md │ │ └── running-a-node.md │ │ ├── overview.md │ │ └── streams │ │ ├── consensus.md │ │ ├── event-log.md │ │ ├── lifecycle.md │ │ ├── streams-index.md │ │ └── uri-scheme.md └── wheel │ └── wheel-reference.mdx ├── docusaurus.config.ts ├── package.json ├── pnpm-lock.yaml ├── sidebars.ts ├── src ├── components │ └── homepage │ │ ├── community.js │ │ ├── get-started.js │ │ ├── homeNavBoxes.module.css │ │ ├── start-building.js │ │ └── tools-utilities.js ├── css │ ├── custom.css │ └── graphiql.min.css ├── fonts │ └── Inter │ │ ├── Inter-VariableFont_slnt,wght.ttf │ │ ├── OFL.txt │ │ ├── README.txt │ │ └── static │ │ ├── Inter-Black.ttf │ │ ├── Inter-Bold.ttf │ │ ├── Inter-ExtraBold.ttf │ │ ├── Inter-ExtraLight.ttf │ │ ├── Inter-Light.ttf │ │ ├── Inter-Medium.ttf │ │ ├── Inter-Regular.ttf │ │ ├── Inter-SemiBold.ttf │ │ └── Inter-Thin.ttf └── pages │ ├── index.js │ ├── index.module.css │ └── markdown-page.md └── static ├── .nojekyll ├── CNAME └── img ├── after-verify.png ├── app-architecture-overview.png ├── architecture-overview.png ├── before-verify.png ├── ceramic-overview.png ├── data-model-table.png ├── eip-712-generate.png ├── example-application-ui.png ├── favicon.png ├── final-diagram.png ├── generate-712.png ├── getting-started-img.png ├── graphiql.png ├── intro-dataverse.png ├── jwt-generate.png ├── logo.svg ├── postman.png ├── protocol.png ├── query-interfaces.png ├── sandbox-extension.png ├── schema_serto.png ├── serto-example.png ├── sign-in.png ├── tech-architecture.png ├── undraw_docusaurus_mountain.svg ├── undraw_docusaurus_react.svg ├── undraw_docusaurus_tree.svg ├── vc-playground.png ├── verify-jwt.png ├── verse.png └── wallet-modal.png /.github/workflows/build-deploy-docs.yml: -------------------------------------------------------------------------------- 1 | name: Build and deploy docs 2 | 3 | on: 4 | pull_request: 5 | branches: 6 | - main 7 | push: 8 | branches: 9 | - main 10 | workflow_dispatch: # manually triggered 11 | 12 | jobs: 13 | build: 14 | name: Build docs website 15 | runs-on: ubuntu-latest 16 | steps: 17 | - name: Checkout repository 18 | uses: actions/checkout@v4 19 | 20 | - name: Install pnpm 21 | uses: pnpm/action-setup@v4 22 | with: 23 | version: 10 24 | run_install: | 25 | - args: [--frozen-lockfile] 26 | 27 | - name: Setup node 28 | uses: actions/setup-node@v4 29 | with: 30 | node-version: 22 31 | cache: 'pnpm' 32 | 33 | - name: Build docs website 34 | run: pnpm build 35 | 36 | - name: Deploy to GitHub Pages 37 | if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' 38 | uses: peaceiris/actions-gh-pages@v4 39 | with: 40 | github_token: ${{ secrets.GITHUB_TOKEN }} 41 | publish_dir: ./build 42 | user_name: github-actions[bot] 43 | user_email: 41898282+github-actions[bot]@users.noreply.github.com 44 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | /node_modules 3 | 4 | # Production 5 | /build 6 | 7 | # Generated files 8 | .docusaurus 9 | .cache-loader 10 | 11 | # Misc 12 | .DS_Store 13 | .env.local 14 | .env.development.local 15 | .env.test.local 16 | .env.production.local 17 | 18 | npm-debug.log* 19 | yarn-debug.log* 20 | yarn-error.log* 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Ceramic Documentation 2 | 3 | This repository contains the code and markdown files for the Ceramic documentation site. View the full site at [**developers.ceramic.network**](https://developers.ceramic.network). 4 | This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. 5 | 6 | ### Local Development 7 | Follow these steps to run the site locally and test your changes. 8 | 9 | Install the dependencies: 10 | 11 | ``` 12 | $ pnpm install 13 | ``` 14 | 15 | Start a local development server: 16 | 17 | ``` 18 | $ pnpm start 19 | ``` 20 | 21 | This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. 22 | 23 | ### Build 24 | 25 | ``` 26 | $ pnpm build 27 | ``` 28 | 29 | This command generates static content into the `build` directory and can be served using any static contents hosting service. 30 | 31 | ### Deployment 32 | 33 | The website is automatically deployed by a GitHub action on commits to the main branch. 34 | 35 | ## Contributing 36 | We welcome all contributions – big and small. To contribute, make your change and submit a PR to this repo describing what you've done. 37 | -------------------------------------------------------------------------------- /babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')], 3 | }; 4 | -------------------------------------------------------------------------------- /docs/composedb/create-ceramic-app.mdx: -------------------------------------------------------------------------------- 1 | import Tabs from "@theme/Tabs"; 2 | import TabItem from "@theme/TabItem"; 3 | 4 | # Scaffold a new Ceramic app 5 | 6 | Get up and running quickly with a basic ComposeDB application with one command. 7 | 8 | **Prerequisites** 9 | 10 | - Operating system: **Linux, Mac, or Windows** (only [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)) 11 | - **Node.js v20** - If you are using a different version, please use `nvm` to install Node.js v20 for best results. 12 | - **npm v10** - Installed automatically with NodeJS v20 13 | 14 | You will also need to run a ceramic-one node in the background which provides Ceramic 15 | data network access. To set it up, follow the steps below: 16 | 17 | :::note 18 | The instructions below cover the steps for the MacOS-based systems. If you are running on a Linux-based system, you can find the 19 | instructions [here](https://github.com/ceramicnetwork/rust-ceramic?tab=readme-ov-file#linux---debian-based-distributions). 20 | ::: 21 | 22 | 1. Install the component using [Homebrew](https://brew.sh/): 23 | 24 | ```bash 25 | brew install ceramicnetwork/tap/ceramic-one 26 | ``` 27 | 28 | 2. Start the `ceramic-one` using the following command: 29 | ```bash 30 | ceramic-one daemon --network in-memory 31 | ``` 32 | 33 | :::note 34 | By default, the command above will spin off a node which connects to a `in-memory`. You can change this behaviour by providing a `--network` flag and specifying a network of your choice. For example: 35 | 36 | ```ceramic-one daemon --network testnet-clay``` 37 | ::: 38 | 39 | --- 40 | 41 | ## Start the ComposeDB example app 42 | 43 | You can easily create a simple ComposeDB starter project by using our CLI and running the following command: 44 | 45 | 54 | 55 | 56 | ```powershell 57 | npx create-ceramic-app 58 | ``` 59 | 60 | 61 | 62 | 63 | ```powershell 64 | pnpx create-ceramic-app 65 | ``` 66 | 67 | 68 | 69 | 70 | :::tip 71 | You need at least yarn 2.x to use the `yarn dlx` command. If you have an older version, upgrade it by running `yarn set version stable` and `yarn install`. 72 | 73 | Then you can run the following command to create a new Ceramic app using yarn 2.x 74 | ::: 75 | 76 | ```powershell 77 | yarn dlx create-ceramic-app 78 | ``` 79 | 80 | 81 | 82 | 83 | ```powershell 84 | bunx create-ceramic-app 85 | ``` 86 | 87 | 88 | 89 | 90 | This command will create a new directory with a basic ComposeDB application (a social app). It will clone the app from [repository](https://github.com/ceramicstudio/ComposeDbExampleApp.git), install all dependencies, launch a local Ceramic node, a local GraphQL server and start the app. 91 | 92 | Once you have an opportunity to play with an example app and see how it works, you can start building your own app. For that, you will probably want to have more control over your environment and the code. You can find more information on how to set up your environment in the [Set up your environment](./set-up-your-environment) section. 93 | -------------------------------------------------------------------------------- /docs/composedb/create-your-composite.mdx: -------------------------------------------------------------------------------- 1 | # Create your composite 2 | 3 | Create your composite to serve as your graph database schema. In this guide, we will create your first composite. 4 | 5 | :::tip 6 | 7 | Before continuing, you must have [set up your environment](./set-up-your-environment.mdx) in the previous step 8 | 9 | ::: 10 | 11 | ## Overview 12 | --- 13 | 14 | A composite is your database schema for ComposeDB, which includes a collection of data models. Once created, your composite instructs your node which models to index and also allows your client to perform queries and mutations on these models. 15 | 16 | ## Data Model Catalog 17 | --- 18 | 19 | The [Model Catalog](./guides/data-modeling/model-catalog.mdx) contains all models created by other ComposeDB developers. By creating or reusing models within the model catalog in your composite, you can instantly share and sync data with other applications. This brings native app data composability to Web3 -- no more API integrations. 20 | 21 | ### List all models 22 | To list all models in the model catalog, run the following command: 23 | 24 | ```bash 25 | composedb model:list --table 26 | ``` 27 | 28 | Here, the flag `--table` will display the output in an organized table view and provide more details about each model’s functionality. By default, this command lists models in production on mainnet. To see models being developed on clay testnet, specify `--network=testnet-clay`: 29 | 30 | ```bash 31 | composedb model:list --network=testnet-clay --table 32 | ``` 33 | 34 | ![Data Model Table](/img/data-model-table.png) 35 | 36 | Notice each model has the following properties: 37 | 38 | - `Name` - model name 39 | - `Unique ID` - unique identifier (stream ID) for the model 40 | - `Description` - description of the model’s functionality 41 | 42 | ## Creating the composite 43 | --- 44 | 45 | In this section we will show how to create a composite by downloading models from the model catalog. 46 | 47 | ### Using a single model 48 | 49 | You can fetch any existing model from the catalog by referencing the model’s unique ID. For example, for your basic social media app, use the existing model `SimpleProfile`. To fetch the model, to your working directory, take note of the model stream ID in the table above and run the following command: 50 | 51 | ```bash 52 | composedb composite:from-model kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65 --ceramic-url=http://localhost:7007 --output=my-first-composite.json 53 | ``` 54 | 55 | You should see the following output in your terminal: 56 | 57 | ```bash 58 | ✔ Creating a composite from models... Composite was created and its encoded representation was saved in my-first-composite.json 59 | ``` 60 | 61 | This output means that you now have the `SimpleProfile` model stored locally in a file called `my-first-composite.json`. 62 | 63 | ### Using multiple models 64 | 65 | If your application needs multiple models, for example the `SimpleProfile` and `Post` models, you can. To fetch them, take note of the model stream IDs and provide them in a ComposeDB CLI command as follows: 66 | 67 | ```bash 68 | composedb composite:from-model kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65 kjzl6hvfrbw6c822s0cj1ug59spj648ml8a6mbqaz91wx8zx3mlwi76tfh3u1dy --ceramic-url=http://localhost:7007 --output=my-first-composite.json 69 | ``` 70 | 71 | The output of this command will be a composite file named `my-first-composite.json`. 72 | 73 | ## Using the composite 74 | --- 75 | ### Deploying the composite 76 | 77 | You will have to deploy the composite with fetched models to your local Ceramic node so that they can be used when building and running your applications. This can be achieved by using ComposeDB CLI and referencing the composite file of fetched models in your local environment as shown below. Note that you have to provide [your did private key](./set-up-your-environment#generate-your-private-key) to deploy the model: 78 | 79 | ```bash 80 | composedb composite:deploy my-first-composite.json --ceramic-url=http://localhost:7007 --did-private-key=your-private-key 81 | ``` 82 | 83 | You should see the output similar to the one below: 84 | 85 | ```bash 86 | ℹ Using DID did:key:z6MkoDgemAx51v8w692aZRLPdwP6UPKj3EgUhBTvbL7hCwLu 87 | ✔ Deploying the composite... Done! 88 | ["kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65"] 89 | ``` 90 | 91 | Whenever composites are deployed, the models will be automatically indexed. This also means that these models are shared across the network (at the moment, only Clay testnet). If you check the output produced by the terminal that runs your Ceramic local node, you should see a similar output: 92 | 93 | ```bash 94 | IMPORTANT: Starting indexing for Model kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65 95 | IMPORTANT: Starting indexing for Model kjzl6hvfrbw6c822s0cj1ug59spj648ml8a6mbqaz91wx8zx3mlwi76tfh3u1dy 96 | IMPORTANT: Creating ComposeDB Indexing table for model: kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65 97 | IMPORTANT: Creating ComposeDB Indexing table for model: kjzl6hvfrbw6c822s0cj1ug59spj648ml8a6mbqaz91wx8zx3mlwi76tfh3u1dy 98 | ``` 99 | 100 | This means that the composite was deployed and the models were indexed on your local node successfully! 🎉 101 | 102 | ### Compiling the composite 103 | 104 | The last step left is compiling the composite. This is necessary to interact with the data in the next step of this guide: 105 | 106 | ```bash 107 | composedb composite:compile my-first-composite.json runtime-composite.json 108 | ``` 109 | 110 | You should see the following output in your terminal: 111 | 112 | ```bash 113 | ✔ Compiling the composite... Done! 114 | runtime-composite.json 115 | ``` 116 | 117 | The output of this command will be a json file called `runtime-composite.json` 118 | 119 | ## Next Steps 120 | --- 121 | Now that you have created your composite, you are ready to use it: **[Interact with data →](./interact-with-data.mdx)** 122 | 123 | ## Related Guides 124 | 125 | - [Intro to Modeling](./guides/data-modeling/data-modeling.mdx) 126 | 127 | - [Model Catalog](./guides/data-modeling/model-catalog.mdx) 128 | 129 | - [Writing Models](./guides/data-modeling/writing-models.mdx) 130 | 131 | - [Composites](./guides/data-modeling/composites.mdx) 132 | -------------------------------------------------------------------------------- /docs/composedb/examples/index.mdx: -------------------------------------------------------------------------------- 1 | # Tutorials and Examples 2 | 3 | If you have built an example app from the [**Set up your environment**](./set-up-your-environment) section and now you're looking for more, check out the extensive list of [**Starter Applications and Tutorials**](./examples/tutorials-and-examples) or go deep with the [**Verifiable Credentials**](./examples/verifiable-credentials) guide. 4 | -------------------------------------------------------------------------------- /docs/composedb/examples/tutorials-and-examples.mdx: -------------------------------------------------------------------------------- 1 | # Starter Applications and Tutorials 2 | 3 | Looking for code samples, starter applications, and tutorials to kickstart your development process? Check out some of the examples below for inspiration. 4 | 5 | ## Starter Applications 6 | 7 | - [**Official ComposeDB Example App**](https://github.com/ceramicstudio/ComposeDbExampleApp) - A starter application built around a social media platform use-case. A great first step if you haven't done anything with ComposeDB yet. 8 | - [**Lit Protocol with ComposeDB**](https://github.com/ceramicstudio/lit-composedb) - Encrypt and decrypt data based on on-chain condition logic using Lit Protocol while storing on ComposeDB 9 | - [**Ethereum Attestation Service on ComposeDB**](https://github.com/ceramicstudio/ceramic-eas) - Save attestations generated using the Ethereum Attestation Service to the Ceramic Network using ComposeDB. 10 | - [**OpenAI Realtime Chat with ComposeDB**](https://github.com/ceramicstudio/ceramic-ai) - Interact with an OpenAI API endpoint in the form of a realtime chat application with storage on ComposeDB. 11 | 12 | ## Tutorials 13 | 14 | - [**Getting Started with ComposeDB (video)**](https://www.youtube.com/watch?v=r68FXBTCBZ4) - Follow an instructional video on getting started and set up on ComposeDB. 15 | - [**Verifiable Credentials**](./verifiable-credentials.mdx) - Learn how to create and verify verifiable credentials on ComposeDB. 16 | - [**Lit Protocol with ComposeDB**](https://developer.litprotocol.com/v3/integrations/storage/ceramic-example) - A tutorial that walks the reader through how the `Lit Protocol with ComposeDB` repository (linked above) works under-the-hood. 17 | - [**Decentralized Databases: ComposeDB**](https://dev.to/fllstck/decentralized-databases-composedb-49m3) - A tutorial that walks the reader through how to set up a decentralized blog on ComposeDB. 18 | - [**Build an AI Chatbot on ComposeDB**](https://learnweb3.io/lessons/build-an-ai-chatbot-on-compose-db-and-the-ceramic-network) - Read a LearnWeb3.io tutorial on how the `OpenAI Realtime Chat with ComposeDB` repository (linked above) works and how to set it up. 19 | - [**Query Filtering and Ordering in ComposeDB**](https://blog.ceramic.network/tutorial-query-filtering-and-ordering-in-composedb/) - Learn the ins and outs of filtering and ordering based on schema subfields in this tutorial blog post. 20 | - [**Creating `MetIRL` Attestations with EAS**](https://docs.attest.sh/docs/tutorials/ceramic-storage) - Learn how the `Ethereum Attestation Service on ComposeDB` repository (linked above) works, how to generate attestations, and how to create confirmations. 21 | - [**Encrypted Data on ComposeDB**](https://blog.ceramic.network/tutorial-encrypted-data-on-composedb/) - Learn yet another way to encrypt and decrypt data on ComposeDB by generating an `encryptionDid` instance. 22 | - [**Verax Attestations with Ceramic Storage**](https://docs.ver.ax/verax-documentation/developer-guides/tutorials/using-ceramic-to-store-the-attestation-payload) - Learn how Ceramic can be used together with Verax on-chain attestations as an efficient storage mechanism for off-chain metadata. 23 | - [**Mastering SET Relations and Immutable Fields (video)**](https://www.youtube.com/watch?v=T2BRQqPI354) - An instructional video walk-through of how to use SET account relations and immutable field features in ComposeDB. 24 | 25 | ## Experiments & SDKs 26 | 27 | - [**Web3 Points Library**](https://github.com/ceramicstudio/solutions-sdk/tree/main/libraries/points) - An experimental use case-based library designed to support developers looking to use Ceramic as the basis for their rewards, incentives, and point systems. 28 | - [**Web3 Points Demo Application**](https://github.com/ceramicstudio/points-example) - A simple full-stack demonstration of how to use the Web3 Points Library to reward users for joining a community's platform presence (in this case, a Discord server). Also contains an extension using Gitcoin Passport located in the `with-gitcoin` branch. 29 | - [**Web3 Points Library Example App Tutorial**](https://blog.ceramic.network/web3-points-library-tutorial/) - A walk-through of the example app demo application (linked above). 30 | - [**Web3 Points Example App Tutorial - YouTube Version**](https://www.youtube.com/watch?v=75IZp2oYncM) - A video walk-through version of the tutorial mentioned above. 31 | 32 | ### **Want your open-source examples featured here?** 33 | 34 | Get in touch with us on the [Ceramic Discord](https://chat.ceramic.network) - we'd love to see what you're building! 35 | -------------------------------------------------------------------------------- /docs/composedb/getting-started.mdx: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## What is Ceramic? 4 | 5 | Ceramic is a shared data network for managing verifiable data at scale, combining **the trust and composability of a blockchain** with **the flexibility of an event-driven architecture** to help organizations get more value from their data. 6 | 7 | Ceramic provides developers with a shared data network that offers verifiable trust and interoperability, allowing them to leverage reusable data models, collective network effects and modular applications so they can focus on building and growing their unique vision. 8 | 9 | ## What is ComposeDB? 10 | 11 | ComposeDB is a composable graph database built on Ceramic, designed for Web3 applications. 12 | 13 | ComposeDB on Ceramic stores and manages data while delivering fast queries and a catalog of plug-and-play data models. Developers, data scientists, and architects use it as the graph data layer for Web3. 14 | 15 | ### Why ComposeDB? 16 | 17 | - Store and query data with powerful, easy-to-use GraphQL APIs 18 | - Build faster with a catalog of plug-and-play schemas 19 | - Bootstrap content by plugging into a composable data ecosystem 20 | - Deliver great UX with sign-in with Ethereum, Solana, and more 21 | - Eliminate trust and guarantee data verifiability 22 | - Scale your Web3 data infrastructure beyond L1 or L2 blockchains 23 | 24 | ### What are the Common Use Cases? 25 | 26 | - **Decentralized identity** - user profiles, credentials, reputation systems 27 | - **Web3 social** - social graphs, posts, reactions, comments, messages 28 | - **DAO tools** - proposals, projects, tasks, votes, contribution graphs 29 | - **Open information graphs** - DeSci graphs, knowledge graphs, discourse graphs 30 | 31 | ## How to Get Started 32 | 33 | - [**Create your first Ceramic app**](./create-ceramic-app) - As easy as running `npx create-ceramic-app`, run your first local Ceramic app and start diving into code. 34 | - [**Set up your environment**](./set-up-your-environment) - Learn how to set up your development environment to start building with ComposeDB. Experience the real Ceramic network, either on the testnet or mainnet. 35 | - [**Create your composite**](./create-your-composite) - Learn how to create your first composite, a reusable data model that can be used across different applications. 36 | - [**Interact with data**](./interact-with-data) - Learn how to interact with data in ComposeDB, from creating, reading, updating, and deleting data to running complex queries. 37 | - [**Core ComposeDB concepts**](./core-concepts) - Learn about the core concepts of ComposeDB, such as composites, schemas, and queries. 38 | 39 | ## Join Ceramic Community 💜 40 | 41 | Ceramic has a large and active community of developers. Here's how you can connect with us: 42 | 43 | - [**Forum**](https://forum.ceramic.network) - The best place to ask questions and to search for answers. 44 | - [**Discord**](https://chat.ceramic.network) - Join the conversation with other developers and the Ceramic team. 45 | - [**Twitter**](https://twitter.com/ceramicnetwork) - Follow us on Twitter for updates and announcements. 46 | - [**GitHub**](https://github.com/ceramicnetwork/) - Check out the Ceramic GitHub organization to find all the repositories and projects. 47 | -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-client/authenticate-users.mdx: -------------------------------------------------------------------------------- 1 | # Authenticate Users 2 | Set up authentication for your ComposeDB application. 3 | 4 | ## Introduction 5 | in ComposeDB, authentication is needed to [enable mutations](../../guides/data-interactions/mutations.mdx) on data controlled by a user’s account. 6 | 7 | ## Get Started 8 | 9 | ### Enable sessions 10 | 11 | Enable users to create an authenticated session using their blockchain wallet. 12 | 13 | [**User Sessions →**](./user-sessions.mdx) -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-client/composedb-client.mdx: -------------------------------------------------------------------------------- 1 | # ComposeDB Client 2 | 3 | Connect your app to a ComposeDB server 4 | 5 | ## Connect your application 6 | 7 | Interact with ComposeDB using JavaScript, TypeScript, or React 8 | 9 | **[JavaScript Client →](./javascript-client.mdx)** 10 | 11 | ## Authenticate users 12 | 13 | Enable user interactions, including data mutations 14 | 15 | **[Authenticate Users →](./authenticate-users.mdx)** 16 | -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-client/javascript-client.mdx: -------------------------------------------------------------------------------- 1 | import Tabs from '@theme/Tabs' 2 | import TabItem from '@theme/TabItem' 3 | import DocCardList from '@theme/DocCardList'; 4 | 5 | # JavaScript Client 6 | APIs to interact with ComposeDB from JavaScript, TypeScript, or React. 7 | 8 | ## Prerequisites 9 | --- 10 | - A [compiled composite](../../guides/data-modeling/composites.mdx#compiling-composites) 11 | 12 | ## Installation 13 | --- 14 | Install the ComposeDB client package: 15 | 16 | 24 | 25 | 26 | ```bash 27 | npm install @composedb/client 28 | ``` 29 | 30 | 31 | 32 | 33 | ```bash 34 | pnpm add @composedb/client 35 | ``` 36 | 37 | 38 | 39 | 40 | ```bash 41 | yarn add @composedb/client 42 | ``` 43 | 44 | 45 | 46 | 47 | If you’re using TypeScript, you may also need to install ComposeDB Types: 48 | 49 | 57 | 58 | 59 | ```bash 60 | npm install -D @composedb/types 61 | ``` 62 | 63 | 64 | 65 | 66 | ```bash 67 | pnpm add -D @composedb/types 68 | ``` 69 | 70 | 71 | 72 | 73 | ```bash 74 | yarn add -D @composedb/types 75 | ``` 76 | 77 | 78 | 79 | 80 | 81 | ## Configuration 82 | --- 83 | Create a client instance by passing your server URL and your compiled composite: 84 | 85 | ```jsx 86 | // Import ComposeDB client 87 | 88 | import { ComposeClient }from '@composedb/client' 89 | 90 | // Import your compiled composite 91 | 92 | import { definition }from './__generated__/definition.js' 93 | 94 | // Create an instance of ComposeClient 95 | // Pass the URL of your Ceramic server 96 | // Pass reference to your compiled composite 97 | 98 | const compose = new ComposeClient({ ceramic: 'http://localhost:7007', definition }) 99 | 100 | ``` 101 | 102 | More details: [`ComposeClient`](https://composedb.js.org/docs/0.5.x/api/classes/client.ComposeClient) 103 | 104 | ## Queries 105 | --- 106 | ### Executing Queries 107 | 108 | Execute GraphQL [Queries](../../guides/data-interactions/queries.mdx) using the schema that is auto-generated from your compiled composite: 109 | 110 | ```jsx 111 | // Get account of authenticated user 112 | 113 | await compose.executeQuery(` 114 | query { 115 | viewer { 116 | id 117 | } 118 | } 119 | `) 120 | 121 | ``` 122 | 123 | More details: [`executeQuery`](https://composedb.js.org/docs/0.5.x/api/classes/client.ComposeClient#executequery) 124 | 125 | ## Mutations 126 | --- 127 | ### Enabling Mutations 128 | 129 | :::tip 130 | Before enabling mutations you must [authenticate the user](./../composedb-client/authenticate-users.mdx). 131 | ::: 132 | 133 | After you have an authenticated user, enable [mutations](../../guides/data-interactions/mutations.mdx) by setting their authenticated account on the ComposeDB client: 134 | 135 | 142 | 143 | 144 | ```jsx 145 | // Assign the authorized did from your session to your client 146 | 147 | compose.setDID(session.did) 148 | ``` 149 | 150 | 151 | 152 | 153 | ```jsx 154 | // Call setDID method on ComposeClient instance 155 | // Using authenticated did instance 156 | 157 | compose.setDID(did) 158 | ``` 159 | 160 | 161 | 162 | 163 | ### Executing mutations 164 | In your client, you can execute GraphQL mutations using the schema that is auto-generated from your compiled composite. Follow examples in the [mutations](../../guides/data-interactions/mutations.mdx) guide. 165 | 166 | ## Next Steps 167 | --- 168 | Learn how to [**Authenticate Users →**](./../composedb-client/authenticate-users.mdx) 169 | 170 | ## Related Guides 171 | --- 172 | ComposeDB’s JavaScript client optionally works with popular GraphQL clients: 173 | 174 | -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-client/using-apollo.mdx: -------------------------------------------------------------------------------- 1 | # Using Apollo GraphQL Client 2 | [Apollo](https://www.apollographql.com/docs/react/api/core/ApolloClient) is a popular GraphQL client for React and other platforms. 3 | 4 | ## Prerequisites 5 | - Install the [`composedb`](../../set-up-your-environment.mdx) packages 6 | - Install `@apollo/client` 7 | - A compiled composite 8 | 9 | ## Usage 10 | ComposeDB client can be used with the [Apollo client](https://www.apollographql.com/docs/react/api/core/ApolloClient) by creating a custom [Apollo link](https://www.apollographql.com/docs/react/api/link/introduction), as shown in the example below: 11 | 12 | ```jsx 13 | import { ApolloClient, ApolloLink, InMemoryCache, Observable } from '@apollo/client' 14 | import { ComposeClient } from '@composedb/client' 15 | 16 | // Path to compiled composite 17 | import { definition } from './__generated__/definition.js' 18 | 19 | const compose = new ComposeClient({ ceramic: 'http://localhost:7007', definition }) 20 | 21 | // Create custom ApolloLink using ComposeClient instance to execute operations 22 | const link = new ApolloLink((operation) => { 23 | return new Observable((observer) => { 24 | compose.execute(operation.query, operation.variables).then( 25 | (result) => { 26 | observer.next(result) 27 | observer.complete() 28 | }, 29 | (error) => { 30 | observer.error(error) 31 | } 32 | ) 33 | }) 34 | }) 35 | 36 | // Use ApolloLink instance in ApolloClient config 37 | export const client = new ApolloClient({ cache: new InMemoryCache(), link }) 38 | ``` 39 | -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-client/using-relay.mdx: -------------------------------------------------------------------------------- 1 | # Using Relay GraphQL Client 2 | [Relay](https://relay.dev/) is a popular GraphQL client for React. 3 | 4 | ## Prerequisites 5 | - Install the [`composedb`](../../set-up-your-environment.mdx) packages 6 | - Install the `relay-runtime`package 7 | - A compiled composite 8 | 9 | ## Usage 10 | The ComposeDB client can be used with Relay by creating a custom [network layer](https://relay.dev/docs/guides/network-layer/), as shown: 11 | 12 | ```jsx 13 | import { ComposeClient } from '@composedb/client' 14 | import { Environment, Network, RecordSource, Store } from 'relay-runtime' 15 | 16 | // Path to compiled composite 17 | import { definition } from './__generated__/definition.js' 18 | 19 | const compose = new ComposeClient({ ceramic: 'http://localhost:7007', definition }) 20 | 21 | // Create custom Network using ComposeClient instance to execute operations 22 | const network = Network.create(async (request, variables) => { 23 | return await client.executeQuery(request.text, variables) 24 | }) 25 | 26 | // Use created Network instance to create Relay Environment 27 | export const environment = new Environment({ network, store: new Store(new RecordSource()) }) 28 | ``` -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-server/composedb-server.mdx: -------------------------------------------------------------------------------- 1 | # ComposeDB Server 2 | Set up and run a ComposeDB Server 3 | 4 | ## Running locally 5 | To get started quickly, run a ComposeDB server locally on your machine. 6 | 7 | [**Running Locally →**](../../guides/composedb-server/running-locally.mdx) 8 | 9 | ## Running in the cloud 10 | To support production usage, run a high-availability ComposeDB server in the cloud. 11 | 12 | [**Running in the Cloud →**](../../guides/composedb-server/running-in-the-cloud.mdx) 13 | 14 | ## Usage Guides 15 | Dive into our server usage guides for more information on: 16 | - [Server Configurations](../../guides/composedb-server/server-configurations.mdx) 17 | - [Access Mainnet](../../guides/composedb-server/access-mainnet.mdx) 18 | - [Data Storage](../../guides/composedb-server/data-storage.mdx) -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-server/data-storage.mdx: -------------------------------------------------------------------------------- 1 | # Data Storage 2 | Store and remove data from your node 3 | 4 | ## Overview 5 | In production, node operators can choose what content to store on their node by pinning and unpinning models or streams. Unpinning is not synonymous with deletion. 6 | 7 | ## Storage & Removal 8 | In order to prevent the loss of streams due to garbage collection, you need to explicitly pin the streams that you wish to persist. Pinning instructs the node to keep them around in persistent storage until they are explicitly unpinned. To view the commands for pinning & unpinning, see the [Ceramic docs](../../../protocol/js-ceramic/guides/ceramic-clients/javascript-clients/pinning) here. 9 | 10 | ## Deletion 11 | When using or participating in the Ceramic Network you should know that the data streams created have a slightly different set of operations that can be performed on them from the standard CRUD operations you may be used to in other tech stacks. 12 | 13 | All data streams are globally readable. If you know the streamID of any and all data streams that exist on the network you, and any other app in the world, can access the data values. This is the backbone of composability. Without this globally readable trait data created on Ceramic would not be portable from app to app. 14 | 15 | There is no “delete” operation on a Ceramic data stream. By nature the blockchain is a public ledger, and as such once a Ceramic stream is anchored on-chain, it will forever exist there. Although this data may end up becoming stale over time, it is forever preserved in the state it was last anchored. Since we cannot mutate the blockchain, we cannot ever perform a full deletion of a Ceramic data stream. Take this into consideration when deciding what types of data you plan to store on the Ceramic network. -------------------------------------------------------------------------------- /docs/composedb/guides/composedb-server/running-locally.mdx: -------------------------------------------------------------------------------- 1 | # Running Locally 2 | Run a ComposeDB server on your local server, e.g. your laptop. 3 | 4 | ## Things to Know 5 | - ComposeDB requires running a Ceramic node for decentralized data and a SQL instance for your index database. 6 | - ComposeDB requires a running `ceramic-one` node which is responsible for storing the data and coordinating with network participants. 7 | Make sure to configure and run the `ceramic-one` node first. You can find the steps of how to install and start the `ceramic-one` instance [here](../../set-up-your-environment#2-installation). 8 | - ComposeDB server can also be run locally [using Docker](../../guides/composedb-server/running-in-the-cloud.mdx). 9 | 10 | :::tip 11 | 12 | If you want to serve a live application in production, see [Running in the Cloud](../../guides/composedb-server/running-in-the-cloud.mdx). 13 | 14 | ::: 15 | 16 | 17 | ## Using Wheel 18 | 19 | The easiest way to to run ComposeDB server on your local machine is using [Wheel](https://github.com/ceramicstudio/wheel.git). 20 | 21 | ### Requirements 22 | 23 | - Node.js 24 | - jq 25 | - PostgreSQL (optional dependent on the network) 26 | - [ceramic-one](../../set-up-your-environment.mdx#2-installation) node up and running 27 | 28 | Head to [Setup Your Environment](../../set-up-your-environment.mdx#install-the-dependencies) section for more detailed dependency installation instructions. 29 | 30 | 31 | **Supported Operating Systems** 32 | - Linux 33 | - Mac 34 | - Windows (only WSL2) 35 | 36 | 37 | ### Setup 38 | 39 | First, install and run the `ceramic-one` binary: 40 | ```bash 41 | brew install ceramicnetwork/tap/ceramic-one 42 | ``` 43 | ```bash 44 | ceramic-one daemon 45 | ``` 46 | 47 | Next, download the Wheel: 48 | 49 | ```bash 50 | curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ceramicstudio/wheel/main/wheel.sh | bash 51 | ``` 52 | 53 | Once downloaded, start the Wheel and follow the setup prompt: 54 | 55 | ```bash 56 | ./wheel 57 | ``` 58 | 59 | When following the prompt, make sure to accept the `Include Caramic?` and `Include ComposeDB?` option to start a 60 | local Ceramic node enabled with CompoeDB. 61 | 62 | For detailed prompt reference and advanced Ceramic configurations head to [Wheel Reference](../../../wheel/wheel-reference.mdx). 63 | 64 | 65 | 66 | 67 | ## Using npm 68 | Alternative way to run ComposeDB Server locally is using npm. This option includes more manual configurations. 69 | 70 | 71 | ### Requirements 72 | **Runtime** 73 | - Node.js Version 16 74 | 75 | **Package Manager** 76 | - npm Version 6 77 | 78 | **Supported Operating Systems** 79 | - Linux 80 | - Mac 81 | - Windows 82 | 83 | :::note 84 | 85 | For Windows, Windows Subsystem for Linux 2 (WSL2) is strongly recommended. Using the Windows command line is not portable and can cause compatibility issue when running the same configuration on a different operating system (e.g. in a Linux-based cloud deployment). 86 | 87 | ::: 88 | 89 | ### Installation 90 | 91 | Install and run the `ceramic-one` binary: 92 | ```bash 93 | brew install ceramicnetwork/tap/ceramic-one 94 | ``` 95 | ```bash 96 | ceramic-one daemon 97 | ``` 98 | 99 | Install the Ceramic CLI and ComposeDB CLI using npm: 100 | 101 | ```bash 102 | npm install -g @ceramicnetwork/cli @composedb/cli 103 | ``` 104 | 105 | ### Basic Setup 106 | ### Admin account 107 | If you don’t already have one, you’ll need to create an admin account (DID) to handle restricted changes and admin operations on your node. To do so, follow the steps in [Set up your environment](../../set-up-your-environment.mdx#developer-account) to generate a key & account. Once you’ve added your admin DID to the config file, return here. 108 | 109 | #### Start the daemon 110 | Using a command line utility or terminal, start the Ceramic daemon: 111 | 112 | ```bash 113 | ceramic daemon 114 | ``` 115 | 116 | ### Configurations 117 | You now have a server running with the default configuration and a preconfigured IPFS node that can be used by the [ComposeDB Client](../../guides/composedb-client/composedb-client.mdx). 118 | 119 | ## Next Steps 120 | Edit your [Server Configurations](../../guides/composedb-server/server-configurations.mdx) for your use case. 121 | 122 | ## Related Guides 123 | Check out our other guides for running a node: 124 | 125 | - [Running in the Cloud](../../guides/composedb-server/running-in-the-cloud.mdx) -------------------------------------------------------------------------------- /docs/composedb/guides/data-interactions/data-interactions.mdx: -------------------------------------------------------------------------------- 1 | # Data Interactions 2 | Query and mutate data on ComposeDB. 3 | 4 | ## Overview 5 | After setting up your [ComposeDB Client](../../guides/composedb-client/javascript-client.mdx), you can perform queries and mutations on ComposeDB data. 6 | 7 | ## Getting Started 8 | 9 | ### Queries 10 | 11 | [**Queries**](../../guides/data-interactions/queries.mdx) allow you to fetch data. 12 | 13 | ### Mutations 14 | 15 | [**Mutations**](../../guides/data-interactions/mutations.mdx) allow you to create or update data. 16 | -------------------------------------------------------------------------------- /docs/composedb/guides/data-interactions/mutations.mdx: -------------------------------------------------------------------------------- 1 | import Tabs from '@theme/Tabs' 2 | import TabItem from '@theme/TabItem' 3 | 4 | # Mutations 5 | 6 | Create or update data on ComposeDB. 7 | 8 | ## Prerequisites 9 | 10 | - An authenticated user 11 | - A deployed composite 12 | - A compiled composite 13 | 14 | :::tip 15 | The ComposeDB Client automatically generates a GraphQL Schema from your compiled composite. 16 | ::: 17 | 18 | ## Enable mutations 19 | 20 | Mutations require an authenticated user. After you have an authenticated user, enable mutations by setting their authenticated account on the ComposeDB client: 21 | 22 | 23 | 30 | 31 | 32 | ```jsx 33 | // Assign the authorized did from your session to your client 34 | 35 | compose.setDID(session.did) 36 | ``` 37 | 38 | 39 | 40 | 41 | ```jsx 42 | // Call setDID method on ComposeClient instance 43 | // Using authenticated did instance 44 | 45 | compose.setDID(did) 46 | ``` 47 | 48 | 49 | 50 | 51 | 52 | ## Create data 53 | Let’s say your app uses a `Post` model: 54 | 55 | ```jsx 56 | type Post @createModel(accountRelation: LIST, description: "A simple text post") { 57 | author: DID! @documentAccount 58 | title: String! @string(minLength: 10, maxLength: 100) 59 | text: String! @string(maxLength: 500) 60 | } 61 | ``` 62 | 63 | Users will generate data as they interact with your app. Your app needs to perform mutations to write that data to the network. Here’s a mutation query that creates a new post: 64 | 65 | ```graphql 66 | # Create post 67 | 68 | mutation CreateNewPost($i: CreatePostInput!) { 69 | createPost(input: $i) { 70 | document{ 71 | id 72 | title 73 | text 74 | } 75 | } 76 | } 77 | 78 | # Content for the post 79 | 80 | { 81 | "i": { 82 | "content": { 83 | "title": "Getting started with ComposeDB" 84 | "text": "A Post created using composites and GraphQL" 85 | } 86 | } 87 | } 88 | ``` 89 | 90 | Where: 91 | 92 | - `mutation`: GraphQL keyword for creating a write operation. 93 | - `CreateNewPost`: custom name given to this mutation. This name should represent what the mutation is doing and can be anything you’d like it to be. 94 | - `($i: CreatePostInput!)` creates a variable named `i` with the requirement that its value is of the type `CreatePostInput`. This type is automatically created for you as a part of the run-time composite. Notice the `!`, which informs us that this input is required. 95 | - `createPost` corresponds to an automatically generated GraphQL binding that is part of the run-time representation of your composite. Then names of these bindings follow a naming convention `create`. 96 | - `(input: $i)` is using the value provided for `$i` as the input for the mutation. This will be defined as a variable to this operation. 97 | - The final piece to this, `document{id,title,text}` is defining the fields of the document we would like this mutation to create. It’s important to note that you need to include `id` here in the mutation, but you will not need to include it in the query variables as it is automatically generated. 98 | - Variables: As you can see, `i` contains `content` that matches the fields in the above schema `title` and `text`. Both have the proper values supplied of a type `string`. This sets up the variables needed for the query. 99 | 100 | ## Update data 101 | Let’s say a user wanted to modify the title of a previous post. Your app would need to perform a mutation to update that field in the post. 102 | 103 | ```graphql 104 | # Update post 105 | 106 | mutation UpdatePost($i: UpdatePostInput!) { 107 | updatePost(input: $i) { 108 | document { 109 | id 110 | title 111 | text 112 | } 113 | } 114 | } 115 | 116 | # Content to be updated 117 | 118 | { 119 | "i": { 120 | "id": -------------------------------------------------------------------------------- /docs/composedb/guides/data-modeling/introduction-to-modeling.mdx: -------------------------------------------------------------------------------- 1 | # Introduction to Modeling 2 | Learn the basics of creating a new data model. 3 | 4 | ## Setup 5 | --- 6 | Create a new `.graphql` file in your project directory to store your model(s). 7 | 8 | For example, let’s create a file called `my-schema.graphql`. Inside, we’re going to create a model to store a very simple user profile: 9 | 10 | ```graphql 11 | type SimpleProfile @createModel(accountRelation: SINGLE, description: "Very basic profile") { 12 | displayName: String! @string(minLength: 3, maxLength: 50) 13 | } 14 | ``` 15 | 16 | ## Metadata 17 | --- 18 | Let’s look into the metadata properties of your new model: 19 | 20 | ```graphql 21 | type SimpleProfile @createModel(accountRelation: SINGLE, description: "Very basic profile") 22 | ``` 23 | 24 | Where: 25 | 26 | - `type` defines the name for your model, in our case `SimpleProfile` 27 | - `@createModel` is a directive that specifies we are creating a new model 28 | - `accountRelation` defines the allowable number of instances per account, where `SINGLE` limits one instance per account, and `LIST` allows unlimited instances per account 29 | - `description` is a string that describes the model 30 | 31 | :::tip 32 | 33 | Model names and descriptions are used in the [Model Catalog](./model-catalog.mdx). Aim for short and descriptive to improve discovery and reuse. 34 | 35 | ::: 36 | 37 | ## Schema 38 | --- 39 | Model schemas are written using the GraphQL Schema Definition Language (SDL). Let’s look at the schema of our new model. It’s a shape that only defines a single field (key) and scalar (value): 40 | 41 | ```graphql 42 | { 43 | displayName: String! @string(minLength: 3, maxLength: 50) 44 | } 45 | ``` 46 | 47 | Where: 48 | 49 | - `displayName` is a field 50 | - `String!` is a scalar that defines `displayName` is a required (`!`) string 51 | - `@string` is a directive that sets validation rules for the scalar, in our case min and max length 52 | 53 | :::tip 54 | 55 | This is a very basic schema. Your schemas can contain more than one field and include various relations. See [Schemas](./schemas.mdx) next. 56 | 57 | ::: 58 | 59 | ## Next Steps 60 | --- 61 | To use your new model in your application, you will need to create a [**Composite →**](./composites.mdx) 62 | 63 | ## Related Guides 64 | --- 65 | - Dive deeper into GraphQL [**Schemas**](./schemas.mdx) 66 | - Learn how to add [**Relations**](./relations.mdx) to your models -------------------------------------------------------------------------------- /docs/composedb/guides/data-modeling/model-catalog.mdx: -------------------------------------------------------------------------------- 1 | # Model Catalog 2 | Discover, share, and reuse data models. 3 | 4 | ## Overview 5 | --- 6 | The catalog is a free and open source repository of all data models created by the ComposeDB developer community. The catalog aims to make it as easy as possible for developers to discover, share, and reuse each others models and underlying data. 7 | 8 | ![Data Model Table](/img/data-model-table.png) 9 | 10 | ### Use Cases 11 | 12 | - Discover high-quality models for your app 13 | - Share and distribute your models to others 14 | 15 | ## Adding models to the catalog 16 | --- 17 | Models in all deployed composites are automatically available on the catalog. 18 | 19 | How it works: 20 | 21 | 1. A developer deploys a [composite](./composites.mdx) containing models to testnet or mainnet 22 | 2. An indexer builds a catalog of all deployed models and exposes it via API 23 | 3. The catalog is automatically available on various interfaces, including ComposeDB CLI 24 | 25 | ## Using models from the catalog 26 | --- 27 | ### Prerequisites 28 | 29 | You need a running instance of ComposeDB server and CLI to use the catalog. See [set up your environment](../../set-up-your-environment.mdx) to get started. 30 | 31 | ### List all models 32 | 33 | Using ComposeDB CLI, run the following command to list all models: 34 | 35 | ```sh 36 | composedb model:list --table 37 | ``` 38 | 39 | You will see a table where each model has the following metadata properties: 40 | 41 | - `Name` - name of the model 42 | - `ID` - unique identifier (streamID) of the model 43 | - `Description` - description of the model 44 | 45 | ### Using a single model 46 | Fetch a single model from the catalog and convert it into a composite, using its model ID: 47 | 48 | ```sh 49 | composedb composite:from-model kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65 --output=my-composite.json 50 | ``` 51 | 52 | ### Using multiple models 53 | Run the `composite:from-model` command depicted above for each model you want to use in your application. Remember to change the composite file name to avoid collisions. After you have multiple composite files, merge them. See Merging Composites. 54 | 55 | ## Next Steps 56 | --- 57 | To use your newly created composite in your app, you will need to deploy and compile your composite. 58 | 59 | ## Related Guides 60 | --- 61 | Can’t find what you’re looking for in the catalog? See [Writing Models](./writing-models.mdx) to learn how to write your own models. -------------------------------------------------------------------------------- /docs/composedb/guides/data-modeling/relations-combine-items.mdx: -------------------------------------------------------------------------------- 1 | # Example: Container of Items 2 | 3 | ## Creating the Models 4 | First, create the SDL for the first model to be combined 5 | 6 | ```graphql 7 | type Ball @createModel(accountRelation: LIST, description: "A ball to display") { 8 | creator: DID! @accountReference 9 | red: Int 10 | green: Int 11 | blue: Int 12 | radius: Float 13 | } 14 | ``` 15 | You will then save this to a file, such as `ball.graphql`. You can then add the model and get the id. 16 | 17 | composedb composite:create --output ball.json ball.graphql 18 | cat ball.json | jq '.models | keys_unsorted[0]' 19 | 20 | Now we need a second model that will *combine* with the first model 21 | 22 | ```graphql 23 | type Obstacle @createModel(accountRelation: LIST, description: "An obstacle a ball can collide with") { 24 | creator: DID! @accountReference 25 | x: Int 26 | y: Int 27 | z: Int 28 | length: Int 29 | width: Int 30 | height: Int 31 | } 32 | ``` 33 | 34 | Next, we're going to combine the existing models into a new model 35 | 36 | ```graphql 37 | type Ball @loadModel(id: "") { 38 | id: ID! 39 | } 40 | 41 | type Obstacle @loadModel(id: ""){ 42 | id: ID! 43 | } 44 | 45 | type Collision @createModel(accountRelation: LIST, description: "Collision between ball and object") { 46 | ballID: StreamID! @documentReference(model: "Ball") 47 | ball: Ball! @relationDocument(property: "ballID") 48 | obstacleID: StreamID! @documentReference(model: "Obstacle") 49 | obstacle: Ball! @relationDocument(property: "ballID") 50 | x: Int 51 | y: Int 52 | z: Int 53 | } 54 | ``` 55 | Save this to a file and add as above. 56 | 57 | We can now merge all of these and deploy them as a composite. 58 | 59 | composedb composite:merge ball.json obstacle.json collision.json --output=merged.json 60 | composedb composite:deploy merged.json 61 | composedb composite:compile merged.json runtime.json 62 | 63 | Our composite is now ready to use. We can use it with graphiql 64 | 65 | composedb graphql:server --graphiql runtime.json 66 | 67 | ## Inserting Data 68 | 69 | We can create an item with mutation 70 | 71 | ```graphql 72 | mutation CreateNewBall($i: CreateBallInput!){ 73 | createBall(input: $i){ 74 | document { 75 | id 76 | radius 77 | } 78 | } 79 | } 80 | ``` 81 | 82 | and variables 83 | 84 | ```graphql 85 | { 86 | "i": { 87 | "content": { 88 | "creator": "", 89 | "radius": 45, 90 | "red": 10, 91 | "green": 20, 92 | "blue": 30 93 | } 94 | } 95 | } 96 | ``` 97 | 98 | We can create a second object with a mutation 99 | 100 | ```graphql 101 | mutation CreateNewObstacle($i: CreateObstacleInput!){ 102 | createObstacle(input: $i){ 103 | document { 104 | id 105 | } 106 | } 107 | } 108 | ``` 109 | 110 | and variables 111 | 112 | ```graphql 113 | { 114 | "i": { 115 | "content": { 116 | "creator": "" 117 | "x": 1 118 | "y": 2 119 | "z": 3 120 | "length": 4 121 | "width": 5 122 | "height": 6 123 | } 124 | } 125 | } 126 | ``` 127 | 128 | Finally we can define the resultant object from combining items 129 | ```graphql 130 | mutation CreateCollision($i: CreateCollisionInput!){ 131 | createCollision(input: $i){ 132 | document { 133 | id 134 | } 135 | } 136 | } 137 | ``` 138 | and variables 139 | ```graphql 140 | { 141 | "i": { 142 | "content": { 143 | "ballID": "", 144 | "obstacleID": "" 145 | } 146 | } 147 | } 148 | ``` 149 | ## Query The Data 150 | We can query for the combined item 151 | ```graphql 152 | query { 153 | collisionIndex(first:5) { 154 | edges { 155 | node { 156 | id 157 | ball { 158 | id 159 | radius 160 | } 161 | obstacle { 162 | id 163 | } 164 | } 165 | } 166 | } 167 | } 168 | ``` -------------------------------------------------------------------------------- /docs/composedb/guides/data-modeling/relations-container-of-items.mdx: -------------------------------------------------------------------------------- 1 | # Example: Container of Items 2 | 3 | ## Creating the Models 4 | First, create the SDL for your item 5 | 6 | ```graphql 7 | type Ball @createModel(accountRelation: LIST, description: "A ball to display") { 8 | creator: DID! @accountReference 9 | red: Int 10 | green: Int 11 | blue: Int 12 | radius: Float 13 | } 14 | ``` 15 | You will then save this to a file, such as `ball.graphql`. You can then add the model and get the id. 16 | 17 | composedb composite:create --output ball.json ball.graphql 18 | cat ball.json | jq '.models | keys_unsorted[0]' 19 | 20 | Next, create the SDL for your container, without references to items 21 | ```graphql 22 | type World @createModel(accountRelation: LIST, description: "Ball World") { 23 | name: String! @string(minLength: 3, maxLength: 50) 24 | } 25 | ``` 26 | Save this to a file and add as above. Then we will create a model to relate our item and container 27 | ```graphql 28 | type Ball @loadModel(id: "") { 29 | id: ID! 30 | } 31 | 32 | type World @loadModel(id: ""){ 33 | id: ID! 34 | } 35 | 36 | type BallRelation @createModel(accountRelation: LIST, description: "Relate a ball to our world") { 37 | ballID: StreamID! @documentReference(model: "Ball") 38 | ball: Ball! @relationDocument(property: "ballID") 39 | worldID: StreamID! @documentReference(model: "World") 40 | world: World! @relationDocument(property: "worldID") 41 | } 42 | ``` 43 | For the relation, the ID will likely be the last model id. Finally, relate our container to our items 44 | ```graphql 45 | type BallRelation @loadModel(id: "") { 46 | id: ID! 47 | } 48 | 49 | type World @loadModel(id: "") { 50 | balls: [BallRelation] @relationFrom(model: "BallRelation", property: "worldID") 51 | } 52 | ``` 53 | 54 | :::caution 55 | This is a view on top of the models, so you cannot require your items, such as with `balls: [BallRelation!]` 56 | ::: 57 | 58 | We can now merge all of these and deploy them as a composite. 59 | 60 | composedb composite:merge ball.json world.json ball_relation.json world_relation.json --output=merged.json 61 | composedb composite:deploy merged.json 62 | composedb composite:compile merged.json runtime.json 63 | 64 | Our composite is now ready to use. We can use it with graphiql 65 | 66 | composedb graphql:server --graphiql runtime.json 67 | 68 | ## Inserting Data 69 | 70 | We can create an item with mutation 71 | 72 | ```graphql 73 | mutation CreateNewBall($i: CreateBallInput!){ 74 | createBall(input: $i){ 75 | document { 76 | id 77 | radius 78 | } 79 | } 80 | } 81 | ``` 82 | 83 | and variables 84 | 85 | ```graphql 86 | { 87 | "i": { 88 | "content": { 89 | "creator": "", 90 | "radius": 45, 91 | "red": 10, 92 | "green": 20, 93 | "blue": 30 94 | } 95 | } 96 | } 97 | ``` 98 | 99 | We can create a container with mutation 100 | 101 | ```graphql 102 | mutation CreateNewWorld($i: CreateWorldInput!){ 103 | createWorld(input: $i){ 104 | document { 105 | id 106 | } 107 | } 108 | } 109 | ``` 110 | 111 | and variables 112 | 113 | ```graphql 114 | { 115 | "i": { 116 | "content": { 117 | "name": "test-world", 118 | } 119 | } 120 | } 121 | ``` 122 | 123 | Finally we can define relations between items and the container with mutation 124 | ```graphql 125 | mutation CreateBallRelation($i: CreateBallRelationInput!){ 126 | createBallRelation(input: $i){ 127 | document { 128 | id 129 | } 130 | } 131 | } 132 | ``` 133 | and variables 134 | ```graphql 135 | { 136 | "i": { 137 | "content": { 138 | "ballID": "", 139 | "worldID": "" 140 | } 141 | } 142 | } 143 | ``` 144 | ## Query The Data 145 | We can query for the container for the items, and from that find the items. 146 | ```graphql 147 | query { 148 | worldIndex(first: 1) { 149 | edges { 150 | node { 151 | id 152 | name 153 | balls(first: 5) { 154 | edges { 155 | node { 156 | id 157 | ballID 158 | } 159 | } 160 | } 161 | } 162 | } 163 | } 164 | } 165 | ``` -------------------------------------------------------------------------------- /docs/composedb/guides/data-modeling/writing-models.mdx: -------------------------------------------------------------------------------- 1 | # Writing Models 2 | Create new models or extend existing models. 3 | 4 | ## Introduction to Modeling 5 | Learn the basics of creating a new data model. 6 | 7 | **[Introduction to Modeling →](../../guides/data-modeling/introduction-to-modeling.mdx)** 8 | 9 | 10 | ## Schemas 11 | Learn how to write high-quality GraphQL schemas for your models. 12 | 13 | **[Schemas →](../../guides/data-modeling/schemas.mdx)** 14 | 15 | 16 | ## Relations 17 | Define queryable relationships between models and other models or accounts. 18 | 19 | **[Relations →](../../guides/data-modeling/relations.mdx)** -------------------------------------------------------------------------------- /docs/composedb/guides/index.mdx: -------------------------------------------------------------------------------- 1 | # Guides 2 | 3 | [**Data Modeling**](./data-modeling/data-modeling.mdx) - Learn how to model data for ComposeDB. 4 | 5 | [**ComposeDB Client**](./composedb-client/composedb-client.mdx) - Connect your app to a ComposeDB server. 6 | 7 | [**ComposeDB Server**](./composedb-server/composedb-server.mdx) - Set up and run a ComposeDB Server. 8 | 9 | [**Data Interactions**](./data-interactions/data-interactions.mdx) - Query and mutate data on ComposeDB. 10 | -------------------------------------------------------------------------------- /docs/composedb/introduction.mdx: -------------------------------------------------------------------------------- 1 | # ComposeDB Docs 2 | ![Introduction](/img/intro-dataverse.png) 3 | 4 | ComposeDB is a composable graph database built on [Ceramic](https://ceramic.network), designed for Web3 applications. 5 | 6 | ### Use Cases 7 | | Use Case | Examples | 8 | |---|---| 9 | |__Decentralized identity__| `user profiles` `credentials` `reputation systems` | 10 | |__Web3 social__| `social graphs` `posts` `reactions` `comments` `messages` | 11 | |__DAO tools__| `proposals` `projects` `tasks` `votes` `contribution graphs` | 12 | |__Open information graphs__| `DeSci graphs` `knowledge graphs` `discourse graphs` | 13 | 14 | ### Why ComposeDB? 15 | 16 | - Store and query data with powerful, easy-to-use GraphQL APIs 17 | - Build faster with a catalog of plug-and-play schemas 18 | - Bootstrap content by plugging into a composable data ecosystem 19 | - Deliver great UX with sign-in with Ethereum, Solana, and more 20 | - Eliminate trust and guarantee data verifiability 21 | - Scale your Web3 data infrastructure beyond L1 or L2 blockchains 22 | 23 | ### Project Status: `Beta` 24 | 25 | ComposeDB officially entered `Beta` on February 28, 2023. What does this mean? 26 | 27 | - You can now build and deploy apps to production on mainnet! 28 | - Core features like GraphQL APIs, reusable models, and data composability are available 29 | - We will continue to improve performance and add more features 30 | - We are not yet guaranteeing a 100% stable, bug-free platform 31 | 32 | If you want to provide feedback, request new features, or report insufficient performance, please [make a post on the Forum](https://forum.ceramic.network/c/graph/9), as we'd like to work with you. 33 | Thank you for being a ComposeDB pioneer and understanding that great Web3 protocols take time to mature. 34 | 35 | 36 | 37 | 38 | ### [Get Started →](./getting-started) 39 | Build a Hello World application and interact from the CLI. 40 | 41 | ### [Development Guides →](./getting-started) 42 | Learn about data modeling, application set up, and data interactions. 43 | 44 | 45 | ### [Core concepts →](./core-concepts) 46 | Dive deeper into the ComposeDB protocol and its components. 47 | 48 | ### [Community →](../ecosystem/community.mdx) 49 | Connect with the ComposeDB developer community. 50 | -------------------------------------------------------------------------------- /docs/composedb/next-steps.mdx: -------------------------------------------------------------------------------- 1 | import Tabs from '@theme/Tabs' 2 | import TabItem from '@theme/TabItem' 3 | 4 | # Next Steps 5 | 6 | After learning the foundations of ComposeDB with the [Getting Started](./getting-started.mdx) guide, you are now ready to start integrating ComposeDB into your application and run in production. 7 | 8 | ## Integration Guides 9 | 10 | - Visit the [Guides](./guides/index.mdx) section to learn more about creating & interacting with data 11 | 12 | ## Examples 13 | 14 | - Create Ceramic App: [Blog](https://blog.ceramic.network/launching-create-ceramic-app/?ref=the-ceramic-blog-newsletter) 15 | 16 | ## Go Further 17 | 18 | - Join the [Community](../ecosystem/community.mdx) 19 | - Learn more about [Core Concepts](./core-concepts.mdx) 20 | - Level up your [Data Modeling](./guides/data-modeling/data-modeling.mdx) 21 | - Perform more advanced [Data interactions](./guides/data-interactions/data-interactions.mdx) 22 | -------------------------------------------------------------------------------- /docs/dids/authorization.md: -------------------------------------------------------------------------------- 1 | # Authorization 2 | 3 | Authorize and then use DIDs where needed. At the moment, Ethereum and Solana accounts 4 | are supported. Reference the chain/network specific libraries for more info on how to 5 | use each. Additional accounts will be supported in the future. 6 | 7 | Authorize with an Ethereum account using [@didtools/pkh-ethereum](https://did.js.org/docs/api/modules/pkh_ethereum): 8 | 9 | ```js 10 | import { DIDSession } from 'did-session' 11 | import { EthereumWebAuth, getAccountId } from '@didtools/pkh-ethereum' 12 | 13 | const ethProvider = // import/get your web3 eth provider 14 | const addresses = await ethProvider.request({ method: 'eth_requestAccounts' }) 15 | const accountId = await getAccountId(ethProvider, addresses[0]) 16 | const authMethod = await EthereumWebAuth.getAuthMethod(ethprovider, accountId) 17 | 18 | const session = await DIDSession.get(accountId, authMethod, { resources: [...]}) 19 | ``` 20 | 21 | Authorize with a Solana account using [@didtools/pkh-solana](https://did.js.org/docs/api/modules/pkh_solana): 22 | 23 | ```js 24 | import { DIDSession } from 'did-session' 25 | import { SolanaWebAuth, getAccountIdByNetwork } from '@didtools/pkh-solana' 26 | 27 | const solProvider = // import/get your Solana provider (ie: window.phantom.solana) 28 | const address = await solProvider.connect() 29 | const accountId = getAccountIdByNetwork('mainnet', address.publicKey.toString()) 30 | const authMethod = await SolanaWebAuth.getAuthMethod(solProvider, accountId) 31 | 32 | const session = await DIDSession.get(accountId, authMethod, { resources: [...]}) 33 | ``` 34 | 35 | With your session, use DIDs in composedb, ceramic & glaze libraries: 36 | 37 | ```js 38 | const ceramic = new CeramicClient() 39 | ceramic.did = session.did 40 | ``` 41 | -------------------------------------------------------------------------------- /docs/dids/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | When creating a DID session, you need to pass an array of string identifiers for resources you want to authorize 4 | for. In the context of the Ceramic Network, resources are an array of Model Stream Ids or Streams Ids. Typically 5 | you will just pass resources from the `@composedb` libraries as you will already manage your Composites and Models 6 | there. For example: 7 | 8 | ```js 9 | import { ComposeClient } from '@composedb/client' 10 | 11 | //... Reference above and `@composedb` docs for additional configuration here 12 | 13 | const client = new ComposeClient({ceramic, definition}) 14 | const resources = client.resources 15 | const session = await DIDSession.get(accountId, authMethod, { resources }) 16 | client.setDID(session.did) 17 | ``` 18 | 19 | If you are still using `@glazed` libraries and tile document streams you will typically pass a wildcard resource, 20 | this all allows 'access all'. While not ideal, there is technical limits in `@glazed` libraries and tile document 21 | streams that make it difficult to offer more granular permission access to sets of stream. Authorization was mostly 22 | designed with model document streams and `@composedb` libraries in mind. Wildcard resource may not be supported in 23 | the future. 24 | 25 | ```js 26 | const session = await DIDSession.get(accountId, authMethod, { resources: [`ceramic://*`]}) 27 | ``` 28 | 29 | By default a session will expire in 1 week. You can change this time by passing the `expiresInSecs` option to 30 | indicate how many seconds from the current time you want this session to expire. 31 | 32 | ```js 33 | const oneDay = 60 * 60 * 24 34 | const session = await DIDSession.get(accountId, authMethod, { resources: [...], expiresInSecs: oneDay }) 35 | ``` 36 | -------------------------------------------------------------------------------- /docs/dids/guides/add-chain-support.md: -------------------------------------------------------------------------------- 1 | # Add Support for a Blockchain 2 | 3 | The standard use of [SIWX](https://github.com/ChainAgnostic/CAIPs/pull/122), [CACAO](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md) and [DID:PKH](https://github.com/w3c-ccg/did-pkh/blob/main/did-pkh-method-draft.md) allows anyone to implement support for another blockchain or account type to authenticate and authorize writes to the Ceramic Network. Additionally a few standard interfaces enables you to implement an auth and verification library that allows anyone to use it with [`did-session`](https://github.com/ceramicnetwork/js-did/tree/main/packages/did-session), the primary library to use DID based accounts with Ceramic. There is just a few steps you have to take, outlined below. 4 | 5 | ### CASA Standards Support 6 | 7 | First make sure your blockchain has the necessary standards specification in the [Chain Agnostic Standards Alliance (CASA)](https://github.com/ChainAgnostic/CASA). CASA creates blockchain agnostic standards which support interoperability and facilitate communication between blockchain protocols, software and companies. Standards are submitted as [Chain Agnostic Improvement Proposals (CAIPs)](https://github.com/ChainAgnostic/CAIPs). Support in Ceramic requires a spec for the following CAIPs in the CASA namespace for your chain. 8 | 9 | 1) CAIP2 - [Blockchain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-2.md) 10 | 11 | 2) CAIP10 - [Account ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md) 12 | 13 | 3) CAIP122 - [Sign in With X (SIWx)](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-122.md) 14 | 15 | The CASA namespaces can be found [here](https://github.com/ChainAgnostic/namespaces). If your blockchain already exists and has the prior 3 CAIPs, then you can move on to the next steps. If not, then you can define these specs yourself by following the instructions in the namespace readme and opening a PR. You can look at other blockchain namespaces for how to format and specify your specs and reference your own ecosystem standards for some if they exist already. You can reach out to the 3Box Labs team for reviews and help if needed. 16 | 17 | ### DID:PKH Standards Support 18 | 19 | With accounts defined through CAIP10 you can now add standards support in DID:PKH for your blockchain. To add support simply add a test vector in the [did-pkh repo](https://github.com/w3c-ccg/did-pkh) that shows what a DID document resolution would look like for an example DID:PKH account for your blockchain. Reference other test vectors for examples and open a PR once ready. 20 | 21 | ### CACAO Support 22 | 23 | [CACAO](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-74.md) is a chain-agnostic Object Capability ([OCAP](https://en.wikipedia.org/wiki/Object-capability_model)). CACAO allows us to create DID sessions by transferring the rights to write/update specific Ceramic streams from a DID:PKH (blockchain account) to a browser session key. Session keys then can sign all Ceramic writes, needing to only sign with your blockchain account once. To add support for your blockchain we need be able to translate from SIWX messages to a CACAO (and back) and describe how to sign a SIWX. The library [`@didtools/cacao`](https://github.com/ceramicnetwork/js-did/tree/main/packages/cacao) implements this. 24 | 25 | To add support, first implement a SIWX class specific to your blockchain, based on the CAIP122 spec defined above. The file should be added to `src/siwx/siw(name).ts` and extend `SiwxMessage`. Typically you should only have to implement the function `signMessage()` which encodes a SIWX message in the format needed to sign message payloads in your ecosystem. Reference the Solana (SIWS) and Ethereum (SIWE) implementations for example. 26 | 27 | Lastly in `src/cacao.ts` implement a `fromSiw(name)Message` function for your blockchain which translates a given SIWX message to a CACAO. Again reference both SIWS and SIWE for example implementations. 28 | 29 | Once added, open a PR. You can reach out to the 3Box Labs team for reviews and help if needed. 30 | 31 | ### DID-Session and Ceramic Support 32 | 33 | To support your blockchain account as DID:PKH in Ceramic you need to be able to both sign and verify CACAOs. Signing and verifying is often specific to a chain depending on the ecosystem wallets, cryptography used and ecosystem standards. Each blockchain adds support by implementing an AuthMethod and Verifier in a blockchain specific library in the [`js-did` monorepo](https://github.com/ceramicnetwork/js-did). Reference existing chains, both Solana and Ethereum for example. 34 | 35 | Authmethods are the primary interface used by [`did-session`](https://github.com/ceramicnetwork/js-did/tree/main/packages/did-session). It has the following interface: 36 | 37 | ```tsx 38 | type AuthMethod = (opts: AuthMethodOpts) => Promise 39 | ``` 40 | 41 | Typically you will write a function or class that returns a configured AuthMethod and provides any specific helper functions that help a developer use your blockchain with an AuthMethod. 42 | 43 | Verifiers are used by Ceramic nodes to verify signed commits by a DID:PKH and CACAO. Nodes must register the verifiers needed for the blockchains and accounts they want to support. Right now most are included by default, once implemented. Verifers have the following interface. 44 | 45 | ```tsx 46 | export type Verifiers = Record 47 | 48 | export type CacaoVerifier = (cacao: Cacao, opts: VerifyOptions) => Promise 49 | ``` 50 | 51 | To add support you create a `@didtools/pkh-(namespace)` package in the [`js-did` monorepo](https://github.com/ceramicnetwork/js-did). Use the existing `@didtools/pkh-ethereum` and `@didtools/pkh-solana` libraries as a template to implement similar naming, functionality, documentation and testing. But primarily the library should export a `Verifier` and a function or class the gives the developer a configured `AuthMethod`. Once ready open a PR. You can reach out to the 3Box Labs team for reviews and help if needed. 52 | 53 | ### Ready, Set, Go 54 | 55 | Once your library and PR are accepted, we will release them for everyone to use and add verifier support for them in Ceramic. We aim to have each maintained by their respective ecosystems when possible, as we dont have the knowledge of all details and specifications in each ecosystem to best support each and every one. If they fall out of date, or tests begin to fail, we may not be able to maintain them ourselves. 56 | 57 | Congrats, now everyone can auth and write to Ceramic directly with their blockchain account of your choice. 58 | -------------------------------------------------------------------------------- /docs/dids/guides/concepts-overview.md: -------------------------------------------------------------------------------- 1 | # Concepts overview 2 | 3 | Ceramic uses the [Decentralized Identifier (DID)](https://w3c.github.io/did-core/) standard for users accounts. DIDs require no central authority - users control their data and whom they share it with. 4 | 5 | ## DID Methods 6 | 7 | We encourage using the `did:pkh` DID method which generates a persistent id from a wallet address’s public key hash. This enables one-click sign-on with your wallet to many apps on Ethereum, and soon on many other chains including Solana. 8 | 9 | ## DID Sessions 10 | 11 | DID-Sessions is a library for providing a familiar, "web session"-like experience. Users no longer have to sign every single action they take within an app - during a timebound period of time they can authorize the app developer to act on their behalf. DID-Sessions outputs verifiable, serializable objects that store information about which DIDs authenticated them, what capabilities they are authorized with and for how long. 12 | -------------------------------------------------------------------------------- /docs/dids/guides/upgrading-did-session.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "Upgrading DID Session" 3 | --- 4 | 5 | ## Upgrading from `did-session@0.x.x` to `did-session@1.x.x` 6 | 7 | AuthProviders change to AuthMethod interfaces. Similarly you can import the auth libraries you need. How you configure and manage 8 | these AuthMethods may differ, but each will return an AuthMethod function to be used with did-session. 9 | 10 | ```js 11 | // Before with v0.x.x 12 | //... 13 | import { EthereumAuthProvider } from '@ceramicnetwork/blockchain-utils-linking' 14 | 15 | const ethProvider = // import/get your web3 eth provider 16 | const addresses = await ethProvider.request({ method: 'eth_requestAccounts' }) 17 | const authProvider = new EthereumAuthProvider(ethProvider, addresses[0]) 18 | const session = new DIDSession({ authProvider }) 19 | const did = await session.authorize() 20 | 21 | // Now did-session@1.0.0 22 | ... 23 | import { EthereumWebAuth, getAccountId } from '@didtools/pkh-ethereum' 24 | 25 | const ethProvider = // import/get your web3 eth provider 26 | const addresses = await ethProvider.request({ method: 'eth_requestAccounts' }) 27 | const accountId = await getAccountId(ethProvider, addresses[0]) 28 | const authMethod = await EthereumWebAuth.getAuthMethod(ethProvider, accountId) 29 | const session = await DIDSession.authorize(authMethod, { resources: [...]}) 30 | const did = session.did 31 | ``` 32 | 33 | # Upgrading From `@glazed/did-session` to `did-session` 34 | 35 | `authorize` changes to a static method which returns a did-session instance and `getDID()` becomes a `did` getter. For example: 36 | 37 | ```js 38 | // Before @glazed/did-session 39 | const session = new DIDSession({ authProvider }) 40 | const did = await session.authorize() 41 | 42 | // Now did-session 43 | const session = await DIDSession.authorize(authProvider, { resources: [...]}) 44 | const did = session.did 45 | ``` 46 | 47 | Requesting resources are required now when authorizing, before wildcard (access all) was the default. You can continue to use 48 | wildcard by passing the following * below. Wildcard is typically only used with `@glazed` libraries and/or tile documents and 49 | it is best to switch over when possible, as the wildcard option may be * deprecated in the future. When using with 50 | composites/models you should request the minimum needed resources instead. 51 | 52 | ```js 53 | const session = await DIDSession.authorize(authProvider, { resources: [`ceramic://*`]}) 54 | const did = session.did 55 | ``` 56 | -------------------------------------------------------------------------------- /docs/dids/guides/using-with-composedb-client.md: -------------------------------------------------------------------------------- 1 | # Using With ComposeDB Client 2 | 3 | [ComposeDB](https://composedb.js.org) is a set of TypeScript libraries and tools to interact with the [Dataverse](https://blog.ceramic.network/into-the-dataverse/) using the [Ceramic network](https://ceramic.network/). 4 | 5 | First, you should start with creating your instance of `ComposeClient` from `@composedb/client` package, passing it the 6 | url to the ceramic node you want to use and the runtime composite definition of the composite you want to use in your App. 7 | 8 | ```js 9 | import { ComposeClient } from '@composedb/client' 10 | import { definition } from './__generated__/definition.js' 11 | 12 | const compose = new ComposeClient({ ceramic: 'http://localhost:7007', definition }) 13 | ``` 14 | 15 | Next, you can create a DID Session, passing it the resources from your client instance. The resources are a list of model 16 | stream IDs from your runtime composite definition: 17 | 18 | ```js 19 | import { DIDSession } from 'did-session' 20 | import type { AuthMethod } from '@didtools/cacao' 21 | import { EthereumWebAuth, getAccountId } from '@didtools/pkh-ethereum' 22 | 23 | const ethProvider = // import/get your web3 eth provider 24 | const addresses = await ethProvider).request({ method: 'eth_requestAccounts' }) 25 | const accountId = await getAccountId(ethProvider, addresses[0]) 26 | const authMethod = await EthereumWebAuth.getAuthMethod(ethProvider, accountId) 27 | 28 | const loadSession = async(authMethod: AuthMethod, resources: Array):Promise => { 29 | return DIDSession.authorize(authMethod, { resources }) 30 | } 31 | 32 | const session = await loadSession(authMethod, compose.resources) 33 | ``` 34 | 35 | Next, you can assign the authorized did from your session to your client. 36 | 37 | ```js 38 | compose.setDID(session.did) 39 | 40 | // use the compose instance to make queries in ComposeDB graph 41 | ``` 42 | 43 | Before you start making mutations with the client instance, you should make sure that the session is not expired 44 | ```js 45 | // before compose mutations, check if session is still valid, if expired, create new 46 | if (session.isExpired) { 47 | const session = loadSession(authMethod) 48 | compose.setDID(session.did) 49 | } 50 | 51 | // continue to make mutations 52 | ``` 53 | 54 | A typical pattern is to store a serialized session in local storage and load on use if available. 55 | 56 | :::caution Warning 57 | LocalStorage is used for illustrative purposes here and may not be best for your app, as 58 | there is a number of known issues with storing secret material in browser storage. The session string 59 | allows anyone with access to that string to make writes for that user for the time and resources that 60 | session is valid for. How that session string is stored and managed is the responsibility of the application. 61 | ::: 62 | 63 | ```js 64 | // An updated version of loadSession(...) 65 | const loadSession = async(authMethod: AuthMethod, resources: Array):Promise => { 66 | const sessionStr = localStorage.getItem('didsession') 67 | let session 68 | 69 | if (sessionStr) { 70 | session = await DIDSession.fromSession(sessionStr) 71 | } 72 | 73 | if (!session || (session.hasSession && session.isExpired)) { 74 | session = await DIDSession.authorize(authMethod, { resources }) 75 | localStorage.setItem('didsession', session.serialize()) 76 | } 77 | 78 | return session 79 | } 80 | ``` 81 | -------------------------------------------------------------------------------- /docs/dids/installation.mdx: -------------------------------------------------------------------------------- 1 | import Tabs from '@theme/Tabs' 2 | import TabItem from '@theme/TabItem' 3 | 4 | # Installation 5 | 6 | ### did-session 7 | 8 | We encourage you to use `did-sessions` to manage all your DID-related needs: 9 | 10 | 18 | 19 | 20 | ```sh 21 | pnpm add did-session 22 | ``` 23 | 24 | 25 | 26 | 27 | ```sh 28 | npm install did-session 29 | ``` 30 | 31 | 32 | 33 | 34 | ```sh 35 | yarn add did-session 36 | ``` 37 | 38 | 39 | 40 | 41 | ### @didtools/pkh-ethereum 42 | 43 | Add if you want to use did:pkh Ethereum accounts with `did-session`. 44 | 45 | 53 | 54 | 55 | ```sh 56 | pnpm add @didtools/pkh-ethereum 57 | ``` 58 | 59 | 60 | 61 | 62 | ```sh 63 | npm install @didtools/pkh-ethereum 64 | ``` 65 | 66 | 67 | 68 | 69 | ```sh 70 | yarn add @didtools/pkh-ethereum 71 | ``` 72 | 73 | 74 | 75 | 76 | ### @didtools/pkh-solana 77 | 78 | Add if you want to use did:pkh Solana accounts with `did-session`. 79 | 80 | 88 | 89 | 90 | ```sh 91 | pnpm add @didtools/pkh-solana 92 | ``` 93 | 94 | 95 | 96 | 97 | ```sh 98 | npm install @didtools/pkh-solana 99 | ``` 100 | 101 | 102 | 103 | 104 | ```sh 105 | yarn add @didtools/pkh-solana 106 | ``` 107 | 108 | 109 | 110 | 111 | ### dids 112 | 113 | You can also just use `dids`, if you want to manage a DID at a lower level or access additional functionality. 114 | 115 | 123 | 124 | 125 | ```sh 126 | pnpm add dids 127 | ``` 128 | 129 | 130 | 131 | 132 | ```sh 133 | npm install dids 134 | ``` 135 | 136 | 137 | 138 | 139 | ```sh 140 | yarn add dids 141 | ``` 142 | 143 | 144 | 145 | -------------------------------------------------------------------------------- /docs/dids/introduction.md: -------------------------------------------------------------------------------- 1 | # Welcome to Decentralized Identifiers 2 | 3 | A suite of tools and APIs to interact with and manage decentralized identifiers (DIDs). 4 | -------------------------------------------------------------------------------- /docs/dids/managing-sessions.md: -------------------------------------------------------------------------------- 1 | # Managing Sessions 2 | 3 | A session can be managed in a few different ways. All sessions consist of a session key in the form of a `did:key` and a CACAO object-capability. 4 | 5 | ## Automatically persisted sessions 6 | 7 | By default (when using `DIDSession.get(...)`) sessions are persisted to [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) in the background. The private key for this session is always a [non-extractable](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/extractable) key, which means that they key itself can't be stolen by a malicious browser extension or script. 8 | 9 | You can check if there already exists an authorized session for any given account using the `hasSessionFor` method. This can be useful if you want to know if the `DIDSession.get` call with result in a wallet interaction from the user, which will happen if `hasSessionFor` returns `false`. 10 | 11 | ```js 12 | if (await DIDSession.hasSessionFor(accountId, resources: [...])) { 13 | console.log(`There is an active session for ${accountId}`) 14 | } 15 | ``` 16 | 17 | ### Removing a persisted session 18 | 19 | If you want to remove a persisted session that was created using `DIDSession.get(...)`, you can use the static function `remove`. This will permanently remove the persisted session for a given account, and the user would need to reauthenticate in order to establish a new session. 20 | 21 | ```js 22 | await DIDSession.remove(accountId) 23 | ``` 24 | 25 | 26 | ### Session lifecycle management 27 | 28 | Additional helper fields are available on DIDSession instances. They can help you manage a session lifecycle and the user experience. For example, if a session has expired you might want to show a message to the user before you ask them for a new session. 29 | 30 | ```js 31 | // Check if authorized or created from existing session string 32 | didsession.hasSession 33 | 34 | // Check if session expired 35 | didsession.isExpired 36 | 37 | // Get resources session is authorized for 38 | didsession.authorizations 39 | 40 | // Check number of seconds till expiration, may want to re auth user at a time before expiration 41 | didsession.expiresInSecs 42 | ``` 43 | 44 | 45 | ## Manual session management 46 | 47 | If you don't want to rely on browsers non-extractable keys, or you are not in a browser environment you can use the `DIDSession.authorize(...)` function. This function creates a session that can be serialized to a string. You can store this for later and then re-initialize. Currently sessions are valid 48 | for 1 week by default. 49 | 50 | ```js 51 | // Create session as above, store for later 52 | const session = await DIDSession.authorize(authMethod, { resources: [...]}) 53 | const sessionString = session.serialize() 54 | 55 | // write/save session string where you want (e.g. filesystem) 56 | // ... 57 | 58 | // Later re initialize session 59 | const session2 = await DIDSession.fromSession(sessionString) 60 | ``` 61 | -------------------------------------------------------------------------------- /docs/ecosystem/community.mdx: -------------------------------------------------------------------------------- 1 | # Community 2 | Explore the many ways to connect, learn, and participate in the ComposeDB community. 3 | 4 | ## Chat and Discussion 5 | - **Forum** - Visit the [Ceramic Forum](https://forum.ceramic.network) to get help, ask questions, and discuss improvements. 6 | - **Discord** - Join the [Ceramic Discord](https://chat.ceramic.network) to join general discussions, share your projects, and meet your fellow community members. 7 | - **Bounties** - Get paid for learning & building on Ceramic, in the [#bounties](https://discord.com/channels/682786569857662976/1040706471689732096/1040719165268426924) channel 8 | 9 | ## Social Media 10 | - **Twitter** - Follow us on Twitter at [@ComposeDB](https://twitter.com/ceramicnetwork) for timely updates. 11 | - **YouTube** - Subscribe to the [Ceramic YouTube](https://www.youtube.com/channel/UCgCLq5dx7sX-yUrrEbtYqVw) to watch talks, tutorials, events, and more. 12 | 13 | ## Resources 14 | - **Blog** - Read the [Ceramic Blog](https://blog.ceramic.network) to discover updates and educational content for developers. 15 | - **Newsletter** - Subscribe to the [Ceramic Newsletter](https://blog.ceramic.network/#/portal/signup) to receive important announcements. 16 | 17 | ## Events 18 | - **Community Calls** 19 | - **Calendar** 20 | 21 | ## Ways to Contribute 22 | ### Ecosystem Grants 23 | If you’re interested in a grant feel free to reach out in the #bounties channel. We welcome all submissions, but we’re especially looking for contributions in the following areas: 24 | 25 | - **Marketplace GUI:** Wouldn’t it be great if developers could access the composite marketplace with an app UI instead of a terminal? 26 | - **Sample Apps & Models:** Inspire other developers by building sample apps & data models, like reputation credentials, social apps, or DAO tools. 27 | - **Easy Node Setup:** Make it easy to deploy ComposeDB on a node - we wrote a [proof of concept](https://github.com/ceramicstudio/ceramic-infra-poc) you can build on. Bonus: Terraform templates for cloud providers like AWS, GCP, and DigitalOcean. 28 | - **Config Script:** We’d love to make [Set up your environment](../composedb/set-up-your-environment) even easier. Want to create a lightning fast script? 29 | 30 | ### **Open source contributions** 31 | Contribute to the [ComposeDB repository](https://github.com/ceramicstudio/js-composedb): here are some packages to get started 32 | - [composedb/client](https://github.com/ceramicstudio/js-composedb/tree/main/packages/client) 33 | - [composedb/cli](https://github.com/ceramicstudio/js-composedb/tree/main/packages/cli) 34 | We recommend getting in touch on the [#ComposeDB](https://discord.com/channels/682786569857662976/1045002408671068220) Discord channel before diving in. 35 | 36 | ### **Project showcase** 37 | - Reach out on the Ceramic Discord channel [#share-your-project](https://discord.com/channels/682786569857662976/801569389044039710) to show off your project on Ceramic 38 | - See a list here of the [most popular projects](https://threebox.notion.site/Ceramic-Ecosystem-a3a7a58f81544d33ad3feb84368775d4). 39 | -------------------------------------------------------------------------------- /docs/introduction/ceramic-roadmap.md: -------------------------------------------------------------------------------- 1 | # Ceramic Roadmap 2 | 3 | 4 | 5 | 6 | 7 | 8 | Since the launch of the ComposeDB Beta, the core Ceramic team remains committed to making ongoing improvements 9 | to both ComposeDB and the underlying Ceramic protocol. Concurrently, we seek to involve the Ceramic developer 10 | community in shaping Ceramic's future. We value your active participation in helping us prioritize the features 11 | and improvements that matter most to our developer base. 12 | 13 | **All current and future projects are outlined in the [Ceramic roadmap](https://github.com/orgs/ceramicstudio/projects/2).** 14 | 15 | We welcome your feedback and insights on our roadmap priorities. You can show your support or express your concerns 16 | about projects on the roadmap by upvoting or downvoting them. Additionally, we encourage you to leave more detailed 17 | comments, making suggestions or indicating relevant feature requests. -------------------------------------------------------------------------------- /docs/introduction/composedb-overview.md: -------------------------------------------------------------------------------- 1 | # ComposeDB 2 | ![Introduction](/img/intro-dataverse.png) 3 | 4 | ComposeDB is a composable graph database built on [Ceramic](https://ceramic.network), designed for Web3 applications. 5 | 6 | ### Use Cases 7 | | Use Case | Examples | 8 | |---|---| 9 | |__Decentralized identity__| `user profiles` `credentials` `reputation systems` | 10 | |__Web3 social__| `social graphs` `posts` `reactions` `comments` `messages` | 11 | |__DAO tools__| `proposals` `projects` `tasks` `votes` `contribution graphs` | 12 | |__Open information graphs__| `DeSci graphs` `knowledge graphs` `discourse graphs` | 13 | 14 | ### Why ComposeDB? 15 | 16 | - Store and query data with powerful, easy-to-use GraphQL APIs 17 | - Build faster with a catalog of plug-and-play schemas 18 | - Bootstrap content by plugging into a composable data ecosystem 19 | - Deliver great UX with sign-in with Ethereum, Solana, and more 20 | - Eliminate trust and guarantee data verifiability 21 | - Scale your Web3 data infrastructure beyond L1 or L2 blockchains 22 | 23 | ### Project Status: `Beta` 24 | 25 | ComposeDB officially entered `Beta` on February 28, 2023. What does this mean? 26 | 27 | - You can now build and deploy apps to production on mainnet! 28 | - Core features like GraphQL APIs, reusable models, and data composability are available 29 | - We will continue to improve performance and add more features 30 | - We are not yet guaranteeing a 100% stable, bug-free platform 31 | 32 | If you want to provide feedback, request new features, or report insufficient performance, please [make a post on the Forum](https://forum.ceramic.network/), as we'd like to work with you. 33 | Thank you for being a ComposeDB pioneer and understanding that great Web3 protocols take time to mature. 34 | 35 | --- 36 | 37 | 38 | ### [Get Started →](../composedb/getting-started) 39 | Build a Hello World application and interact from the CLI. 40 | 41 | ### [Development Guides →](../composedb/guides) 42 | Learn about data modeling, application set up, and data interactions. 43 | 44 | 45 | ### [Core concepts →](../composedb/core-concepts) 46 | Dive deeper into the ComposeDB protocol and its components. 47 | 48 | ### [Community →](../ecosystem/community) 49 | Connect with the ComposeDB developer community. 50 | -------------------------------------------------------------------------------- /docs/introduction/did-overview.md: -------------------------------------------------------------------------------- 1 | # Decentralized Identifiers 2 | 3 | Cermic comes with a suite of tools and APIs to interact with and manage decentralized identifiers (DIDs). DIDs require no central authority - users control their data and whom they share it with. 4 | 5 | ## DID Methods 6 | We encourage using the did:pkh DID method which generates a persistent id from a wallet address’s public key hash. This enables one-click sign-on with your wallet to many apps on Ethereum, and soon on many other chains including Solana. We also support the Ceramic-created 3ID method which acts as an aggregator for multiple accounts and can handle multiple keys simulatneously. 7 | 8 | ## DID Sessions 9 | 10 | DID-Sessions is a library for providing a familiar, "web session"-like experience. Users no longer have to sign every single action they take within an app - during a timebound period of time they can authorize the app developer to act on their behalf. DID-Sessions outputs verifiable, serializable objects that store information about which DIDs authenticated them, what capabilities they are authorized with and for how long. 11 | 12 | -------------------------------------------------------------------------------- /docs/introduction/intro.md: -------------------------------------------------------------------------------- 1 | # The Composable Data Network 2 | 3 | Ceramic is a decentralized data network that powers an ecosystem of interoperable Web3 applications and services. Ceramic's event streaming protocol is a highly-scalable decentralized data infrastructure used for building all kinds of interoperable Web3 services and protocols, such as decentralized databases. Ceramic-powered databases and services enable thousands of Web3 developers to build data-intensive applications and solve the world's most complex data challenges. By decentralizing application databases, Ceramic makes data composable and reusable across all applications. 4 | 5 | ![Introduction](/img/ceramic-overview.png) 6 | 7 | 8 | ## Introduction to Ceramic 9 | --- 10 | 11 | - Head to the [**ComposeDB**](./composedb-overview.md) section to learn more about stream-level Ceramic functionality. 12 | 13 | - Head to the [**Ceramic Protocol**](./protocol-overview.md) section to learn about lower-level Ceramic functionality 14 | 15 | - Explore use cases and projects [**built on Ceramic**](https://threebox.notion.site/Ceramic-Ecosystem-a3a7a58f81544d33ad3feb84368775d4) 16 | 17 | ## Build Applications 18 | 19 | --- 20 | 21 | ### [**ComposeDB: Graph DB for Web3 Apps →**](../composedb/getting-started) 22 | 23 | ComposeDB is a decentralized graph database powered by Ceramic that enables you to build powerful Web3 applications using composable data, GraphQL, and reusable models. ComposeDB is the newest and most popular database built on Ceramic. 24 | 25 | ## Run a Ceramic Node 26 | 27 | --- 28 | 29 | Run a Ceramic node to provide data storage, compute, and bandwidth for your Ceramic application. Today there are no tokenized incentives for running a Ceramic node, but by running a node you can ensure the data for your app remains available while helping contribute to the network's decentralization. 30 | 31 | - [**Run Ceramic in the cloud**](../protocol/js-ceramic/guides/ceramic-nodes/running-cloud) 32 | 33 | - [**Run Ceramic locally**](../protocol/js-ceramic/guides/ceramic-nodes/running-locally) 34 | -------------------------------------------------------------------------------- /docs/introduction/protocol-overview.md: -------------------------------------------------------------------------------- 1 | 2 | # Ceramic Protocol 3 | 4 | Ceramic is a decentralized event streaming protocol that enables developers to build decentralized databases, distributed compute pipelines, and authenticated data feeds, etc. Ceramic nodes can subscribe to subsets of streams forgoing the need of a global network state. This makes Ceramic an eventually consistent system (as opposed to strongly consistent like L1 blockchains), enabling web scale applications to be built reliably. 5 | 6 | 7 | ## Core Components 8 | 9 | --- 10 | 11 | The Ceramic protocol consists of the following components: 12 | 13 | - [**Streams →**](../protocol/js-ceramic/streams/streams-index) 14 | - [**Accounts →**](../protocol/js-ceramic/accounts/accounts-index.md) 15 | - [**Networking →**](../protocol/js-ceramic/networking/networking-index.md) 16 | - [**Ceramic API →**](../protocol/js-ceramic/api.md) 17 | - [**Ceramic Nodes →**](../protocol/js-ceramic/nodes/overview.md) 18 | 19 | 20 | ## Specification Status 21 | 22 | --- 23 | 24 | | Section | State | 25 | | --- | --- | 26 | | [1. Streams](../protocol/js-ceramic/streams/streams-index) | **[Draft/WIP](../protocol/js-ceramic/streams/streams-index)** | 27 | | [1.1. Event Log](../protocol/js-ceramic/streams/event-log) | **[Reliable](../protocol/js-ceramic/streams/event-log)** | 28 | | [1.2. URI Scheme](../protocol/js-ceramic/streams/uri-scheme) | **[Reliable](../protocol/js-ceramic/streams/uri-scheme)** | 29 | | [1.3. Consensus](../protocol/js-ceramic/streams/consensus) | **[Draft/WIP](../protocol/js-ceramic/streams/consensus)** | 30 | | [1.4. Lifecycle](../protocol/js-ceramic/streams/lifecycle) | **[Reliable](../protocol/js-ceramic/streams/lifecycle)** | 31 | | [2. Accounts](../protocol/js-ceramic/accounts/accounts-index) | **[Draft/WIP](../protocol/js-ceramic/accounts/accounts-index)** | 32 | | [2.1. Decentralized Identifiers](../protocol/js-ceramic/accounts/decentralized-identifiers) | **[Draft/WIP](../protocol/js-ceramic/accounts/decentralized-identifiers)** | 33 | | [2.2. Authorizations](../protocol/js-ceramic/accounts/authorizations) | **[Reliable](../protocol/js-ceramic/accounts/authorizations)** | 34 | | [2.3. Object-Capabilities](../protocol/js-ceramic/accounts/object-capabilities) | **[Draft/WIP](../protocol/js-ceramic/accounts/object-capabilities)** | 35 | | [3. Networking](../protocol/js-ceramic/networking/networking-index) | **[Draft/WIP](../protocol/js-ceramic/networking/networking-index)** | 36 | | [3.1. Tip Gossip](../protocol/js-ceramic/networking/tip-gossip) | **[Reliable](../protocol/js-ceramic/networking/tip-gossip)** | 37 | | [3.2. Tip Queries](../protocol/js-ceramic/networking/tip-queries) | **[Reliable](../protocol/js-ceramic/networking/tip-queries)** | 38 | | [3.3. Event Fetching](../protocol/js-ceramic/networking/event-fetching) | **[Reliable](../protocol/js-ceramic/networking/event-fetching)** | 39 | | [3.4. Network Identifiers](../protocol/js-ceramic/networking/networks) | **[Reliable](../protocol/js-ceramic/networking/networks)** | 40 | | [4. API](../protocol/js-ceramic/api) | **[Missing](../protocol/js-ceramic/api)** | 41 | | [5. Nodes](../protocol/js-ceramic/nodes/overview) | **[Draft/WIP](../protocol/js-ceramic/nodes/overview)** | 42 | 43 | #### **Legend** 44 | 45 | | Spec state | Label | 46 | | --- | --- | 47 | | Unlikely to change in the foreseeable future. | **Stable** | 48 | | All content is correct. Important details are covered. | **Reliable** | 49 | | All content is correct. Details are being worked on. | **Draft/WIP** | 50 | | Do not follow. Important things have changed. | **Incorrect** | 51 | | No work has been done yet. | **Missing** | 52 | 53 | 54 | -------------------------------------------------------------------------------- /docs/introduction/why-ceramic.md: -------------------------------------------------------------------------------- 1 | # Why Ceramic? 2 | 3 | --- 4 | 5 | Ceramic's decentralized data network provides Web3 developers with a collection of features that make it possible to build scalable Web3 applications with composable data that can be reused and shared across applications. 6 | 7 | ## Overview 8 | 9 | Ceramic compared to other popular Web3 infrastructure solutions. 10 | 11 | | | Ceramic | L2s | L1s | Web2 DB | 12 | |---|---|---|---|---| 13 | |__UX__| 🟢 | 🔴 | 🔴 | 🟢 | 14 | |__Low Cost__| 🟢 | 🟡 | 🔴 | 🟢 | 15 | |__Web Scale__| 🟢 | 🟡 | 🔴 | 🟡 | 16 | |__Composability__| 🟢 | 🟡 | 🟢 | 🔴 | 17 | |__Verifiability__| 🟢 | 🟢 | 🟢 | 🔴 | 18 | |__Permissionless__| 🟢 | 🟢 | 🟢 | 🔴 | 19 | |__Designed for...__| Decentralized data | Decentralized finance | Decentralized finance | Centralized data | 20 | 21 | 22 | ## Key Benefits 23 | 24 | --- 25 | 26 | ### Mutable data storage 27 | Ceramic provides developers with a set of standard, open APIs for storing, updating, and retrieving data from the network. This helps to break down data silos, enabling all data to be openly accessible. Additionally, all data mutations on Ceramic are cryptographically verifiable and can provide auditability throughout all historical versions of a piece of data that has changed over time. 28 | 29 | ### Data Composability 30 | 31 | Data on Ceramic is structured and stored in data models, which can be easily reused by different applications to share 32 | data between them. Data models are created by developers in the community, and the ecosystem of data models is constantly expanding. Data models typically represent a single, logical application feature such as a user profile, a social graph, or a blog and developers typically combine multiple data models to create their application. 33 | 34 | ### Developer Experience 35 | 36 | Building composable applications with Web3 data on Ceramic is simple. Install Ceramic, browse the marketplace of data models, plug these models into your app, and automatically get access to all data stored on the network that conforms to those data models. The community is constantly creating new tooling that make it easier to build, and expand what's possible with composable data. 37 | 38 | ### Sign in with Web3 39 | 40 | Ceramic uses the decentralized identifier (DID) standard for user accounts, which are compatible with all blockchain wallets. When using Ceramic in your application, users can authenticate with the Web3 wallets they already have, and can even control the same Ceramic account from multiple different blockchain wallets (cross-chain) if they'd like. Data models are typically account-centric, meaning that every user is in control of their own data. 41 | 42 | ### Decentralization 43 | 44 | The Ceramic network is decentralized and permissionless, allowing anyone in the world to spin up a node to provide storage, compute, and bandwidth resources to users and applications built on the network. Today there are no tokenized incentives for running Ceramic, but the community is exploring options. 45 | 46 | ### Scalability 47 | 48 | Ceramic's data network infrastructure is highly-scalable and can service use cases where high amounts of data throughput is needed. On Ceramic, every data object maintains its own state and nodes independently process stream transactions, allowing unbounded parallelization. This enables Ceramic to operate at worldwide data scale, which is orders of magnitude greater than the scale needed for decentralized finance. -------------------------------------------------------------------------------- /docs/protocol/ceramic-one/README.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview 3 | description: 4 | Offchain event store for applications requiring mutable records or aggregations over streams. 5 | --- 6 | 7 | Ceramic is a decentralized data network provides web3 developers with a collection of features that 8 | make it possible to build scalable web3 applications with composable data that can be reused and 9 | shared across applications. Data written to Ceramic has the following unique properties: 10 | 11 | - **Verifiability**: All data written to Ceramic is signed by its author, meaning data on Ceramic is 12 | self-certifying and trustworthy. 13 | - **Composability**: Data in Ceramic is organized by [models](/docs/protocol/ceramic-one/concepts). 14 | When applications use the same data models, the data they create can be viewed as one, universal 15 | dataset. Ceramic makes it easy to compose data from distinct applications and users into a single, 16 | hackable dataset. 17 | - **Scalable**: Data in Ceramic is sharded by author by default. In exchange for giving up 18 | transactionality, Ceramic elegantly scales to massive datasets. 19 | - **Secure**: Ceramic gains a sense of time by anchoring its data to a blockchain, which allows 20 | Ceramic nodes to assert when data was created. Ceramic uses this sense of time to implement 21 | expiring user sessions, meaning one compromised session keypair doesn't permanently taint a user's 22 | identity. 23 | 24 | ## Contents 25 | 26 | - [Concepts](/docs/protocol/ceramic-one/concepts) 27 | - [Installation](/docs/protocol/ceramic-one/usage/installation) 28 | -------------------------------------------------------------------------------- /docs/protocol/ceramic-one/usage/consume.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Consume 3 | description: Consume events from a stream 4 | --- 5 | 6 | :::tip 7 | 8 | Just getting started? Check out our Getting Connected Guide to get your client setup This document 9 | assumes that you've already followed our 10 | [installation guide](/docs/protocol/ceramic-one/usage/installation) 11 | 12 | ::: 13 | 14 | Let's explore how use Ceramic to read messages from a stream. Nodes in the Ceramic Network 15 | subscribe to data by expressing an [interest](/docs/protocol/ceramic-one/concepts#interests) in a 16 | given data model. This interest is broadcast to the node's peers in the network, who will then 17 | initiate periodic synchronization of all data conforming to that model via [Recon](#), a protocol 18 | tailor-made for the efficient synchronization of large sets of events. 19 | 20 | ## Consuming events 21 | 22 | First, we'll learn how to register an interest. Then we'll learn how to read events matching our 23 | interests. Finally, we'll learn about some extra methods to fetch specific events from your 24 | ceramic-one node. 25 | 26 | ### `registerInterestModel` 27 | 28 | This method allows end users to register interest in a specific data model within the Ceramic 29 | network. The model's identifier is, itself, the ID of a stream that defines its schema. 30 | 31 | ```typescript 32 | import { CeramicClient, EventsFeedParams } from "@ceramic-sdk/http-client"; 33 | 34 | const ceramic = new CeramicClient({ url: "http://localhost:5101" }); 35 | 36 | // My model stream ID 37 | const modelId = "kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65"; 38 | 39 | // Listen to all events written to instances of this modela 40 | await ceramic.registerInterestModel(modelId); 41 | ``` 42 | 43 | Upon success, the function won't return anything, but it will throw if there's an issue. You're now 44 | ready to read events from streams tied to this schema! 45 | 46 | ### `getEventsFeed` 47 | 48 | This method allows users to poll for new events that match their interests. It follows a typical 49 | pagination screen, in which users may specify `limit`, the maxinum number of results to return in a 50 | given query, and `resumeAt` an opaque token that the ceramic-one node can use to determine where the 51 | user left off in their last read. 52 | 53 | ### Prepare your request parameters 54 | 55 | Let's assume I want to read 50 events matching my interests. Both of these parameters are optional, 56 | but we'll define them to illustrate their purpose. If no limit is defined, the SDK will retrieve all 57 | new events from the resume token. 58 | 59 | ```typescript 60 | const params: EventsFeedParams = { 61 | limit: 50, 62 | resumeAt: "0", // The resumeToken returned from the last call to `getEventsFeed` 63 | }; 64 | ``` 65 | 66 | ### Get a batch of events 67 | 68 | ```typescript 69 | const events = await ceramic.getEventsFeed(params); 70 | ``` 71 | 72 | If there is an issue, `getEventsFeed` will throw. Otherwise, you'll get an object shaped like this: 73 | 74 | ```typescript 75 | type EventsFeed = { 76 | events: { 77 | id: string; 78 | data?: string; 79 | }[]; 80 | resumeToken: string; 81 | }; 82 | ``` 83 | 84 | ### Getting individual events 85 | 86 | Ceramic also offers a handful of simple APIs to fetch individual events from your ceramic-one node. 87 | 88 | #### `getEvent` 89 | 90 | This is the most straightforward of the event fetching methods. It returns an event of the form: 91 | 92 | ```typescript 93 | type Event = { 94 | id: string; 95 | data?: string; 96 | }; 97 | ``` 98 | 99 | To fetch an event by its id, we use `getEvent`: 100 | 101 | ```typescript 102 | const eventId = events.events[0].id; // The ID of the event we want to fetch 103 | const event = await ceramic.getEvent(eventId); 104 | ``` 105 | 106 | There are also a small collection of simple helper functions to extract specific parts of an event. 107 | 108 | #### `getEventData` 109 | 110 | Extract the data payload from an event. 111 | 112 | ```typescript 113 | const data = await ceramic.getEventData(eventId); 114 | ``` 115 | 116 | This is equivalent to: 117 | 118 | ```typescript 119 | ceramic.getEvent(eventId).then((event) => event.data); 120 | ``` 121 | 122 | #### `getEventCAR` 123 | 124 | Extract the data payload from an event and parse it as a CAR file. 125 | 126 | ```typescript 127 | const data = await ceramic.getEventCAR(eventId); 128 | ``` 129 | 130 | `data` will be the parsed payload of the event. 131 | 132 | #### `getEventType` 133 | 134 | This method is useful for cases where you know the schema of the payload. To use it, you must have the 135 | [codeco](https://github.com/ceramicnetwork/codeco) package and your codec handy. 136 | 137 | ```bash 138 | npm install --save codeco 139 | ``` 140 | 141 | Then, you can use it like this: 142 | 143 | ```typescript 144 | import { Decoder } from "codeco"; 145 | 146 | type MyPayload = /* ... */; 147 | const decoder: Decoder = /* ... */; 148 | 149 | const data: MyPayload = await ceramic.getEventType(decoder, eventId); 150 | ``` 151 | -------------------------------------------------------------------------------- /docs/protocol/ceramic-one/usage/installation.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Installation 3 | description: Getting started with the Ceramic SDK. 4 | --- 5 | 6 | The [Ceramic SDK](https://github.com/ceramicstudio/ceramic-sdk) enables user to interact with the 7 | Ceramic's primitive APIs for creating streams as well as producing events on streams, consuming 8 | events from streams, and aggregating stream state. Find it on GitHub at 9 | https://github.com/ceramicstudio/ceramic-sdk. 10 | 11 | The SDK is written in TypeScript and published to NPM as `@ceramic-sdk`, with a handful of useful 12 | sub-packages: 13 | 14 | - `@ceramic-sdk/events`: Utilities for creating and signing events that comply to the 15 | [Ceramic Event Log specifications](https://developers.ceramic.network/docs/protocol/js-ceramic/streams/event-log) 16 | - `@ceramic-sdk/http-client`: A simple client for 17 | [ceramic-one's](https://github.com/ceramicnetwork/rust-ceramic) HTTP APIs. 18 | - `@ceramic-sdk/identifiers`: A handful of useful types for identifying streams and events. 19 | - `@ceramic-sdk/model-client`: A client that handles the creation and fetching of model stream 20 | types. 21 | - `@ceramic-sdk/model-instance-client`: A client that handles the creation and fetching of model 22 | instance document stream types. 23 | 24 | :::tip While Ceramic will eventually support a wide array of different stream types, this guide will 25 | focus on the use of models and model instance documents given they represent the predominant pattern 26 | developers currently use when interacting with the network. ::: 27 | 28 | The Ceramic SDK needs a [ceramic-one](https://github.com/ceramicnetwork/rust-ceramic) daemon to 29 | connect to. 30 | 31 | Let's get them all installed! 32 | 33 | ### Install ceramic-one 34 | 35 | ceramic-one can run on macOS, Linux, or from within a docker container. 36 | 37 | #### MacOS 38 | 39 | Install from [Homebrew](https://brew.sh/): 40 | 41 | ```bash 42 | brew install ceramicnetwork/tap/ceramic-one 43 | ``` 44 | 45 | #### Linux (Debian-based distributions) 46 | 47 | Install a the latest release using dpkg: 48 | 49 | ```bash 50 | # get deb.tar.gz 51 | curl -LO https://github.com/ceramicnetwork/rust-ceramic/releases/download/latest/ceramic-one_x86_64-unknown-linux-gnu.tar.gz 52 | # untar the Debian software package file 53 | tar zxvf ceramic-one_x86_64-unknown-linux-gnu.tar.gz 54 | # install with dpkg - package manager for Debian 55 | dpkg -i ceramic-one.deb 56 | ``` 57 | 58 | #### Linux (from Source) 59 | 60 | ```bash 61 | # Install rust 62 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 63 | # Install build tools 64 | apt-get install -y build-essential pkg-config openssl libssl-dev unzip 65 | # Update environment 66 | source "$HOME/.cargo/env" 67 | # Install protobuf 68 | PROTOC_VERSION=3.20.1 69 | PROTOC_ZIP=protoc-$PROTOC_VERSION-linux-x86_64.zip 70 | curl --retry 3 --retry-max-time 90 -OL https://github.com/protocolbuffers/protobuf/releases/download/v$PROTOC_VERSION/$PROTOC_ZIP \ 71 | && unzip -o $PROTOC_ZIP -d /usr/local bin/protoc \ 72 | && unzip -o $PROTOC_ZIP -d /usr/local 'include/*' \ 73 | && rm -f $PROTOC_ZIP 74 | # Checkout rust-ceramic repo 75 | git clone https://github.com/ceramicnetwork/rust-ceramic 76 | # Enter repo and build 77 | cd rust-ceramic 78 | make build 79 | cp ./target/release/ceramic-one /usr/local/bin/ceramic-one 80 | ``` 81 | 82 | #### Docker 83 | 84 | Start rust-ceramic using the host network: 85 | 86 | ```bash 87 | docker run --network=host \ 88 | public.ecr.aws/r5b3e0r5/3box/ceramic-one:latest 89 | ``` 90 | 91 | #### Docker-Compose 92 | 93 | 1. Create a testing directory, and enter it: 94 | 95 | ```bash 96 | mkdir ceramic-recon 97 | cd ceramic-recon 98 | ``` 99 | 100 | 2. Save the following docker-compose.yaml there: 101 | 102 | ```YAML 103 | version: '3.8' 104 | 105 | services: 106 | ceramic-one: 107 | image: public.ecr.aws/r5b3e0r5/3box/ceramic-one:latest 108 | network_mode: "host" 109 | volumes: 110 | - ceramic-one-data:/root/.ceramic-one 111 | volumes: 112 | ceramic-one-data: 113 | driver: local 114 | ``` 115 | 116 | 3. Run `docker-compose up -d` 117 | 118 | ### Run the ceramic-one daemon 119 | 120 | ```bash 121 | # if necessary, include the path/to/the/binary e.g. /usr/local/bin/ceramic-one or ./target/release/ceramic-one 122 | $ ceramic-one daemon 123 | 124 | # There are many flags for the daemon CLI that can be passed directly or set as environment variables. 125 | # See `DaemonOpts` in one/src/lib.rs for the complete list or pass the -h flag 126 | $ ceramic-one daemon -h 127 | 128 | # A few common options are overriding the log level: 129 | $ RUST_LOG=warn,ceramic_one=info,ceramic_service=debug ceramic-one daemon 130 | # Or modifying the network 131 | $ ceramic-one daemon --network testnet-clay 132 | $ ceramic-one daemon --network local --local-network-id 0 133 | # Or changing where directory where all data is stored. This folder SHOULD be backed up in production 134 | # and if you change the defaults, you MUST specify it every time you start the daemon. 135 | $ ceramic-one daemon --store-dir ./custom-store-dir 136 | ``` 137 | 138 | ### Add client packages to your project 139 | 140 | ```bash 141 | npm install --save @ceramic-sdk/events @ceramic-sdk/identifiers @ceramic-sdk/http-client 142 | ``` 143 | 144 | ### Set up your client 145 | 146 | ```typescript 147 | import { CeramicClient } from "@ceramic-sdk/http-client"; 148 | 149 | const client = new CeramicClient({ url: "http://localhost:5101" }); 150 | 151 | // Now some calls! 152 | const response = await client.getVersion(); 153 | 154 | // Confirm it matches the version you just installed 155 | console.log(response.version); 156 | ``` 157 | -------------------------------------------------------------------------------- /docs/protocol/ceramic-one/usage/query.mdx: -------------------------------------------------------------------------------- 1 | --- 2 | title: Query the pipeline 3 | description: Query table states across Ceramic's data pipeline. 4 | --- 5 | 6 | :::tip 7 | 8 | This document assumes that you've already followed our 9 | [installation guide](/docs/protocol/ceramic-one/usage/installation). 10 | 11 | ::: 12 | 13 | Streaming systems are invaluable in modern data architectures due to their ability to process and 14 | analyze data in real-time as it flows through a system. One of the primary use cases that makes 15 | streaming systems so powerful is aggregation. By continuously processing incoming events, streaming 16 | systems allow for the dynamic creation and updating of table views, providing up-to-the-moment 17 | insights without the need for batch processing. 18 | 19 | This real-time data transformation capability enables applications to maintain live dashboards, 20 | detect anomalies instantly, and make data-driven decisions with minimal latency. Ceramic offers a 21 | powerful data pipeline suitable for a variety of workloads. 22 | 23 | ## Flight SQL library 24 | 25 | Flight SQL is a protocol designed efficiently handling and querying large-scale analytical data by 26 | extending [Apache Arrow Flight](https://arrow.apache.org/blog/2019/10/13/introducing-arrow-flight/), 27 | an RPC protocol built for high-performance data transfer in big data application settings. 28 | 29 | Ceramic nodes expose a Flight SQL endpoint which allows developers to query the various parquet 30 | tables across the Ceramic data pipeline. 31 | 32 | ### Why Flight SQL? 33 | 34 | Flight SQL organizes data into columnar format for fast, memory-efficient data handling, thus 35 | reducing the amount of time needed to serialize, deserialize, and transfer data between clients and 36 | servers. At the same time, Flight SQL supports SQL queries, making it highly useful for applications 37 | requiring SQL analytics. 38 | 39 | Since Flight SQL's protocol is tailored for high-throughput data transport across networks, this 40 | makes it ideal for moving large, columnar data (like Parquet) over the network between distributed 41 | systems. Furthermore, Parquet data can be loaded into an Arrow-based in-memory format and then 42 | queried and transmitted efficiently, ideal for intense data workloads. 43 | 44 | ## Set up your client 45 | 46 | The `@ceramic-sdk/flight-sql-client` is a package designed to run server-side only. Using this 47 | client needs a [ceramic-one](https://github.com/ceramicnetwork/rust-ceramic) daemon running with 48 | experimental flags which point to your S3 bucket: 49 | 50 | ```bash 51 | ceramic-one -- daemon --experimental-features --flight-sql-bind-address 0.0.0.0:5102 --object-store-url s3://your-bucket-name 52 | ``` 53 | 54 | ### Install the flight-sql package 55 | 56 | ```bash 57 | npm install --save @ceramic-sdk/flight-sql-client apache-arrow 58 | ``` 59 | 60 | ### Create a client instance 61 | 62 | ```typescript 63 | import { ClientOptions, createFlightSqlClient } from "@ceramic-sdk/flight-sql-client"; 64 | import { tableFromIPC } from "apache-arrow"; 65 | 66 | const OPTIONS: ClientOptions = { 67 | headers: new Array(), 68 | username: undefined, 69 | password: undefined, 70 | token: undefined, 71 | tls: false, 72 | host: "127.0.0.1", 73 | port: 5102, 74 | }; 75 | 76 | const client = await createFlightSqlClient(OPTIONS); 77 | ``` 78 | 79 | ### Execute a query 80 | 81 | ```typescript 82 | const buffer = await client.preparedQuery( 83 | "SELECT * from conclusion_events where stream_type = $1", 84 | new Array(["$1", "3"]) 85 | ); 86 | 87 | // deserialize the IPC format into a table 88 | const data = tableFromIPC(buffer); 89 | const row = data.get(0); 90 | 91 | // data will be stored as bytes - transform to readable 92 | const content = JSON.parse(Buffer.from(row?.data).toString()); 93 | console.log(content); 94 | ``` 95 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/accounts/accounts-index.md: -------------------------------------------------------------------------------- 1 | # Accounts 2 | --- 3 | 4 | User-owned Ceramic accounts 5 | 6 | ### Overview 7 | 8 | User owned data requires an account model that is both core to the protocol and general enough to support the wide diversity of possible account models and real world scenarios. Accounts are identified by Decentralized Identifiers, a general and extensible method to represent unique account strings, resolve public keys, and other account info or key material. Object-Capabilities are used to permission and authorize stream writes from one account to another, this may include session keys, applications and managing organization access. 9 | 10 | ### [Decentralized Identifiers](decentralized-identifiers.md) 11 | 12 | Decentralized Identifiers (DIDs) are used to represent accounts. DIDs are identifiers that enable verifiable, decentralized digital identities. They require no centralized party or registry and are extremely extensible, allowing a variety of implementations and account models to exist. 13 | 14 | ### [Authorizations](authorizations.md) 15 | 16 | Authorizations allow one account to delegate stream access to another account. While the current model is simple and minimal, it is descriptive enough to follow the rule of least privilege and limit the access that is delegated to another account. 17 | 18 | ### [Object Capabilities](object-capabilities.md) 19 | 20 | Object Capabilities or CACAO are the technical feature and implementation that enables support for permissions and a general and powerful capability-based authorization system over streams. -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/accounts/authorizations.md: -------------------------------------------------------------------------------- 1 | # Authorizations 2 | --- 3 | 4 | Authorization is the act of delegating access to a stream to an account that is different than its owner. As a best practice, when granting authorizations to another account you want to follow the rule of least privilege and only authorize that delegate's temporary key to write the minimally needed data to Ceramic. 5 | 6 | ## Scopes 7 | 8 | --- 9 | 10 | CACAO and Ceramic support a basic way to describe the resources and actions an authorization includes. The resource parameter is an array of strings. In Ceramic those strings are StreamIDs or model StreamIDs. The implied action is write access, as read access is not authorized in any way at the protocol level. Read access would require an encryption protocol, as streams are public, and is out of scope for now. 11 | 12 | :::note 13 | In the future, we expect the ability to specify more granular authorizations based on actions (write, delete, create, update etc) and resources. 14 | ::: 15 | 16 | ### Streams 17 | 18 | For example, to authorize an account to write to only two specific streams, you would specify the streamIds as resources in the CACAO as follows: 19 | 20 | ```bash 21 | [ "ceramic://kjzl6cwe1jw14bby1eybtqjr1w5l8xysitwmd34i8huccr7lk8g6xrt2l1c1ngn", "ceramic://kjzl6cwe1jw1476bbp2a0lg8gcmk9zj1xjanpg6dooc3golyb2fnmwmg0p6ane3"] 22 | ``` 23 | 24 | ### Models 25 | 26 | The mostly commonly used pattern is to specify authorizations by model streamIds. `model` is a property that can be defined in a streams init event. When specified and used with CACAO it allows a DID and key the ability to write to all streams with this specific model value for that user. 27 | 28 | :::note 29 | Ceramic will likely support other keys and values in streams beyond `model` for authorizations in the future. 30 | ::: 31 | 32 | Models at the moment are primarily used as higher level concept built on top of Ceramic. A set of models will typically describe the entire write data-model of an application, making it a logical way for a user to authorize an application to write to all streams that is needed for that application. 33 | 34 | For example, a simple social application with a user profile and posts would have two corresponding models, a profile model and a post model. The CACAO would have the resources specified by an array of both model streamIds, shown below. This would allow a DID with this CACAO to create and write to any stream with these models. Allowing it to create as many posts as necessary. 35 | 36 | Resources defined by model streamID are formatted as `ceramic://*?model=` and would be defined as follows for the prior example. 37 | 38 | ```bash 39 | [ "ceramic://*?model=kjzl6hvfrbw6c7keo17n66rxyo21nqqaa9lh491jz16od43nokz7ksfcvzi6bwc", "ceramic://*?model=kjzl6hvfrbw6c99mdfpjx1z3fue7sesgua6gsl1vu97229lq56344zu9bawnf96"] 40 | ``` 41 | 42 | ### Wildcard 43 | 44 | Lastly a wildcard for all resources is supported. For security reasons, wildcard will be deprecated in the future and is only included here for completeness. 45 | 46 | ```bash 47 | [ "ceramic://*" ] 48 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/accounts/decentralized-identifiers.md: -------------------------------------------------------------------------------- 1 | # Identifiers 2 | --- 3 | 4 | Ceramic streams rely on an account model to authenticate and authorize updates to a stream. A fully realized vision of user owned data includes the use of public key cryptography and the ability to sign data with a public-private key-pair controlled by a user. But key pairs alone are often not user friendly nor sufficient and don't fully represent the range of real world scenarios. 5 | 6 | ## Decentralized Identifiers (DIDs) 7 | 8 | --- 9 | 10 | Ceramic uses [Decentralized Identifiers (DIDs)](https://w3c.github.io/did-core/) to represent accounts. DIDs are identifiers that enable verifiable, decentralized digital identities. They require no centralized party or registry and are extremely extensible, allowing a variety of implementations and account models to exist. 11 | 12 | DID methods are specific implementations of the DID standard that define an identifier namespace along with how to resolve its DID document, which typically stores public keys for signing and encryption. The ability to resolve public keys from identifiers allows anyone to verify a signature for a DID. 13 | 14 | ## Supported Methods 15 | 16 | --- 17 | 18 | At this time, the following DID methods can be used with Ceramic: 19 | 20 | ### PKH DID 21 | 22 | **PKH DID Method**: A DID method that natively supports blockchain accounts. DID documents are statically generated from a blockchain account, allowing blockchain accounts to sign, authorize and authenticate in DID based environments. PKH DID is the primary and recommended method in Ceramic. [did:pkh Method Specification](https://github.com/w3c-ccg/did-pkh/blob/main/did-pkh-method-draft.md) 23 | 24 | ```bash 25 | did:pkh:eip155:1:0xb9c5714089478a327f09197987f16f9e5d936e8a 26 | ``` 27 | 28 | ### Key DID 29 | 30 | **Key DID Method**: A DID method that expands a cryptographic public key into a DID Document, with support for Ed25519 and Secp256k1. Key DIDs are typically not used in long lived environments. [did:key Method Specification](https://w3c-ccg.github.io/did-method-key/) 31 | 32 | ```bash 33 | did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK 34 | ``` 35 | 36 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/api.md: -------------------------------------------------------------------------------- 1 | # Ceramic API 2 | --- 3 | The new and improved Ceramic API is a work in progress. We will update this page when it's available. In the meantime, have a look at the [HTTP API](./guides/ceramic-clients/javascript-clients/ceramic-http.md) that's implemented by the current JS Ceramic implementation. 4 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/authentication/key-did.md: -------------------------------------------------------------------------------- 1 | # Key DID libraries 2 | 3 | --- 4 | 5 | The Key DID libraries include the [resolver](#key-did-resolver) and [multiple providers](#key-did-providers) to provide a simple way for developers to get started using the [DID client](./did-jsonrpc.md) with the `did:key` method. 6 | 7 | ## Available libraries 8 | 9 | --- 10 | 11 | - The [Key DID resolver](#key-did-resolver) allows a DID JSON-RPC client to resolve accounts using the `did:key` method 12 | - The [Key DID provider ED25519](#key-did-provider-ed25519) allows applications to create and use Key DID accounts for ED25519 keypairs. This provider supports encryption. 13 | - The [Key DID provider secp256k1](#key-did-provider-secp256k1) allows applications to create and use Key DID accounts for secp256k1 keypairs. This provider does not supports encryption. 14 | 15 | ## Key DID resolver 16 | 17 | --- 18 | 19 | The `key-did-resolver` module is needed to resolve DID documents using the `did:key` method. 20 | 21 | ### Installation 22 | 23 | ```sh 24 | npm install key-did-resolver 25 | ``` 26 | 27 | ### Usage 28 | 29 | ```ts 30 | import { DID } from 'dids' 31 | import { getResolver } from 'key-did-resolver' 32 | 33 | async function resolveDID() { 34 | const did = new DID({ resolver: getResolver() }) 35 | return await did.resolve('did:key:...') 36 | } 37 | ``` 38 | 39 | ## Key DID providers 40 | 41 | --- 42 | 43 | Different libraries implement a provider for the `did:key` method based on different cryptographic primitives. These providers may have different possibilities, for example `key-did-provider-ed25519` supports encryption while `key-did-provider-secp256k1` does not. 44 | 45 | ## Key DID provider ED25519 46 | 47 | --- 48 | 49 | This is the **recommended provider** for the `key:did` method in most cases. 50 | 51 | ### Installation 52 | 53 | ```sh 54 | npm install key-did-provider-ed25519 55 | ``` 56 | 57 | ### Usage 58 | 59 | ```ts 60 | import { DID } from 'dids' 61 | import { Ed25519Provider } from 'key-did-provider-ed25519' 62 | import { getResolver } from 'key-did-resolver' 63 | 64 | // `seed` must be a 32-byte long Uint8Array 65 | async function authenticateDID(seed) { 66 | const provider = new Ed25519Provider(seed) 67 | const did = new DID({ provider, resolver: getResolver() }) 68 | await did.authenticate() 69 | return did 70 | } 71 | ``` 72 | 73 | ## Key DID provider secp256k1 74 | 75 | --- 76 | 77 | This provider *does not support encryption*, so using methods such as `createJWE` on the `DID` instance is not supported. 78 | 79 | ### Installation 80 | 81 | ```sh 82 | npm install key-did-provider-secp256k1 83 | ``` 84 | 85 | ### Usage 86 | 87 | ```ts 88 | import { DID } from 'dids' 89 | import { Secp256k1Provider } from 'key-did-provider-secp256k1' 90 | import { getResolver } from 'key-did-resolver' 91 | 92 | // `seed` must be a 32-byte long Uint8Array 93 | async function authenticateDID(seed) { 94 | const provider = new Secp256k1Provider(seed) 95 | const did = new DID({ provider, resolver: getResolver() }) 96 | await did.authenticate() 97 | return did 98 | } 99 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/clients-overview.md: -------------------------------------------------------------------------------- 1 | # Clients 2 | 3 | ### Ceramic clients 4 | 5 | Ceramic clients are libraries that allow your application to communicate with a Ceramic node. Different clients may choose to implement different high-level, language-specific developer APIs. Before submitting requests to a Ceramic node, clients translate those API calls into the standard [Ceramic HTTP API](./javascript-clients/ceramic-http.md), which it uses to actually communicate with a Ceramic node. 6 | 7 | ### Account clients 8 | 9 | Account clients are libraries that allow your application to recognize users, authenticate, and perform other account-related functionality such as signing transactions and encrypting data. 10 | 11 | ## Available clients 12 | 13 | --- 14 | 15 | When building with Ceramic clients, be sure to install both a Ceramic client and an account client. 16 | 17 | ### [**JS Ceramic HTTP Client →**](./javascript-clients/ceramic-http.md) 18 | 19 | The Ceramic JS HTTP client is a Ceramic client that can be used in browsers and Node.js environments to connect your application to a Ceramic node. It is actively maintained by 3Box Labs and supports the latest Ceramic features. This is the recommended Ceramic client to build with for most applications. 20 | 21 | 24 | 25 | ### [DID JSON-RPC Client →](./authentication/did-jsonrpc.md) 26 | 27 | The DID JSON-RPC Client is an account client that provides a simple JS API for interacting with Ceramic accounts. It is actively maintained by 3Box Labs and supports all account types. -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/javascript-clients/ceramic-http.md: -------------------------------------------------------------------------------- 1 | # Ceramic HTTP client 2 | 3 | The Ceramic HTTP client library can be used in browsers and Node.js to connect your application to a Ceramic node. It is actively maintained and supports the latest Ceramic features. 4 | 5 | ![Verse](/img/verse.png) 6 | 7 | ## Things to know 8 | 9 | 10 | - The client is read-only by default, to enable transactions a [DID client](../authentication//did-jsonrpc.md) needs to be attached to the Ceramic client instance. 11 | - Ceramic streams can be identified by a **stream ID** or a **commit ID**. A **stream ID** is generated when creating the stream and can be used to load the **latest version** of the stream, while a **commit ID** represents a **specific version** of the stream. 12 | 13 | ## Installation 14 | 15 | ```bash 16 | npm install @ceramicnetwork/http-client 17 | ``` 18 | 19 | 30 | 31 | ## Common use-cases 32 | 33 | ### Load a single stream 34 | 35 | ```ts 36 | // Import the client 37 | import { CeramicClient } from '@ceramicnetwork/http-client' 38 | 39 | // Connect to a Ceramic node 40 | const ceramic = new CeramicClient('https://your-ceramic-node.com') 41 | 42 | // The `id` argument can be a stream ID (to load the latest version) 43 | // or a commit ID (to load a specific version) 44 | async function load(id) { 45 | return await ceramic.loadStream(id) 46 | } 47 | ``` 48 | 49 | ### Load multiple streams 50 | 51 | Rather than using the `loadStream` method multiple times with `Promise.all()` to load multiple streams at once, a **more efficient way for loading multiple streams** is to use the `multiQuery` method. 52 | 53 | ```ts 54 | // Import the client 55 | import { CeramicClient } from '@ceramicnetwork/http-client' 56 | 57 | // Connect to a Ceramic node 58 | const ceramic = new CeramicClient('https://your-ceramic-node.com') 59 | 60 | // The `ids` argument can contain an array of stream IDs (to load the latest version) 61 | // or commit IDs (to load a specific version) 62 | async function loadMulti(ids = []) { 63 | const queries = ids.map((streamId) => ({ streamId })) 64 | // This will return an Object of stream ID keys to stream values 65 | return await ceramic.multiQuery(queries) 66 | } 67 | ``` 68 | 69 | ### Enable transactions 70 | 71 | In order to create and update streams, the Ceramic client instance must be able to sign transaction payloads by using an authenticated DID instance. The [DID client documentation](../authentication//did-jsonrpc.md) describes the process of authenticating and attaching a DID instance to the Ceramic instance. 72 | 73 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/javascript-clients/pinning.md: -------------------------------------------------------------------------------- 1 | # Pinning 2 | 3 | Pinning allows you to persist and make streams available on a Ceramic node beyond a single session. This guide demonstrates how to add and remove streams from your node's pinset, and how to list the streams currently in the pinset. In order to interact with a pinset, you must have [installed a Ceramic client](./ceramic-http.md). 4 | 5 | ## Overview 6 | 7 | By default Ceramic will garbage collect any stream that has been written or [queried](./queries.md) on your node after some period of time. In order to prevent the loss of streams due to garbage collection, you need to explicitly pin the streams that you wish to persist. Pinning instructs the node to keep them around in persistent storage until they are explicitly unpinned. 8 | 9 | ## **Pin a stream while creating it** 10 | 11 | Most StreamTypes will allow you to request that a Stream be pinned at the same time that you create the Stream. An example using the TileDocument Streamtype is below: 12 | 13 | ```javascript 14 | await TileDocument.create(ceramic, content, null, { pin: true }) 15 | ``` 16 | 17 | ## **Add to pinset** 18 | 19 | Use the `pin.add()` method to add an existing stream to your permanent pinset. 20 | 21 | ```javascript 22 | const streamId = 'kjzl6cwe1jw14...' 23 | await ceramic.admin.pin.add(streamId) 24 | ``` 25 | 26 | 27 | ## **Remove from pinset** 28 | 29 | Use the `pin.rm()` method to remove a stream from your permanent pinset. 30 | 31 | ```javascript 32 | const streamId = 'kjzl6cwe1jw14...' 33 | await ceramic.admin.pin.rm(streamId) 34 | ``` 35 | 36 | 37 | ## **List streams in pinset** 38 | 39 | Use the `pin.ls()` method to list streams currently in your permanent pinset. 40 | 41 | ```javascript 42 | const streamIds = await ceramic.admin.pin.ls() 43 | ``` 44 | 45 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/javascript-clients/queries.md: -------------------------------------------------------------------------------- 1 | # Queries 2 | 3 | This guide demonstrates how to query streams during runtime using the [JS HTTP](./ceramic-http.md) and JS Core clients. 4 | 5 | ## **Requirements** 6 | 7 | You need to have an [installed client](./ceramic-http.md) to perform queries during runtime. 8 | 9 | ## **Query a stream** 10 | 11 | Use the `loadStream()` method to load a single stream using its _StreamID_. 12 | 13 | ```javascript 14 | const streamId = 'kjzl6cwe1jw14...' 15 | const stream = await ceramic.loadStream(streamId) 16 | ``` 17 | 18 | :::caution 19 | 20 | When using the Typescript APIs, `loadStream` by default returns an object of type `Stream`, which will not have any methods available to perform updates, or any other streamtype-specific methods or accessors. To be able to perform updates, as well as to access streamtype-specific data or functionality, you need to specialize the `loadStream` method on the StreamType of the Stream being loaded. 21 | ::: 22 | 23 | 24 | ## **Query a stream at a specific commit** 25 | 26 | If you want to see the contents of a stream as of a specific point in time, it's possible to pass a _CommitID_ instead of a _StreamID_ to the `loadStream()` method described above. This will cause the Stream to be loaded at the specified commit, rather than the current commit as loaded from the network. When loading with a CommitID, the returned Stream object will be marked as readonly and cannot be used to perform updates. If you wish to perform updates, load a new instance of the Stream using its StreamID. 27 | 28 | ## **Query multiple streams** 29 | 30 | Use the `multiQuery()` method to load multiple streams at once. The returned object is a map from _StreamIDs_ to stream instances. 31 | 32 | ```javascript 33 | const queries = [ 34 | { 35 | streamId: 'kjzl6cwe1jw...14', 36 | }, 37 | { 38 | streamId: 'kjzl6cwe1jw...15', 39 | }, 40 | ] 41 | const streamMap = await ceramic.multiQuery(queries) 42 | ``` 43 | 44 | 45 | ## **Query a stream using paths** 46 | 47 | Use the `multiQuery()` method to load one or more streams using known paths from a root stream to its linked streams. 48 | 49 | Imagine a stream `kjzl6cwe1jw...14` whose content contains the StreamIDs of two other streams. These StreamIDs exist at various levels within a nested JSON structure. 50 | 51 | ```javascript 52 | { 53 | a: 'kjzl6cwe1jw...15', 54 | b: { 55 | c: 'kjzl6cwe1jw...16' 56 | } 57 | } 58 | ``` 59 | 60 | In the stream above, the path from root stream `kjzl6cwe1jw...14` to linked stream `kjzl6cwe1jw...15` is `/a` and the path to linked stream `kjzl6cwe1jw...16` is `/b/c`. Using the StreamID of the root stream and the paths outlined here, we use `multiQuery()` to query all three streams at once without needing to explicitly know the StreamIDs of the two linked streams. 61 | 62 | The `multiQuery()` below will return a map with all three streams. 63 | 64 | ```javascript 65 | const queries = [{ 66 | streamId: 'kjzl6cwe1jw...14' 67 | paths: ['/a', '/b/c'] 68 | }] 69 | const streamMap = await ceramic.multiQuery(queries) 70 | ``` 71 | 72 | 73 | ## **Helper methods** 74 | 75 | To get specific information about the stream that you created or loaded you can use the accessors on the `Stream` class. Below are some examples. 76 | 77 | 78 | 79 | ### Get StreamID 80 | 81 | Use the `stream.id` property to get the unique `StreamID` for this stream. 82 | 83 | ```javascript 84 | const streamId = stream.id 85 | ``` 86 | 87 | 88 | 89 | ### Get latest commit 90 | 91 | Use the `stream.commitId` property to get latest CommitID of a stream. 92 | 93 | ```javascript 94 | const commitId = stream.commitId 95 | ``` 96 | 97 | 98 | 99 | ### Get all anchor commits 100 | 101 | Use the `stream.anchorCommitIds` property to get all CommitIDs which are anchor commits for this stream. 102 | 103 | ```javascript 104 | const anchorCommits = stream.anchorCommitIds 105 | ``` 106 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-clients/stream-api/caip10-link.md: -------------------------------------------------------------------------------- 1 | # CAIP-10 Link client 2 | 3 | --- 4 | 5 | A CAIP-10 Link is a stream that stores a proof that links a blockchain address to a Ceramic account (DID), using the [CAIP-10 standard](https://github.com/ChainAgnostic/CAIPs/blob/master/CAIPs/caip-10.md) to represent blockchain addresses. 6 | 7 | 8 | ## Installation 9 | 10 | --- 11 | 12 | ```sh 13 | npm install @ceramicnetwork/stream-caip10-link 14 | ``` 15 | 16 | ### Additional requirements 17 | 18 | - In order to load CAIP-10 Links, a [Ceramic client instance](../javascript-clients/ceramic-http.md) must be available 19 | - To add/remove links, the client must also have an [authenticated DID](../authentication/did-jsonrpc.md) 20 | - An authentication provider is needed to sign the payload for the given CAIP-10 account, using the `blockchain-utils-linking` module that should be installed as needed: 21 | 22 | ```sh 23 | npm install @ceramicnetwork/blockchain-utils-linking 24 | ``` 25 | 26 | ## Common usage 27 | 28 | --- 29 | 30 | ### Load a link 31 | 32 | In this example we load a Caip10Link for the account `0x054...7cb8` on the Ethereum mainnet blockchain (`eip155:1`). 33 | 34 | ```ts 35 | import { CeramicClient } from '@ceramicnetwork/http-client' 36 | import { Caip10Link } from '@ceramicnetwork/stream-caip10-link' 37 | 38 | const ceramic = new CeramicClient() 39 | 40 | async function getLinkedDID() { 41 | // Using the Ceramic client instance, we can load the link for a given CAIP-10 account 42 | const link = await Caip10Link.fromAccount( 43 | ceramic, 44 | '0x0544dcf4fce959c6c4f3b7530190cb5e1bd67cb8@eip155:1', 45 | ) 46 | // The `did` property of the loaded link will contain the DID string value if set 47 | return link.did 48 | } 49 | ``` 50 | 51 | ### Create a link 52 | 53 | Here we can see the full flow of getting a user's Ethereum address, creating a link, and adding the users' DID account. 54 | 55 | In this example we create a Caip10Link for the account `0x054...7cb8` on the Ethereum mainnet blockchain (`eip155:1`) and then associate it with the DID `did:3:k2t6...ydki`. 56 | 57 | ```ts 58 | import { CeramicClient } from '@ceramicnetwork/http-client' 59 | import { Caip10Link } from '@ceramicnetwork/stream-caip10-link' 60 | import { EthereumAuthProvider } from '@ceramicnetwork/blockchain-utils-linking' 61 | 62 | const ceramic = new CeramicClient() 63 | 64 | async function linkCurrentAddress() { 65 | // First, we need to create an EthereumAuthProvider with the account currently selected 66 | // The following assumes there is an injected `window.ethereum` provider 67 | const addresses = await window.ethereum.request({ 68 | method: 'eth_requestAccounts', 69 | }) 70 | const authProvider = new EthereumAuthProvider(window.ethereum, addresses[0]) 71 | 72 | // Retrieve the CAIP-10 account from the EthereumAuthProvider instance 73 | const accountId = await authProvider.accountId() 74 | 75 | // Load the account link based on the account ID 76 | const accountLink = await Caip10Link.fromAccount( 77 | ceramic, 78 | accountId.toString(), 79 | ) 80 | 81 | // Finally, link the DID to the account using the EthereumAuthProvider instance 82 | await accountLink.setDid( 83 | 'did:3:k2t6wyfsu4pg0t2n4j8ms3s33xsgqjhtto04mvq8w5a2v5xo48idyz38l7ydki', 84 | authProvider, 85 | ) 86 | } 87 | ``` 88 | 89 | ### Remove a link 90 | 91 | Removing a link involves a similar flow to setting the DID, but using the `clearDid` method instead of `setDid`: 92 | 93 | ```ts 94 | import { CeramicClient } from '@ceramicnetwork/http-client' 95 | import { Caip10Link } from '@ceramicnetwork/stream-caip10-link' 96 | import { EthereumAuthProvider } from '@ceramicnetwork/blockchain-utils-linking' 97 | 98 | const ceramic = new CeramicClient() 99 | 100 | async function unlinkCurrentAddress() { 101 | // First, we need to create an EthereumAuthProvider with the account currently selected 102 | // The following assumes there is an injected `window.ethereum` provider 103 | const addresses = await window.ethereum.request({ 104 | method: 'eth_requestAccounts', 105 | }) 106 | const authProvider = new EthereumAuthProvider(window.ethereum, addresses[0]) 107 | 108 | // Retrieve the CAIP-10 account from the EthereumAuthProvider instance 109 | const accountId = await authProvider.accountId() 110 | 111 | // Load the account link based on the account ID 112 | const accountLink = await Caip10Link.fromAccount( 113 | ceramic, 114 | accountId.toString(), 115 | ) 116 | 117 | // Finally, unlink the DID from the account using the EthereumAuthProvider instance 118 | await accountLink.clearDid(authProvider) 119 | } 120 | ``` 121 | 122 | 134 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/ceramic-nodes/running-locally.md: -------------------------------------------------------------------------------- 1 | # Launch a local Ceramic node 2 | 3 | --- 4 | 5 | To run a local Ceramic node you will generally need to run two key components: 6 | - `js-ceramic` - an api interface for Ceramic applications 7 | - `ceramic-one` - a binary that provides a Ceramic data network access through the protocol implementation in Rust. 8 | 9 | You should always start with running the `ceramic-one` component first to make sure that the `js-ceramic` component can connect to it. 10 | 11 | ## Prerequisites 12 | 13 | --- 14 | 15 | Installing the `js-ceramic` requires the following: 16 | - a terminal of your choice, 17 | - [Node.js](https://nodejs.org/en/) v20, 18 | - [npm](https://www.npmjs.com/get-npm) v10 19 | 20 | Make sure to have these installed on your machine. 21 | 22 | 23 | ## Setting up the `ceramic-one` component 24 | 25 | The easiest way to install the `ceramic-one` is using [Homebrew](https://brew.sh/) package manager. After installing Homebrew on your local machine, you can install `ceramic-one` using the following command: 26 | 27 | ```bash 28 | brew install ceramicnetwork/tap/ceramic-one 29 | ``` 30 | 31 | Once installed, run the ceramic-one binary by running the command provided below. Not that using the flag `--network` you can modify the network: 32 | 33 | ```bash 34 | ceramic-one daemon --network testnet-clay 35 | ``` 36 | 37 | :::note 38 | There are many flags for the daemon CLI that can be passed directly or set as environment variables. You can pass the `-h` flag to see the complete list as follows: 39 | 40 | ```ceramic-one daemon -h``` 41 | ::: 42 | 43 | You also have an option of running the `ceramic-one` binary using Docker. Check out the instructions in the [README of rust-ceramic repository](https://github.com/ceramicnetwork/rust-ceramic?tab=readme-ov-file). 44 | 45 | 46 | ## Setting up the `js-ceramic` component 47 | 48 | The Ceramic command line interface provides an easy way to start a JS Ceramic node in a local Node.js environment. This is a great way to get started developing with Ceramic before moving to a cloud-hosted node for production use cases. 49 | 50 | 51 | ### Install the Ceramic CLI 52 | 53 | Open your console and install the CLI using npm: 54 | 55 | ```bash 56 | npm install -g @ceramicnetwork/cli 57 | ``` 58 | 59 | ### Launch the `js-ceramic` node 60 | 61 | Use the `ceramic daemon` command to start a local JS Ceramic node connected to the [Clay Testnet](../../networking/networks.md#clay-testnet) by default running at `https://localhost:7007`: 62 | 63 | ```bash 64 | ceramic daemon 65 | ``` 66 | 67 | ### Configure your network 68 | 69 | (Optional) By default, the JS CLI starts a node on the [Clay Testnet](../../networking/networks.md#clay-testnet). If you would like to use a different network, you can specify this using the `--network` option. View [available networks](../../networking/networks.md). Note, the CLI can not be used with [Mainnet](../../networking/networks.md#mainnet). 70 | 71 | ### Configure a node URL 72 | 73 | (Optional) It is possible to use the CLI with a remote Ceramic node over HTTP, instead of a local node. To do this, use the `config set` command to set the `ceramicHost` variable to the URL of the node you wish to use. 74 | 75 | ```bash 76 | ceramic config set ceramicHost 'https://yourceramicnode.com' 77 | ``` 78 | 79 | ## Monitoring 80 | You can always check if `js-ceramic` and `ceramic-one` components are available by running the commands listed below. 81 | 82 | ### `js-ceramic` service's availability 83 | 84 | Check the `js-ceramic` service’s availability with the healthcheck endpoint: 85 | 86 | ```json 87 | curl http://localhost:7007/api/v0/node/healthcheck 88 | ``` 89 | 90 | ### `ceramic-one` service's availability 91 | 92 | Check the ceramic-one service’s availability with the liveness endpoint: 93 | 94 | ```json 95 | curl http://127.0.0.1:5101/ceramic/liveness 96 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/guides/guides-index.md: -------------------------------------------------------------------------------- 1 | # Ceramic Development Guides 2 | --- 3 | 4 | Guides that support development on Ceramic. 5 | 6 | ### Ceramic Nodes 7 | 8 | - [**Running Locally**](./ceramic-nodes/running-locally.md) 9 | - [**Running in the Cloud**](./ceramic-nodes/running-cloud.md) 10 | 11 | ### Ceramic Clients 12 | 13 | - [**JavaScript Client**](./ceramic-clients/javascript-clients/ceramic-http.md) 14 | - [**Authentication**](./ceramic-clients/authentication/key-did.md) 15 | - [**Stream APIs**](./ceramic-clients/stream-api/caip10-link.md) 16 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/networking/event-fetching.md: -------------------------------------------------------------------------------- 1 | # Event Fetching 2 | 3 | Once a tip is discovered through the [Tip Gossip](tip-queries.md) or [Tip Query](tip-queries.md) protocols a node knows both the StreamID and the latest event CID of the stream. The latest Event contains the CID of the `prev` Event and so on until the Init Event is found in the event log. The Init Event's CID is also in the StreamID. This is proof that the tip is part of the stream identified by the StreamId. 4 | 5 | The tip is one of [Init, Data, or Time Event](../streams/event-log.md). If the tip CID is the initial event CID then the stream has never been updated and the initial event is the complete event log. If the tip CID points to a Data, or Time event then that event will contain a `prev` field with a CID link to its previous event. IPFS can be used to retrieve this event. Similarly you can use IPFS to recursively fetch and resolve every `prev` event in an event log until reaching the initial event. At that point you have retrieved and synced the entire stream. 6 | 7 | Fetching an event with IPFS from a peer both relies on [IPFS BitSwap](https://docs.ipfs.tech/concepts/bitswap/) and the [IPFS DHT](https://docs.ipfs.tech/concepts/dht/). -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/networking/networking-index.md: -------------------------------------------------------------------------------- 1 | # Networking 2 | 3 | Networking sub-protocols for Ceramic. 4 | 5 | ### Overview 6 | 7 | Ceramic streams and nodes are grouped into independent networks. These networks can be either for public use or for use by a specific community. There are currently a few commonly shared and default networks. When a stream is published in a network, other nodes in the same network are able to query and discover the stream, receive the latest stream events (tips), and sync the entire event set for a stream. Each of the these network functions are defined by a sub protocol listed below. 8 | 9 | ### [Networks](networks.md) 10 | 11 | Networks are collections of Ceramic [nodes](../nodes/overview.md) that share specific configurations and communicate over dedicated [libp2p](https://libp2p.io/) pubsub topics. They are easily identified by a path string, for example `/ceramic/mainnet` . 12 | 13 | ### [Data Feed API](data-feed-api.md) 14 | 15 | The Ceramic Data Feed API gives developers a way to keep track of all the new state changes that are happening in the Ceramic network. This enables developers to customize the way their data is indexed and queried, and enables the development of new custom database products on top of Ceramic. 16 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/networking/networks.md: -------------------------------------------------------------------------------- 1 | # Networks 2 | 3 | Information about the default Ceramic networks 4 | 5 | ## Overview 6 | --- 7 | 8 | Networks are collections of Ceramic [nodes](../nodes/overview.md) that share specific configurations and communicate over dedicated [libp2p](https://libp2p.io/) pubsub topics. Networks are disjoint from one another; streams that exist on one network are **not** discoverable or usable on another. 9 | 10 | These pubsub topics are used to relay all messages for the defined networking sub protocols. 11 | 12 | ## All Networks 13 | --- 14 | 15 | An overview of the various Ceramic networks available today: 16 | 17 | | Name | Network ID | Ceramic Pubsub Topic | Timestamp Authority | Type | 18 | | --- | --- | --- | --- | --- | 19 | | Mainnet | mainnet | /ceramic/mainnet | Ethereum Mainnet (EIP155:1) | Public | 20 | | Clay Testnet | testnet-clay | /ceramic/testnet-clay | Ethereum Gnosis Chain | Public | 21 | | Dev Unstable | dev-unstable | /ceramic/dev-unstable | Ethereum Goerli Testnet | Public | 22 | | Local | local | /ceramic/local-$(randomNumber) | Ethereum by Truffle Ganache | Private | 23 | | In-memory | inmemory | | None | Private | 24 | 25 | :::note 26 | There is currently a proposal to decompose each network into multiple pubsub topics for scalability, the pubsub topics will remain prefixed by the network identifier `/ceramic//` see [CIP-120](https://github.com/ceramicnetwork/CIP/blob/main/CIPs/cip-120.md) 27 | ::: 28 | 29 | ## Public networks 30 | --- 31 | 32 | Ceramic has three public networks that can be used when building applications: 33 | 34 | - Mainnet 35 | - Testnet Clay 36 | - Dev Unstable 37 | 38 | ### Mainnet 39 | 40 | Mainnet is the main public network used for production deployments on Ceramic. Ceramic's mainnet nodes communicate over the dedicated `/ceramic/mainnet` libp2p pubsub topic and use Ethereum's mainnet blockchain (`EIP155:1`) for generating timestamps used in [time events](../streams/event-log.md) for streams. 41 | 42 | ### Clay Testnet 43 | 44 | Clay Testnet is a public Ceramic network used by the community for application prototyping, development, and testing purposes. Ceramic core devs also use Clay for testing official protocol release candidates. While we aim to maintain a high level of quality on the Clay testnet that mirrors the expectations of Mainnet as closely as possible, ultimately the reliability, performance, and stability guarantees of the Clay network are lower than that of Mainnet. Because of this, **the Clay network should not be used for applications in production**. 45 | 46 | Clay nodes communicate over the dedicated `/ceramic/testnet-clay` libp2p pubsub topic and use Ethereum's Gnosis blockchain for generating timestamps used in [time events](../streams/event-log.md) for streams. 47 | 48 | ### Dev Unstable 49 | 50 | Dev Unstable is a public Ceramic network used by Ceramic core protocol developers for testing new protocol features and the most recent commits on the develop branch of `js-ceramic`. It should be considered **unstable and highly experimental**; only use this network if you want to test the most cutting edge features, but expect issues. 51 | 52 | Dev Unstable nodes communicate over the dedicated `/ceramic/dev-unstable` libp2p pubsub topic and use Ethereum's Goerli testnet blockchains for generating timestamps used in [time events](../streams/event-log.md) for streams. 53 | 54 | ## Private Networks 55 | --- 56 | 57 | You can prototype applications on Ceramic by running the protocol in a local environment completely disconnected from other public nodes. Here "private" indicates that it is independent of the mainnet network, but does **not** imply any confidentiality guarantees. This is still public data. 58 | 59 | ### Local 60 | 61 | Local is a private test network used for the local development of Ceramic applications. Nodes connected to the same local network communicate over a randomly-generated libp2p topic `/ceramic/local-$(randomNumber)` and use a local Ethereum blockchain provided by Truffle's [Ganache](https://trufflesuite.com/ganache/) for generating timestamps used in [time events](../streams/event-log.md) for streams. 62 | 63 | ## Examples 64 | --- 65 | 66 | ### TypeScript Definitions 67 | 68 | ```tsx 69 | enum Networks { 70 | MAINNET = 'mainnet', // The prod public network 71 | TESTNET_CLAY = 'testnet-clay', // Should act like mainnet to test apps 72 | DEV_UNSTABLE = 'dev-unstable', // May diverge from mainnet to test Ceramic 73 | LOCAL = 'local', // local development and testing 74 | INMEMORY = 'inmemory', // local development and testing 75 | } 76 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/networking/tip-gossip.md: -------------------------------------------------------------------------------- 1 | # Tip Gossip 2 | 3 | When a stream is updated, the latest event (tip) is gossiped and propagated out to all the nodes in a network that are interested in that particular stream. Additionally, listening for all tips, allows a node to learn about streams it did not know about. This allows all interested nodes in the network to quickly get the latest update and state for a stream. 4 | 5 | ## Protocol 6 | --- 7 | 8 | ### Publishing Updates 9 | 10 | When an event is created and appended to a stream, the node will publish an update message to the network. All messages are broadcast on the [libp2p pubsub](https://github.com/libp2p/specs/tree/master/pubsub) topic for the [network](networks.md) this node is configured for. Any other node listening on this network will receive the update and then can decide to take any further action or discard. 11 | 12 | ### Update Messages 13 | 14 | ```tsx 15 | type UpdateMessage = { 16 | typ: MsgType.UPDATE //0 17 | stream: StreamID 18 | tip: CID 19 | model?: StreamID 20 | } 21 | ``` 22 | 23 | Where: 24 | 25 | - **`typ`** - the message is an update message, enum `0` 26 | - **`stream`** - streamId of the stream which this update is for 27 | - **`tip`** - CID of the latest event (tip) of the stream, the update 28 | - **`model`** - streamId of the ComposeDB data model that the stream being updated belongs to (optional) 29 | 30 | ### Replicating Updates 31 | 32 | Any nodes that have received an update message and are interested in that stream can now save the tip (update). Any node that has saved this update can now answer [tip queries](tip-queries.md) for this stream. As long as there is at least one node in the network with this information (tip) saved, the publishing node can go down without effecting the availability of the stream. 33 | 34 | ## Examples 35 | --- 36 | 37 | ### TypeScript Definitions 38 | 39 | ```tsx 40 | /** 41 | * Ceramic Pub/Sub message type. 42 | */ 43 | enum MsgType { 44 | UPDATE = 0, 45 | QUERY = 1, 46 | RESPONSE = 2, 47 | KEEPALIVE = 3, 48 | } 49 | 50 | type UpdateMessage = { 51 | typ: MsgType.UPDATE 52 | stream: StreamID 53 | tip: CID // the CID of the latest commit 54 | model?: StreamID // optional 55 | } 56 | 57 | // All nodes will always ignore this message 58 | type KeepaliveMessage = { 59 | typ: MsgType.KEEPALIVE 60 | ts: number // current time in milliseconds since epoch 61 | ver: string // current ceramic version 62 | } 63 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/networking/tip-queries.md: -------------------------------------------------------------------------------- 1 | # Tip Queries 2 | 3 | Ceramic streams are identified by a [URI](../streams/uri-scheme) called StreamIds. Nodes that want to sync a stream need to query the network for the tip of that stream using its StreamId. 4 | 5 | !!!note 6 | Tips are the most recent Init, Data, or Time event for a given Stream Tip 7 | 8 | 9 | ## Protocol 10 | --- 11 | 12 | A node resolving a Ceramic URI sends a query message to the network and then listens for responses with the candidates for the current tip of the stream. Any node that is interested in the same stream on the network and has stored its tips will respond with a response message. All messages are sent on the [libp2p pubsub](https://github.com/libp2p/specs/tree/master/pubsub) topic for the [network](networks.md) the node is configured for. 13 | 14 | ### **Query Message** 15 | 16 | ```tsx 17 | type QueryMessage = { 18 | typ: MsgType.QUERY // 1 19 | id: string 20 | stream: StreamID 21 | } 22 | ``` 23 | 24 | Where: 25 | 26 | - **`typ`** - the message is a query message, enum `1` 27 | - **`stream`** - the streamId that is being queried or resolved 28 | - **`id`** - a multihash `base64url.encode(sha265(dagCBOR({typ:1, stream: streamId})))`, can generally be treated as a random string that is used to pair queries to responses 29 | 30 | ### **Response Message** 31 | 32 | ```tsx 33 | type ResponseMessage = { 34 | typ: MsgType.RESPONSE // 2 35 | id: string 36 | tips: Map 37 | } 38 | ``` 39 | 40 | Where: 41 | 42 | - **`typ`** - the message is a response message, enum `2` 43 | - **`id`** - id of the query that this message is a response to 44 | - **`tips`** - map of `StreamID` to CID of stream tip 45 | 46 | :::note 47 | Currently this will only ever have a single `StreamID` in the query, but Ceramic will likely have batch queries at some point in the future. 48 | ::: 49 | 50 | ## Examples 51 | --- 52 | 53 | ### TypeScript Definitions 54 | 55 | ```tsx 56 | enum MsgType { // Ceramic Pub/Sub message type. 57 | UPDATE = 0, 58 | QUERY = 1, 59 | RESPONSE = 2, 60 | KEEPALIVE = 3, 61 | } 62 | 63 | type QueryMessage = { 64 | typ: MsgType.QUERY 65 | id: string 66 | stream: StreamID 67 | } 68 | 69 | type ResponseMessage = { 70 | typ: MsgType.RESPONSE 71 | id: string 72 | tips: Map 73 | } 74 | ``` -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/nodes/overview.md: -------------------------------------------------------------------------------- 1 | # Nodes Overview 2 | --- 3 | 4 | ## Ceramic Nodes 5 | 6 | A Ceramic node is a bundle of services and long-lived processes that support the protocol and provide access to the Ceramic Network. Current implementations bundle and run most all of the following services and sub protocols defined here. This includes the following: 7 | 8 | 9 | ### **Ceramic Services** 10 | 11 | | Service | Description | 12 | | --- | --- | 13 | | StateStore | Tracks and stores the latest tips for pinned streams and caches stream state. | 14 | | Networking | Runs the stream query and update protocols on Gossipsub and manages peer connections. | 15 | | API | Provides HTTP API service for connected Ceramic clients to read, write and query streams. Additionally, some node management functions are included. | 16 | | Timestamping | Regularly publishes timestamp proofs and Ceramic time events for a given set of events. | 17 | 18 | :::note 19 | 20 | In the future, node implementations may only provide a subset of services to the network. For example, nodes may be optimized to provide only indexing, long term storage, client APIs etc. 21 | ::: 22 | 23 | ## Timestamp Nodes 24 | 25 | --- 26 | 27 | Timestamping nodes support a small but important subset of the Ceramic protocol. Timestamping is entirely described by [CAIP-168 IPLD Timestamp Proof](https://chainagnostic.org/CAIPs/caip-168) and Ceramic Time Events. Timestamp services aggregate events from streams to be timestamped, construct Merkle proofs, publish transactions and publish timestamp events to the Ceramic Network. Ceramic mainnet currently supports `f(bytes32)` timestamp transaction types on Ethereum mainnet. This transaction type is entirely described by the [`eip155` namespace](https://github.com/ChainAgnostic/namespaces/blob/main/eip155/caip168.md) for CAIP-168. 28 | 29 | ## Implementations 30 | 31 | --- 32 | 33 | The following table includes active node implementations: 34 | 35 | | Node | Name | Language | Description | Status | Maintainer | 36 | | --- | --- | --- | --- | --- | --- | 37 | | Ceramic | [js-ceramic](https://github.com/ceramicnetwork/js-ceramic/) | JavaScript | Complete Ceramic implementation. Runs all Ceramic core services, and connects to an IPFS node for all IPFS, libp2p, IPLD services needed. | Production | 3Box Labs | 38 | | Timestamp | [ceramic-anchor-service](https://github.com/ceramicnetwork/ceramic-anchor-service) | JavaScript | Complete timestamp services. Supports f(bytes32) and raw transaction types for EVM (EIP-155) blockchains. | Production | 3Box Labs | 39 | 40 | Longterm Ceramic is targeting multiple implementations of the protocol to support general resilience, robustness and security. Want to work on a node implementation in a new language like Rust or Go? Get in touch on the Forum! -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/nodes/running-a-node.md: -------------------------------------------------------------------------------- 1 | # Running a Node 2 | --- 3 | This will help explain how to run a Ceramic Node and some other specifics that are recommended to make sure your node is running smoothly. 4 | 5 | ## Installation 6 | --- 7 | 8 | ### Install and Run the Ceramic CLI 9 | 10 | This can be installed from NPM and updated through NPM by using the following command: 11 | 12 | ```bash 13 | npx @ceramicnetwork/cli daemon 14 | ``` 15 | 16 | :::note 17 | Make sure that you have `ceramic-one` binary running in the background. To set it up, follow the setup steps [here](../guides/ceramic-nodes/running-locally#setting-up-the-ceramic-one-component). 18 | ::: 19 | 20 | 21 | This will install the CLI and start the daemon. This will allow all of the initial files to be created. This will successfully have a node running on the Clay TestNet. 22 | 23 | ## Operations Considerations 24 | --- 25 | 26 | ### Log Rotate 27 | 28 | As a node runs for sometime if you enable the log to files you will want to enable `logrotate` to ensure that your node does not overfill the hard drive. This can be done by following the following steps: 29 | 30 | 1. Install `logrotate` using the following command: 31 | 32 | ```bash 33 | sudo apt install logrotate 34 | ``` 35 | 36 | 2. Create a file in `/etc/logrotate.d/ceramic` with the following contents: 37 | 38 | ```bash 39 | /home/ubuntu/.ceramic/logs/*.log { 40 | daily 41 | missingok 42 | rotate 7 43 | compress 44 | delaycompress 45 | notifempty 46 | create 0640 ubuntu ubuntu 47 | sharedscripts 48 | postrotate 49 | systemctl restart ceramic 50 | endscript 51 | } 52 | ``` 53 | 54 | 3. Enable and Start the `logrotate` service using the following commands: 55 | 56 | ```bash 57 | sudo systemctl enable logrotate 58 | sudo systemctl start logrotate 59 | ``` 60 | 61 | ### Monitoring 62 | 63 | It is strongly recommended to use your existing monitoring system to collect and process the [metrics offered by the node](../../../composedb/guides/composedb-server/server-configurations.mdx). 64 | 65 | 66 | #### Availability 67 | 68 | Check the `js-ceramic` service’s availability with the healthcheck endpoint 69 | 70 | ```json 71 | curl http://localhost:7007/api/v0/node/healthcheck 72 | ``` 73 | 74 | Check the `ceramic-one` service’s availability with the liveness endpoint 75 | 76 | ```json 77 | curl http://127.0.0.1:5101/ceramic/liveness 78 | ``` 79 | 80 | #### Metrics 81 | 82 | Both `ceramic-one` and `js-ceramic` have prometheus compatible endpoints available. 83 | 84 | `ceramic-one` is enabled by default 85 | 86 | ```jsx 87 | curl http://127.0.0.1:9464/metrics # ceramic-one metrics 88 | ``` 89 | 90 | js-ceramic monitoring configuration is described [here](https://developers.ceramic.network/docs/composedb/guides/composedb-server/server-configurations#prometheus-endpoint0). -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/overview.md: -------------------------------------------------------------------------------- 1 | # Ceramic Protocol 2 | 3 | Ceramic is a decentralized event streaming protocol that enables developers to build decentralized databases, distributed compute pipelines, and authenticated data feeds, etc. Ceramic nodes can subscribe to subsets of streams forgoing the need of a global network state. This makes Ceramic an eventually consistent system (as opposed to strongly consistent like L1 blockchains), enabling web scale applications to be built reliably. 4 | 5 | 6 | The latest release of Ceramic has introduced a new Rust-based implementation of Ceramic protocol which offers performance and stability improvements as well as a new data synchronisation protocol called Recon. Developers, building on Ceramic network will be using two main components: 7 | - `js-ceramic` component which provides the API interface for Ceramic applications 8 | - `ceramic-one` component which provides Ceramic data network access (contains the implementation of Recon protocol). 9 | 10 |
11 | ![protocol-overview](/img/protocol.png) 12 |
13 | 14 | 15 | The protocol doesn't prescribe how to interpret events found within streams; this is left to the applications consuming the streams. Some examples of this type of application are: 16 | - [ComposeDB](../../composedb/getting-started) 17 | -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/streams/consensus.md: -------------------------------------------------------------------------------- 1 | # Consensus 2 | 3 | ## Consensus Model 4 | 5 | --- 6 | 7 | Event streams rely on a limited conflict resolution or consensus model. Global consensus and ordering is not needed for progress and most decisions are localized to the consuming party of a single event stream. Guarantees are limited, but if any two parties consume the same set of events for a stream, they will arrive at the same state. 8 | 9 | The underlying log structure of an event stream allows multiple parallel histories, or branches, to be created resulting in a tree structure. A log or valid event stream is a single tree path from a known "latest" event to the Init Event. Latest events are also referred to as stream "tips". Logs can have multiple tips when there are branches in the log, and the "tip" selection for the canonical log of a stream becomes a consensus problem. 10 | 11 | ### Single stream consensus 12 | 13 | A tip and canonical log for a stream are selected by the following pseudo algorithm and rules: 14 | 15 | 1. Given a set of tips, traverse each tree path from tip till a commonly shared Time Event or the Init Event. 16 | 2. From the shared event, traverse each path in the opposite direction (towards tip) until a Time Event is found (or the end of the log is reached). This set of events are considered conflicting events. 17 | 3. Given each Time Event, determine the blockheight for the transaction included in the timestamp proof. Select the path with lowest blockheight. If a single path is selected, exit with path and tip selected, otherwise continue. Most cases will terminate here, it will be rare to have the same blockheight. 18 | 4. If multiple tips have the same blockheight, select the path with the greatest number of events from the last timestamp proof till tip. If single path selected, exit with path and tip selected, otherwise continue. 19 | 5. If number of events is equal, chooses the event and path which has the smallest CID in binary format (an arbitrary but deterministic choice) 20 | 21 | ### Cross stream ordering 22 | 23 | It is assumed all timestamp events in a network are committed to the same blockchain, as specified by the `chainId` in the timestamp event. The main Ceramic network commits timestamp proofs to the Ethereum blockchain. 24 | 25 | The addition of timestamp events in streams gives some notion of relative global time for all events time-stamped on the same blockchain. This allows events across different streams to be globally ordered if a higher-level protocol requires it. Ceramic events can also be ordered against transactions and state on the blockchain in which it is timestamped. On most secure blockchains you can also reference wall clock time within some reasonable bounds and order events both in and out of the system based on that. 26 | 27 | ## Risks 28 | 29 | --- 30 | 31 | ### Late Publishing 32 | 33 | Without any global consensus guarantees, all streams and their potential tips are not known by all participants at any point in time. There may be partitions in the networks, existence of local networks, or individual participants may choose to intentionally withhold some events while publishing others. Selective publishing like this may or may not be malicious depending on the context in which the stream is consumed. 34 | 35 | Consider the following example: A user creates a stream, makes two conflicting updates and timestamps one of them earlier than the other, but only publishes the data of the update that was timestamped later. Now subsequent updates to the stream will be made on top of the second, published update. Every observer will accept these updates as valid since they have not seen the first update. However if the user later publishes the data of the earlier update, the stream will fork back to this update and all of the other updates made to the stream will be invalidated. 36 | 37 | Most of the time, the potential of an intentional late publishing attack isn't a concern in practice, as streams in Ceramic are generally controlled by a single user, and there's no incentive to attack one's own streams. This would become more of a concern, however, in streams with more sophisticated access control that allowed multiple end users to write into the same stream. In that case, all users of the stream would need to trust all the other users who have - or have ever had - write access to the stream to not be secretly sitting on timestamped writes that they haven't yet published, or else risk those writes being revealed later on and causing the stream to lose all writes that have occurred since the previously secret write was created. 38 | 39 | Additionally, note that late publishing may also be used as a deterrent to selling user identities. An identity or account buyer can't know that the seller is not keeping secret events that they will publish after the identity was sold. -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/streams/lifecycle.md: -------------------------------------------------------------------------------- 1 | # Stream Lifecycle 2 | 3 | ## Write Lifecycle 4 | 5 | --- 6 | 7 | ### Create 8 | 9 | A stream is created when an [Init Event](event-log.md) is created and published. The stream is then uniquely referenced in the network by its [StreamId](uri-scheme.md), which is derived from this Init Event. 10 | 11 | ### Update 12 | 13 | Updates to a stream include the creating and publishing of data events or timestamp events. When creating these events they must reference the latest event or tip in the stream. The latest event, if there is multiple, is determined by locally following the conflict resolution and [consensus rules](consensus.md). The current update protocol is described further [here](../networking/tip-gossip.md). 14 | 15 | The data event is a signed event and is expected to be created and published by the controller of the given stream it is being appended. A timestamp event on the other hand can be created by any participant in network, given that it is a valid timestamp proof. Typically in the Ceramic network they will be created and published by a timestamping service. 16 | 17 | ## Read Lifecycle 18 | 19 | --- 20 | 21 | ### Query 22 | 23 | The network can be queried to discover the latest tips for any stream by StreamId. Knowing both the StreamId and tip then allows any node to sync the stream. Query requests are broadcast to the entire network to discover peers that have tips for any given stream. Future query protocols can be optimized and include other stream attributes and values to discover streams and stream tips. The current query protocol is described further [here](../networking/tip-queries.md). 24 | 25 | ### Sync 26 | 27 | Streams can be synced and loaded by knowing both the StreamId and the latest event (tip). Given the latest tip you can traverse the stream event log from event to event in order until the Init Event is reached. Each event is loaded from peers in the network, any peer with a tip is expected to have the entirety of the event stream log. The current sync protocol is described further [here](../networking/event-fetching.md). 28 | 29 | ## Durability 30 | 31 | --- 32 | 33 | ### Maintenance 34 | A stream is a set of [events](event-log.md) and these events are stored in IPFS nodes. As long as the entire set of events is pinned and advertised on the IPFS DHT, the respective stream will be retrievable. If your application depends on a stream remaining available, it is your application's responsibility to maintain and store all of its events. This can be done by running your own IPFS nodes or by using an IPFS pinning service. Typically you will be running an IPFS node with Ceramic. 35 | 36 | If any events are not available at a given time, it is not a guarantee that the stream has been deleted. A node with a copy of those events 37 | may be temporarily offline and may return at some future time. 38 | 39 | Other nodes in the network can pin (maintain and store) events from your streams or anyone else's streams. If you suffer a data loss, some other node MAY have preserved your data. Popular streams and their events are likely to be stored on many nodes in the network. -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/streams/streams-index.md: -------------------------------------------------------------------------------- 1 | # Streams 2 | 3 | Data structures core to Ceramic 4 | 5 | ### Overview 6 | 7 | Streams are a core concept in Ceramic, they include a primary data structure called an event log, a URI scheme to identify unique streams in a network, a simple consensus model to agree on the same event log across the network, and a supporting lifecycle of creating, updating, querying, and syncing streams. 8 | 9 | ### [Event Log](event-log.md) 10 | 11 | The core data structure of streams is a self-certifying event log. It combines IPLD for hash linked data and cryptographic proofs to create an authenticated and immutable log. This event log can be used to model mutable databases and other data structures on top. 12 | 13 | ### [URI Scheme](uri-scheme.md) 14 | 15 | A URI scheme is used to reference unique streams and unique events included in streams. They use a self describing format that allows anyone to parse and consume a stream correctly, while also easily supporting future changes and new types. 16 | 17 | ### [Consensus](consensus.md) 18 | 19 | An event log or stream can end up with multiple branches or tips across nodes in the network. Different branches will result in differing stream state. A simple consensus model is used to allow all nodes whom consume the same set of events to eventually agree on a single log or state. 20 | 21 | ### [Stream Lifecycle](lifecycle.md) 22 | 23 | A stream write lifecycle includes its creation and updates, otherwise know as events. A stream read lifecycle includes queries and syncing. -------------------------------------------------------------------------------- /docs/protocol/js-ceramic/streams/uri-scheme.md: -------------------------------------------------------------------------------- 1 | # URI Scheme 2 | 3 | --- 4 | 5 | ## Stream URL 6 | 7 | --- 8 | 9 | Each stream in Ceramic is identified by a unique URL. This URL is comprised of a protocol identifier for Ceramic and a StreamId as defined below. 10 | 11 | When encoded as a string the StreamID is prepended with the protocol handler and StreamID is typically encoded using `base36`. This fully describes which stream and where it is located, in this case it can be found on the Ceramic Network. 12 | 13 | 14 | ```bash 15 | ceramic:// 16 | ``` 17 | 18 | For example, a StreamId may look as follows: 19 | 20 | ```bash 21 | ceramic://kjzl6fddub9hxf2q312a5qjt9ra3oyzb7lthsrtwhne0wu54iuvj852bw9wxfvs 22 | ``` 23 | 24 | EventIds can also be encoded in the same way. 25 | 26 | ```bash 27 | ceramic:// 28 | ``` 29 | 30 | ## StreamId 31 | 32 | --- 33 | 34 | A StreamId is composed of a StreamId code, a stream type, and a CID. It is used to reference a specific and unique event stream. StreamIds are similar to CIDs in IPLD, and use multiformats, but they provide additional information specific to Ceramic event streams. This also allows them to be distinguished from CIDs. The *init event* of an event stream is used to create the StreamId. 35 | 36 | StreamIds are defined as: 37 | 38 | ```bash 39 | ::= 40 | 41 | # e.g. using CIDv1 42 | ::= 43 | ``` 44 | 45 | Where: 46 | 47 | - **``** is a [multibase](https://github.com/multiformats/multibase) code (1 or 2 bytes), to ease encoding StreamIds into various bases. 48 | :::note 49 | Binary (not text-based) protocols and formats may omit the multibase prefix when the encoding is unambiguous. 50 | ::: 51 | - **``** `0xce` is a [multicodec](https://github.com/multiformats/multicodec) used to indicate that it's a [StreamId](https://github.com/multiformats/multicodec/blob/master/table.csv#L78), encoded as a varint 52 | - **``** is a [varint](https://github.com/multiformats/unsigned-varint) representing the stream type of the stream. 53 | - **``** is the bytes from the [CID](https://github.com/multiformats/cid) of the `init event`, stripped of the multibase prefix. 54 | 55 | The multicodec for StreamID is [`0xce`](https://github.com/multiformats/multicodec/blob/master/table.csv#L78). For compatibility with browser urls it's recommended to encode the StreamId using [[`base36`]](https://github.com/multiformats/multibase). 56 | 57 | The stream type value does not currently have any functionality at the protocol level. Rather, it is used by applications building on top of Ceramic (e.g. ComposeDB) to distinguish between different logic that is applied when processing events. Stream Type values have to be registered in the table of [CIP-59](https://github.com/ceramicnetwork/CIP/blob/main/CIPs/CIP-59/CIP-59.md#registered-values). 58 | 59 | ## EventId 60 | 61 | --- 62 | 63 | EventIds extend StreamIds to reference a specific event in a specific stream. Additional bytes are added to the end of a StreamId. If it represents the genesis event the zero byte is added (`0x00`) otherwise the CID that represents the event is added. 64 | 65 | EventIds are defined as 66 | 67 | ```bash 68 | ::= 69 | 70 | 71 | 72 | # e.g. using CIDv1 and representing the genesis event 73 | ::= 74 | 75 | <0x00> 76 | 77 | # e.g. using CIDv1 and representing an arbitrary event in the log 78 | ::= 79 | 80 | 81 | 82 | ``` 83 | 84 | Where: 85 | 86 | - **``** is either the zero byte (`0x00`) or [CID](https://github.com/multiformats/cid) bytes. 87 | 88 | ### Stream Versions 89 | 90 | Each EventId can also be considered a reference to a specific version of a stream. At any EventId, a stream can be loaded up until that event and the resulting set of events are considered the version of that stream. -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "docs", 3 | "version": "0.0.0", 4 | "private": true, 5 | "scripts": { 6 | "docusaurus": "docusaurus", 7 | "start": "docusaurus start", 8 | "build": "docusaurus build", 9 | "swizzle": "docusaurus swizzle", 10 | "deploy": "docusaurus deploy", 11 | "clear": "docusaurus clear", 12 | "serve": "docusaurus serve", 13 | "write-translations": "docusaurus write-translations", 14 | "write-heading-ids": "docusaurus write-heading-ids", 15 | "create-composite": "composedb composite:create example-composite.graphql --output static/my-first-composite.json", 16 | "typecheck": "tsc" 17 | }, 18 | "dependencies": { 19 | "@ceramicnetwork/cli": "^5.2.0", 20 | "@ceramicnetwork/common": "^5.1.0", 21 | "@ceramicnetwork/http-client": "^5.2.0", 22 | "@composedb/cli": "^0.7.0", 23 | "@composedb/client": "^0.7.0", 24 | "@didtools/pkh-ethereum": "^0.5.0", 25 | "@docusaurus/core": "^3.0.0", 26 | "@docusaurus/plugin-client-redirects": "^3.0.0", 27 | "@docusaurus/plugin-content-docs": "^3.0.0", 28 | "@docusaurus/plugin-google-tag-manager": "^3.0.0", 29 | "@docusaurus/preset-classic": "^3.0.0", 30 | "@docusaurus/theme-common": "^3.0.0", 31 | "@graphiql/toolkit": "^0.9.1", 32 | "@mdx-js/react": "^3.0.0", 33 | "clsx": "^2.0.0", 34 | "did-session": "^3.0.2", 35 | "graphiql": "^3.0.9", 36 | "graphql": "^16.8.1", 37 | "graphql-ws": "^5.14.2", 38 | "prism-react-renderer": "^2.1.0", 39 | "react": "^18.2.0", 40 | "react-device-detect": "^2.2.3", 41 | "react-dom": "^18.2.0", 42 | "react-ga4": "^2.1.0", 43 | "react-scripts": "5.0.1", 44 | "semantic-ui-react": "^2.1.5" 45 | }, 46 | "devDependencies": { 47 | "@docusaurus/module-type-aliases": "3.0.0" 48 | }, 49 | "browserslist": { 50 | "production": [ 51 | ">0.5%", 52 | "not dead", 53 | "not op_mini all" 54 | ], 55 | "development": [ 56 | "last 1 chrome version", 57 | "last 1 firefox version", 58 | "last 1 safari version" 59 | ] 60 | }, 61 | "engines": { 62 | "node": ">=18.0" 63 | } 64 | } 65 | -------------------------------------------------------------------------------- /src/components/homepage/community.js: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import styles from "./homeNavBoxes.module.css"; 3 | 4 | const FeatureList = [ 5 | { 6 | title: "Forum →", 7 | icon: ( 8 | 9 | 13 | 14 | ), 15 | items: [ 16 | { 17 | url: "https://forum.ceramic.network/", 18 | text: "The best place to ask questions and to search for answers." 19 | } 20 | ] 21 | }, 22 | { 23 | title: "Discord →", 24 | icon: ( 25 | 26 | 30 | 31 | ), 32 | items: [ 33 | { 34 | url: "https://chat.ceramic.network/", 35 | text: "Join the conversation with other developers and the Ceramic team." 36 | } 37 | ] 38 | }, 39 | { 40 | title: "Twitter →", 41 | icon: ( 42 | 43 | 47 | 48 | ), 49 | items: [ 50 | { 51 | url: "https://twitter.com/ceramicnetwork", 52 | text: "Follow us on Twitter for updates and announcements." 53 | } 54 | ] 55 | } 56 | ]; 57 | 58 | function Feature({ title, icon, items }) { 59 | return ( 60 | 71 | ); 72 | } 73 | 74 | export default function HomepageFeatures() { 75 | return ( 76 |
77 | {FeatureList.map((props, idx) => ( 78 | 79 | ))} 80 |
81 | ); 82 | } 83 | -------------------------------------------------------------------------------- /src/components/homepage/get-started.js: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import clsx from "clsx"; 3 | import styles from "./homeNavBoxes.module.css"; 4 | 5 | const FeatureList = [ 6 | { 7 | title: "Why Ceramic? →", 8 | items: [ 9 | { 10 | url: "docs/introduction/why-ceramic", 11 | text: "Dive into the overview of Ceramic Network. See key benefits, compare to other web3 solutions." 12 | } 13 | ] 14 | }, 15 | { 16 | title: "Ceramic Ecosystem →", 17 | items: [ 18 | { 19 | url: "https://threebox.notion.site/Ceramic-Ecosystem-Directory-a3a7a58f81544d33ad3feb84368775d4", 20 | text: "Explore the innovative projects and tools built on Ceramic Network." 21 | } 22 | ] 23 | } 24 | ]; 25 | 26 | function Feature({ title, icon, items }) { 27 | return ( 28 | 38 | ); 39 | } 40 | 41 | export default function HomepageFeatures() { 42 | return ( 43 |
44 | {FeatureList.map((props, idx) => ( 45 | 46 | ))} 47 |
48 | ); 49 | } 50 | -------------------------------------------------------------------------------- /src/components/homepage/homeNavBoxes.module.css: -------------------------------------------------------------------------------- 1 | .features { 2 | display: grid; 3 | grid-template-columns: repeat(auto-fill, minmax(max(250px, calc((100% - 1rem * 2) / 3)), 1fr)); 4 | /* grid-template-columns: 1fr 1fr; */ 5 | gap: 1rem; 6 | } 7 | 8 | .featureSvg { 9 | height: 400px; 10 | width: 200px; 11 | } 12 | 13 | .homecardLink { 14 | text-decoration: none; 15 | color: var(--ifm-font-color-base); 16 | } 17 | .homecardLink:hover { 18 | text-decoration: none; 19 | } 20 | 21 | .homecard { 22 | display: flex; 23 | flex-direction: column; 24 | justify-content: space-between; 25 | height: 125px; 26 | padding: 20px 20px; 27 | border-radius: 8px; 28 | border: 1px solid #d6d6d6; 29 | box-shadow: 0px 2px 10px 0px rgba(0, 0, 0, 0.25); 30 | background-color: var(--box-color); 31 | } 32 | 33 | .homecard:hover { 34 | background-color: #fff8f6 !important; 35 | } 36 | 37 | @media screen and (max-width: 450px) { 38 | .homecard { 39 | width: 100%; 40 | } 41 | } 42 | 43 | html[data-theme="light"] .homecard { 44 | border: 1px solid #d6d6d6; 45 | box-shadow: 0px 2px 10px 0px rgba(0, 0, 0, 0.25); 46 | } 47 | 48 | html[data-theme="dark"] .homecard { 49 | border: 1px solid #d6d6d6; 50 | box-shadow: 2px 2px 10px 2px rgba(255, 255, 255, 0.2); 51 | } 52 | 53 | html[data-theme="dark"] .homecard:hover { 54 | border: 1px solid #d6d6d6; 55 | background-color: black !important; 56 | } 57 | 58 | .homecard .title { 59 | font-size: 16px; 60 | font-style: normal; 61 | font-weight: 700; 62 | line-height: normal; 63 | text-decoration: none; 64 | } 65 | 66 | .homecard .listContainerLink { 67 | color: var(--ifm-font-color-base); 68 | font-size: 0.9em; 69 | font-weight: 300; 70 | line-height: normal; 71 | } 72 | 73 | .homecard .action { 74 | color: #4149f9 !important; 75 | font-size: 12px; 76 | font-style: normal; 77 | font-weight: 700; 78 | line-height: normal; 79 | padding: 3px 0 0 0; 80 | } 81 | 82 | html[data-theme="light"] .homecard a { 83 | color: #000; 84 | } 85 | .homecard a { 86 | color: white; 87 | line-height: 2rem; 88 | } 89 | -------------------------------------------------------------------------------- /src/components/homepage/start-building.js: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import clsx from "clsx"; 3 | import styles from "./homeNavBoxes.module.css"; 4 | 5 | const FeatureList = [ 6 | { 7 | title: "Example App →", 8 | items: [ 9 | { 10 | url: "/docs/composedb/create-ceramic-app", 11 | text: "Setup a fully functioning Ceramic app by running one simple command." 12 | } 13 | ] 14 | }, 15 | { 16 | title: "ComposeDB →", 17 | items: [ 18 | { url: "docs/composedb/getting-started", text: "Build composable dApps using a decentralised graph database." } 19 | ] 20 | } 21 | ]; 22 | 23 | function Feature({ title, icon, items }) { 24 | return ( 25 | 35 | ); 36 | } 37 | 38 | export default function HomepageFeatures() { 39 | return ( 40 |
41 | {FeatureList.map((props, idx) => ( 42 | 43 | ))} 44 |
45 | ); 46 | } 47 | -------------------------------------------------------------------------------- /src/components/homepage/tools-utilities.js: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import clsx from "clsx"; 3 | import styles from "./homeNavBoxes.module.css"; 4 | 5 | const FeatureList = [ 6 | { 7 | title: "Ceramic Protocol →", 8 | items: [ 9 | { 10 | url: "docs/protocol/js-ceramic/overview", 11 | text: "Dive into the specifications and implementation of the Ceramic Protocol." 12 | } 13 | ] 14 | }, 15 | { 16 | title: "Data Feed API →", 17 | items: [{ url: "docs/protocol/js-ceramic/networking/data-feed-api", text: "Build custom indexes on Ceramic." }] 18 | }, 19 | { 20 | title: "Decentralized Identifiers (DIDs) →", 21 | items: [{ url: "docs/dids/introduction", text: "Interact and manage decentralized identifiers." }] 22 | }, 23 | { 24 | title: "Simple Deploy →", 25 | items: [ 26 | { 27 | url: "docs/composedb/guides/composedb-server/running-in-the-cloud", 28 | text: "Easily run Ceramic Nodes in the Cloud." 29 | } 30 | ] 31 | } 32 | ]; 33 | 34 | function Feature({ title, icon, items }) { 35 | return ( 36 | 46 | ); 47 | } 48 | 49 | export default function HomepageFeatures() { 50 | return ( 51 |
52 | {FeatureList.map((props, idx) => ( 53 | 54 | ))} 55 |
56 | ); 57 | } 58 | -------------------------------------------------------------------------------- /src/css/custom.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Any CSS included here will be global. The classic template 3 | * bundles Infima by default. Infima is a CSS framework designed to 4 | * work well for content-centric websites. 5 | */ 6 | 7 | /* You can override the default Infima variables here. */ 8 | 9 | @font-face { 10 | font-family: "Inter"; 11 | font-style: normal; 12 | src: url("../fonts/Inter/static/Inter-Light.ttf"); 13 | font-weight: 300; 14 | font-display: swap; 15 | } 16 | @font-face { 17 | font-family: "Inter"; 18 | font-style: normal; 19 | src: url("../fonts/Inter/static/Inter-Regular.ttf"); 20 | font-weight: 400; 21 | font-display: swap; 22 | } 23 | @font-face { 24 | font-family: "Inter"; 25 | font-style: normal; 26 | src: url("../fonts/Inter/static/Inter-SemiBold.ttf"); 27 | font-weight: 500; 28 | font-display: swap; 29 | } 30 | 31 | @font-face { 32 | font-family: "Inter"; 33 | font-style: normal; 34 | src: url("../fonts/Inter/static/Inter-Bold.ttf"); 35 | font-weight: 700; 36 | font-display: swap; 37 | } 38 | 39 | :root { 40 | --ifm-font-family-base: Inter, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, 41 | BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", 42 | "Segoe UI Symbol"; 43 | --ifm-font-family-monospace: "Roboto Mono", SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", 44 | monospace; 45 | --ifm-color-primary: #fc6429; 46 | --ifm-color-primary-dark: #ef481d; 47 | --ifm-color-primary-darker: #ef4115; 48 | --ifm-color-primary-darkest: #de390f; 49 | --ifm-color-primary-light: #f26541; 50 | --ifm-color-primary-lighter: #f3704e; 51 | --ifm-color-primary-lightest: #f58f75; 52 | --ifm-code-font-size: 95%; 53 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); 54 | --shadow: rgba(0, 0, 0, 0.1); 55 | --ifm-menu-link-padding-horizontal: 1rem; 56 | --ifm-h1-font-size: 2.25rem; 57 | --ifm-h2-font-size: 1.75rem; 58 | --ifm-h3-font-size: 1.5rem; 59 | --ifm-h4-font-size: 1.25rem; 60 | --ifm-h5-font-size: 0.95rem; 61 | --ifm-h6-font-size: 0.875rem; 62 | --box-color: #fff; 63 | } 64 | 65 | /* For readability concerns, you should choose a lighter palette in dark mode. */ 66 | [data-theme="dark"] { 67 | --ifm-color-primary: #fc6429; 68 | --ifm-color-primary-dark: #ef481d; 69 | --ifm-color-primary-darker: #ef4115; 70 | --ifm-color-primary-darkest: #de390f; 71 | --ifm-color-primary-light: #f26541; 72 | --ifm-color-primary-lighter: #f3704e; 73 | --ifm-color-primary-lightest: #f58f75; 74 | --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); 75 | --shadow: rgba(255, 255, 255, 0.2); 76 | --ifm-background-color: #010122 !important; 77 | --ifm-background-surface-color: #010122 !important; 78 | --ifm-hero-background-color: #fc6429 !important; 79 | --ifm-font-color-base-inverse: white !important; 80 | --box-color: #1e1e1e; 81 | } 82 | 83 | .footer--dark { 84 | --ifm-footer-background-color: #01011f; 85 | } 86 | -------------------------------------------------------------------------------- /src/fonts/Inter/Inter-VariableFont_slnt,wght.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/Inter-VariableFont_slnt,wght.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/OFL.txt: -------------------------------------------------------------------------------- 1 | Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter) 2 | 3 | This Font Software is licensed under the SIL Open Font License, Version 1.1. 4 | This license is copied below, and is also available with a FAQ at: 5 | http://scripts.sil.org/OFL 6 | 7 | 8 | ----------------------------------------------------------- 9 | SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 10 | ----------------------------------------------------------- 11 | 12 | PREAMBLE 13 | The goals of the Open Font License (OFL) are to stimulate worldwide 14 | development of collaborative font projects, to support the font creation 15 | efforts of academic and linguistic communities, and to provide a free and 16 | open framework in which fonts may be shared and improved in partnership 17 | with others. 18 | 19 | The OFL allows the licensed fonts to be used, studied, modified and 20 | redistributed freely as long as they are not sold by themselves. The 21 | fonts, including any derivative works, can be bundled, embedded, 22 | redistributed and/or sold with any software provided that any reserved 23 | names are not used by derivative works. The fonts and derivatives, 24 | however, cannot be released under any other type of license. The 25 | requirement for fonts to remain under this license does not apply 26 | to any document created using the fonts or their derivatives. 27 | 28 | DEFINITIONS 29 | "Font Software" refers to the set of files released by the Copyright 30 | Holder(s) under this license and clearly marked as such. This may 31 | include source files, build scripts and documentation. 32 | 33 | "Reserved Font Name" refers to any names specified as such after the 34 | copyright statement(s). 35 | 36 | "Original Version" refers to the collection of Font Software components as 37 | distributed by the Copyright Holder(s). 38 | 39 | "Modified Version" refers to any derivative made by adding to, deleting, 40 | or substituting -- in part or in whole -- any of the components of the 41 | Original Version, by changing formats or by porting the Font Software to a 42 | new environment. 43 | 44 | "Author" refers to any designer, engineer, programmer, technical 45 | writer or other person who contributed to the Font Software. 46 | 47 | PERMISSION & CONDITIONS 48 | Permission is hereby granted, free of charge, to any person obtaining 49 | a copy of the Font Software, to use, study, copy, merge, embed, modify, 50 | redistribute, and sell modified and unmodified copies of the Font 51 | Software, subject to the following conditions: 52 | 53 | 1) Neither the Font Software nor any of its individual components, 54 | in Original or Modified Versions, may be sold by itself. 55 | 56 | 2) Original or Modified Versions of the Font Software may be bundled, 57 | redistributed and/or sold with any software, provided that each copy 58 | contains the above copyright notice and this license. These can be 59 | included either as stand-alone text files, human-readable headers or 60 | in the appropriate machine-readable metadata fields within text or 61 | binary files as long as those fields can be easily viewed by the user. 62 | 63 | 3) No Modified Version of the Font Software may use the Reserved Font 64 | Name(s) unless explicit written permission is granted by the corresponding 65 | Copyright Holder. This restriction only applies to the primary font name as 66 | presented to the users. 67 | 68 | 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font 69 | Software shall not be used to promote, endorse or advertise any 70 | Modified Version, except to acknowledge the contribution(s) of the 71 | Copyright Holder(s) and the Author(s) or with their explicit written 72 | permission. 73 | 74 | 5) The Font Software, modified or unmodified, in part or in whole, 75 | must be distributed entirely under this license, and must not be 76 | distributed under any other license. The requirement for fonts to 77 | remain under this license does not apply to any document created 78 | using the Font Software. 79 | 80 | TERMINATION 81 | This license becomes null and void if any of the above conditions are 82 | not met. 83 | 84 | DISCLAIMER 85 | THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 86 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF 87 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT 88 | OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE 89 | COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 90 | INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL 91 | DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 92 | FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM 93 | OTHER DEALINGS IN THE FONT SOFTWARE. 94 | -------------------------------------------------------------------------------- /src/fonts/Inter/README.txt: -------------------------------------------------------------------------------- 1 | Inter Variable Font 2 | =================== 3 | 4 | This download contains Inter as both a variable font and static fonts. 5 | 6 | Inter is a variable font with these axes: 7 | slnt 8 | wght 9 | 10 | This means all the styles are contained in a single file: 11 | Inter-VariableFont_slnt,wght.ttf 12 | 13 | If your app fully supports variable fonts, you can now pick intermediate styles 14 | that aren’t available as static fonts. Not all apps support variable fonts, and 15 | in those cases you can use the static font files for Inter: 16 | static/Inter-Thin.ttf 17 | static/Inter-ExtraLight.ttf 18 | static/Inter-Light.ttf 19 | static/Inter-Regular.ttf 20 | static/Inter-Medium.ttf 21 | static/Inter-SemiBold.ttf 22 | static/Inter-Bold.ttf 23 | static/Inter-ExtraBold.ttf 24 | static/Inter-Black.ttf 25 | 26 | Get started 27 | ----------- 28 | 29 | 1. Install the font files you want to use 30 | 31 | 2. Use your app's font picker to view the font family and all the 32 | available styles 33 | 34 | Learn more about variable fonts 35 | ------------------------------- 36 | 37 | https://developers.google.com/web/fundamentals/design-and-ux/typography/variable-fonts 38 | https://variablefonts.typenetwork.com 39 | https://medium.com/variable-fonts 40 | 41 | In desktop apps 42 | 43 | https://theblog.adobe.com/can-variable-fonts-illustrator-cc 44 | https://helpx.adobe.com/nz/photoshop/using/fonts.html#variable_fonts 45 | 46 | Online 47 | 48 | https://developers.google.com/fonts/docs/getting_started 49 | https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide 50 | https://developer.microsoft.com/en-us/microsoft-edge/testdrive/demos/variable-fonts 51 | 52 | Installing fonts 53 | 54 | MacOS: https://support.apple.com/en-us/HT201749 55 | Linux: https://www.google.com/search?q=how+to+install+a+font+on+gnu%2Blinux 56 | Windows: https://support.microsoft.com/en-us/help/314960/how-to-install-or-remove-a-font-in-windows 57 | 58 | Android Apps 59 | 60 | https://developers.google.com/fonts/docs/android 61 | https://developer.android.com/guide/topics/ui/look-and-feel/downloadable-fonts 62 | 63 | License 64 | ------- 65 | Please read the full license text (OFL.txt) to understand the permissions, 66 | restrictions and requirements for usage, redistribution, and modification. 67 | 68 | You can use them in your products & projects – print or digital, 69 | commercial or otherwise. 70 | 71 | This isn't legal advice, please consider consulting a lawyer and see the full 72 | license for all details. 73 | -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Black.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Black.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Bold.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-ExtraBold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-ExtraBold.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-ExtraLight.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-ExtraLight.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Light.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Light.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Medium.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Medium.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Regular.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-SemiBold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-SemiBold.ttf -------------------------------------------------------------------------------- /src/fonts/Inter/static/Inter-Thin.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/src/fonts/Inter/static/Inter-Thin.ttf -------------------------------------------------------------------------------- /src/pages/index.js: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import clsx from "clsx"; 3 | import Link from "@docusaurus/Link"; 4 | import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; 5 | import Layout from "@theme/Layout"; 6 | import HomeNavBox from "../components/homepage/get-started"; 7 | import HomeNavStart from "../components/homepage/start-building"; 8 | import HomeNavUtils from "../components/homepage/tools-utilities"; 9 | import HomeCommunity from "../components/homepage/community"; 10 | import styles from "./index.module.css"; 11 | 12 | function HomepageHeader() { 13 | const { siteConfig } = useDocusaurusContext(); 14 | return ( 15 |
16 |
17 |
18 |

Ceramic Docs

19 |

{siteConfig.tagline}

20 |
21 |
22 | Ceramic 23 |
24 |
25 |
26 | ); 27 | } 28 | 29 | export default function Home() { 30 | const { siteConfig } = useDocusaurusContext(); 31 | return ( 32 |
33 | 34 | 35 |
36 |
37 |
43 |

Build with ComposeDB

44 |
45 | A decentralized, composable graph database to build interoperable applications on Ceramic. 46 |
47 |
58 | 61 |
62 |
63 |
64 |
65 |
71 | 72 |
73 |
Get Started
74 |

New to Ceramic? Start here!

75 | 76 |
77 |
78 |
Start building
79 |

Build interoperable Web3 applications powered by decentralised tools from the Ceramic ecosystem.

80 | 81 |
82 |
83 |
Explore Network Tools and Utilities
84 |

Run Ceramic nodes and interact with the Ceramic protocol.

85 | 86 |
87 | 88 |
89 |
90 |
91 |
92 |
Join our Community
93 |

Ceramic has a large and active community of developers. Here's how you can connect with us:

94 | 95 |
96 |
97 |
98 | 99 |
100 | ); 101 | } 102 | -------------------------------------------------------------------------------- /src/pages/index.module.css: -------------------------------------------------------------------------------- 1 | /** 2 | * CSS files with the .module.css suffix will be treated as CSS modules 3 | * and scoped locally. 4 | */ 5 | 6 | html[data-theme="dark"] header { 7 | color: #fff; 8 | } 9 | 10 | html, 11 | body { 12 | height: 100%; 13 | } 14 | 15 | .heroBanner { 16 | padding: 2rem 0; 17 | text-align: left; 18 | position: relative; 19 | overflow: hidden; 20 | } 21 | 22 | .heroBanner h1 { 23 | font-size: 1.5em; 24 | line-height: 1.2; 25 | } 26 | 27 | .heroBanner p { 28 | color: #fffdfd; 29 | font-size: 0.7em; 30 | font-weight: 300; 31 | line-height: 1.25; 32 | } 33 | 34 | .heroContent { 35 | max-width: 1240px; 36 | justify-content: center; 37 | align-items: center; 38 | display: flex; 39 | flex-direction: row; 40 | } 41 | 42 | @media (max-width: 768px) { 43 | .heroContent { 44 | flex-direction: column; 45 | } 46 | 47 | .heroContent img { 48 | width: auto; 49 | } 50 | } 51 | 52 | .productSection { 53 | background-color: #fff8f8; 54 | padding: 0 12px; 55 | } 56 | 57 | html[data-theme="dark"] .productSection { 58 | background-color: #1e1e1e; 59 | } 60 | .communitySection { 61 | background-color: #feece5; 62 | padding: 0 12px 50px; 63 | } 64 | 65 | html[data-theme="dark"] .communitySection { 66 | background-color: #1e1e1e; 67 | } 68 | 69 | .productCardsWrapper { 70 | max-width: 1240px; 71 | width: 100%; 72 | gap: 40px; 73 | margin: 0px auto; 74 | display: flex; 75 | flex-wrap: wrap; 76 | padding: 40px 0px; 77 | } 78 | 79 | .productCard { 80 | width: calc(50% - 20px); 81 | display: grid; 82 | grid-template-rows: auto 1fr auto; 83 | padding: 32px; 84 | border-radius: 8px; 85 | box-shadow: 0px 18px 42px 0px var(--shadow); 86 | flex-direction: column; 87 | justify-content: space-between; 88 | } 89 | 90 | @media screen and (max-width: 996px) { 91 | .productCard { 92 | width: 100%; 93 | } 94 | } 95 | 96 | @media screen and (max-width: 996px) { 97 | .heroBanner { 98 | padding: 2rem; 99 | } 100 | } 101 | 102 | .buttons { 103 | display: flex; 104 | align-items: center; 105 | justify-content: center; 106 | } 107 | 108 | header { 109 | padding-top: 50px; 110 | font-weight: bold; 111 | font-size: 1.75em; 112 | } 113 | 114 | screen-card { 115 | margin: 0px auto; 116 | max-width: 1240px; 117 | height: 100%; 118 | margin-bottom: 70px; 119 | display: flex; 120 | flex-direction: column; 121 | justify-content: center; 122 | align-items: center; 123 | } 124 | -------------------------------------------------------------------------------- /src/pages/markdown-page.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Markdown page example 3 | --- 4 | 5 | # Markdown page example 6 | 7 | You don't need React to write simple standalone pages. 8 | -------------------------------------------------------------------------------- /static/.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/.nojekyll -------------------------------------------------------------------------------- /static/CNAME: -------------------------------------------------------------------------------- 1 | developers.ceramic.network -------------------------------------------------------------------------------- /static/img/after-verify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/after-verify.png -------------------------------------------------------------------------------- /static/img/app-architecture-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/app-architecture-overview.png -------------------------------------------------------------------------------- /static/img/architecture-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/architecture-overview.png -------------------------------------------------------------------------------- /static/img/before-verify.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/before-verify.png -------------------------------------------------------------------------------- /static/img/ceramic-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/ceramic-overview.png -------------------------------------------------------------------------------- /static/img/data-model-table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/data-model-table.png -------------------------------------------------------------------------------- /static/img/eip-712-generate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/eip-712-generate.png -------------------------------------------------------------------------------- /static/img/example-application-ui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/example-application-ui.png -------------------------------------------------------------------------------- /static/img/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/favicon.png -------------------------------------------------------------------------------- /static/img/final-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/final-diagram.png -------------------------------------------------------------------------------- /static/img/generate-712.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/generate-712.png -------------------------------------------------------------------------------- /static/img/getting-started-img.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/getting-started-img.png -------------------------------------------------------------------------------- /static/img/graphiql.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/graphiql.png -------------------------------------------------------------------------------- /static/img/intro-dataverse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/intro-dataverse.png -------------------------------------------------------------------------------- /static/img/jwt-generate.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/jwt-generate.png -------------------------------------------------------------------------------- /static/img/logo.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | -------------------------------------------------------------------------------- /static/img/postman.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/postman.png -------------------------------------------------------------------------------- /static/img/protocol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/protocol.png -------------------------------------------------------------------------------- /static/img/query-interfaces.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/query-interfaces.png -------------------------------------------------------------------------------- /static/img/sandbox-extension.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/sandbox-extension.png -------------------------------------------------------------------------------- /static/img/schema_serto.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/schema_serto.png -------------------------------------------------------------------------------- /static/img/serto-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/serto-example.png -------------------------------------------------------------------------------- /static/img/sign-in.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/sign-in.png -------------------------------------------------------------------------------- /static/img/tech-architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/tech-architecture.png -------------------------------------------------------------------------------- /static/img/vc-playground.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/vc-playground.png -------------------------------------------------------------------------------- /static/img/verify-jwt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/verify-jwt.png -------------------------------------------------------------------------------- /static/img/verse.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/verse.png -------------------------------------------------------------------------------- /static/img/wallet-modal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ceramicnetwork/docs-docusaurus/233cda2f38a8994704a366d432227448bba92ada/static/img/wallet-modal.png --------------------------------------------------------------------------------