Ceramic Core

This package contains the implementation of the core Ceramic protocol. It's exposed using a simple JavaScript API.

Getting started

Installation

$ npm install @ceramicnetwork/core

Usage

import Ceramic from '@ceramicnetwork/core'
import TileDocument from '@ceramicnetwork/stream-tile'

import IPFS from 'ipfs-core'
import dagJose from 'dag-jose'
import { convert } from 'blockcodec-to-ipld-format'

const format = convert(dagJose)

const ipfs = Ipfs.create({
    ipld: { formats: [format] },
})

const config: CeramicConfig = {}
const ceramic = await Ceramic.create(ipfs, config)

// create document example
const tileDocument = await TileDocument.create(ceramic, { test: 123 })

Ceramic API

Complete Ceramic core API is available on Ceramic API.

Development

Run tests:

$ npm test

Run linter:

npm run lint

Contributing

We are happy to accept small and large contributions. Make sure to check out the Ceramic specifications for details of how the protocol works.

Index

References

Enumerations

MsgType

Interfaces

Type aliases

Object literals

References

StateStore

Re-exports StateStore

Type aliases

IPFSPubsubMessage

IPFSPubsubMessage: { data: Uint8Array; from: string; key: Uint8Array; seqno: Uint8Array; signature: Uint8Array; topicIDs: string[] }

Type declaration

data: Uint8Array
from: string
key: Uint8Array
seqno: Uint8Array
signature: Uint8Array
topicIDs: string[]

LoadDocumentFunc

LoadDocumentFunc: <T>(streamId: CommitID) => Promise<T>

Type declaration

- <T>(streamId: CommitID): Promise<T>
- Type parameters
  - T: Stream
  Parameters
  - streamId: CommitID
  Returns Promise<T>

Props

Props: { networkName?: string; pinningBackends?: PinningBackendStatic[]; pinningEndpoints?: string[]; stateStoreDirectory?: string }

Type declaration

Optional networkName?: string
Optional pinningBackends?: PinningBackendStatic[]
Optional pinningEndpoints?: string[]
Optional stateStoreDirectory?: string

PubsubMessage

PubsubMessage: UpdateMessage | QueryMessage | ResponseMessage

QueryMessage

QueryMessage: { id: string; stream: StreamID; typ: QUERY }

Type declaration

id: string
stream: StreamID
typ: QUERY

Registry

Registry: Map<number, StreamHandler<Stream>>

RepositoryDependencies

RepositoryDependencies: { anchorService: AnchorService; conflictResolution: ConflictResolution; context: Context; dispatcher: Dispatcher; handlers: HandlersMap; pinStore: PinStore; stateValidation: StateValidation }

Type declaration

anchorService: AnchorService
conflictResolution: ConflictResolution
context: Context
dispatcher: Dispatcher
handlers: HandlersMap
pinStore: PinStore
stateValidation: StateValidation

ResponseMessage

ResponseMessage: { id: string; tips: Map<string, CID>; typ: RESPONSE }

Type declaration

id: string
tips: Map<string, CID>
typ: RESPONSE

Task

Task<TaskResultType>: () => Promise<TaskResultType>

Type parameters

TaskResultType

Type declaration

- (): Promise<TaskResultType>
- Returns Promise<TaskResultType>

UpdateMessage

UpdateMessage: { stream: StreamID; tip: CID; typ: UPDATE }

Type declaration

stream: StreamID
tip: CID
typ: UPDATE

Variables

Const APPLY_ANCHOR_COMMIT_ATTEMPTS

APPLY_ANCHOR_COMMIT_ATTEMPTS: 3 = 3

Const BASE_CHAIN_ID

BASE_CHAIN_ID: "eip155" = "eip155"

Const CHAIN_ID

CHAIN_ID: "inmemory:12345" = "inmemory:12345"

Const DEFAULT_CACHE_LIMIT

DEFAULT_CACHE_LIMIT: 500 = 500

Const DEFAULT_LOCAL_ETHEREUM_RPC

DEFAULT_LOCAL_ETHEREUM_RPC: "http://localhost:7545" = "http://localhost:7545"

Const DEFAULT_NETWORK

DEFAULT_NETWORK: INMEMORY = Networks.INMEMORY

Const DEFAULT_STATE_STORE_DIRECTORY

DEFAULT_STATE_STORE_DIRECTORY: string = path.join(os.homedir(), ".ceramic", "statestore")

Const DID_MATCHER

DID_MATCHER: "^(did:([a-zA-Z0-9_]+):([a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)*)((;[a-zA-Z0-9_.:%-]+=[a-zA-Z0-9_.:%-]*)*)(/[^#?]*)?)([?][^#]*)?(#.*)?" = "^(did:([a-zA-Z0-9_]+):([a-zA-Z0-9_.-]+(:[a-zA-Z0-9_.-]+)*)((;[a-zA-Z0-9_.:%-]+=[a-zA-Z0-9_.:%-]*)*)(/[^#?]*)?)([?][^#]*)?(#.*)?"

Const IPFS_GET_TIMEOUT

IPFS_GET_TIMEOUT: 60000 = 60000

Const IPFS_GET_TIMEOUT

IPFS_GET_TIMEOUT: 60000 = 60000

Const IPFS_GET_TIMEOUT

IPFS_GET_TIMEOUT: 60000 = 60000

Const IPFS_MAX_RECORD_SIZE

IPFS_MAX_RECORD_SIZE: 256000 = 256000

Const IPFS_RESUBSCRIBE_INTERVAL_DELAY

IPFS_RESUBSCRIBE_INTERVAL_DELAY: number = 1000 * 15

Const MAX_POLL_TIME

MAX_POLL_TIME: 86400000 = 86400000

Const MAX_PROVIDERS_COUNT

MAX_PROVIDERS_COUNT: 100 = 100

Const MAX_RESPONSE_INTERVAL

MAX_RESPONSE_INTERVAL: 300 = 300

Const POLL_INTERVAL

POLL_INTERVAL: 60000 = 60000

Const SAMPLE_ETH_TX_HASH

SAMPLE_ETH_TX_HASH: "bagjqcgzaday6dzalvmy5ady2m5a5legq5zrbsnlxfc2bfxej532ds7htpova" = "bagjqcgzaday6dzalvmy5ady2m5a5legq5zrbsnlxfc2bfxej532ds7htpova"

Const TESTING

TESTING: boolean = process.env.NODE_ENV == 'test'

Const packageJson

packageJson: any = require('../package.json')

Const textDecoder

textDecoder: TextDecoder = new TextDecoder('utf-8')

Const textDecoder

textDecoder: TextDecoder = new TextDecoder('utf-8')

Const textEncoder

textEncoder: TextEncoder = new TextEncoder()

Functions

anchorUpdate

anchorUpdate(ceramic: Ceramic, stream: Stream): Promise<void>

- Defined in packages/core/src/state-management/__tests__/anchor-update.ts:6
Parameters
- ceramic: Ceramic
- stream: Stream
Returns Promise<void>

asIpfsMessage

asIpfsMessage(data: PubsubMessage, from?: string): IPFSPubsubMessage

- Defined in packages/core/src/pubsub/__tests__/as-ipfs-message.ts:12
PubsubMessage as raw IPFS pubsub message.

Parameters
- data: PubsubMessage
  
  PubsubMessage to transform into raw form.
- Optional from: string
  
  Peer ID that ostensibly sent the message.
Returns IPFSPubsubMessage

betweenTimeout

betweenTimeout<T>(betweenMs: number): UnaryFunction<Observable<T>, Observable<T>>

- Defined in packages/core/src/pubsub/message-bus.ts:14
Stop emitting if +betweenMs+ passed since the last emitted value.

Type parameters
- T
Parameters
- betweenMs: number
  
  max interval between the sequential values.
Returns UnaryFunction<Observable<T>, Observable<T>>

buildQueryMessage

buildQueryMessage(streamId: StreamID): QueryMessage

- Defined in packages/core/src/pubsub/pubsub-message.ts:53
Parameters
- streamId: StreamID
Returns QueryMessage

buildResubscribeQueue

buildResubscribeQueue(logger: DiagnosticsLogger): TaskQueue

- Defined in packages/core/src/pubsub/incoming-channel.ts:19
Parameters
- logger: DiagnosticsLogger
Returns TaskQueue

commitAtTime

commitAtTime(stateHolder: StreamStateHolder, timestamp: number): CommitID

- Defined in packages/core/src/conflict-resolution.ts:219
Parameters
- stateHolder: StreamStateHolder
- timestamp: number
Returns CommitID

createCeramic

createCeramic(ipfs: IpfsApi, config?: CeramicConfig & { seed?: string }): Promise<Ceramic>

- Defined in packages/core/src/__tests__/create-ceramic.ts:12
Parameters
- ipfs: IpfsApi
- Optional config: CeramicConfig & { seed?: string }
Returns Promise<Ceramic>

createIPFS

createIPFS(overrideConfig?: Record<string, unknown>): Promise<IpfsApi>

- Defined in packages/core/src/__tests__/ipfs-util.ts:12
Create an IPFS instance

Parameters
- Default value overrideConfig: Record<string, unknown> = {}
  
  IFPS config for override
Returns Promise<IpfsApi>

defaultHandlers

defaultHandlers(): Registry

- Defined in packages/core/src/handlers-map.ts:9
Returns Registry

delay

delay(ms: number): Promise<void>

- Defined in packages/core/src/pubsub/__tests__/delay.ts:1
Parameters
- ms: number
Returns Promise<void>

deserialize

deserialize(message: any): PubsubMessage

- Defined in packages/core/src/pubsub/pubsub-message.ts:93
Parameters
- message: any
Returns PubsubMessage

filterExternal

filterExternal(ownPeerId$: Observable<string>): MonoTypeOperatorFunction<IPFSPubsubMessage>

- Defined in packages/core/src/pubsub/incoming-channel.ts:106
Pass only messages from other IPFS nodes.

Parameters
- ownPeerId$: Observable<string>
  
  Own peer id.
Returns MonoTypeOperatorFunction<IPFSPubsubMessage>

ipfsToPubsub

ipfsToPubsub(peerId$: Observable<string>, pubsubLogger: ServiceLogger, topic: string): UnaryFunction<Observable<IPFSPubsubMessage>, Observable<PubsubMessage>>

- Defined in packages/core/src/pubsub/pubsub.ts:19
Deserialize incoming message in an internal observable that does not emit if error happens. Log a successfully deserialized message.

Parameters
- peerId$: Observable<string>
  
  own IPFS node peer id
- pubsubLogger: ServiceLogger
  
  logger that dumps a successfully deserialized message
- topic: string
  
  IPFS pubsub topic we listen
Returns UnaryFunction<Observable<IPFSPubsubMessage>, Observable<PubsubMessage>>

messageHash

messageHash(message: any): string

- Defined in packages/core/src/pubsub/pubsub-message.ts:42
Parameters
- message: any
Returns string

messageTypeToString

messageTypeToString(type: MsgType): string

- Defined in packages/core/src/dispatcher.ts:22
Parameters
- type: MsgType
Returns string

Const noop

noop(): void

- Defined in packages/core/src/pubsub/task-queue.ts:3
Returns void

Const normalizeStreamID

normalizeStreamID(streamId: StreamID | string): StreamID

- Defined in packages/core/src/ceramic.ts:135
Parameters
- streamId: StreamID | string
Returns StreamID

pickLogToAccept

pickLogToAccept(state1: StreamState, state2: StreamState): Promise<StreamState>

- Defined in packages/core/src/conflict-resolution.ts:69
Given two different StreamStates representing two different conflicting histories of the same stream, pick which commit to accept, in accordance with our conflict resolution strategy

Parameters
- state1: StreamState
  
  first log's state
- state2: StreamState
  
  second log's state
Returns Promise<StreamState>

the StreamState containing the log that is selected

Const promiseTimeout

promiseTimeout(ms: number, promise: Promise<any>): Promise<any>

- Defined in packages/core/src/utils.ts:97
Parameters
- ms: number
- promise: Promise<any>
Returns Promise<any>

serialize

serialize(message: PubsubMessage): Uint8Array

- Defined in packages/core/src/pubsub/pubsub-message.ts:65
Parameters
- message: PubsubMessage
Returns Uint8Array

streamFromState

streamFromState<T>(context: Context, handlersMap: HandlersMap, state: StreamState, update$?: (init: StreamState) => Observable<StreamState>): T

- Defined in packages/core/src/state-management/stream-from-state.ts:14
Build Stream from the current state and update feed.

Type parameters
- T: Stream
Parameters
- context: Context
  
  Ceramic context
- handlersMap: HandlersMap
  
  available stream handlers
- state: StreamState
  
  current state of the stream
- Optional update$: (init: StreamState) => Observable<StreamState>
  
  On-demand feed of updates for the stream
  - - (init: StreamState): Observable<StreamState>
    - Parameters
      - init: StreamState
      Returns Observable<StreamState>
Returns T

swarmConnect

swarmConnect(a: IpfsApi, b: IpfsApi): Promise<void>

- Defined in packages/core/src/__tests__/ipfs-util.ts:48
Connect two IPFS instances via swarm.connect

Parameters
- a: IpfsApi
  
  Initiates connection
- b: IpfsApi
  
  Receives connection
Returns Promise<void>

Const tryStreamId

tryStreamId(id: string): StreamID | null

- Defined in packages/core/src/ceramic.ts:144
Parameters
- id: string
Returns StreamID | null

verifyAnchorCommit

verifyAnchorCommit(dispatcher: Dispatcher, anchorService: AnchorService, commit: AnchorCommit): Promise<AnchorProof>

- Defined in packages/core/src/conflict-resolution.ts:28
Verifies anchor commit structure

Parameters
- dispatcher: Dispatcher
  
  To get raw blob from IPFS
- anchorService: AnchorService
  
  AnchorService to verify chain inclusion
- commit: AnchorCommit
  
  Anchor commit
Returns Promise<AnchorProof>

Object literals

Const DEFAULT_ANCHOR_SERVICE_URLS

DEFAULT_ANCHOR_SERVICE_URLS: object

[Networks.DEV_UNSTABLE]

[Networks.DEV_UNSTABLE]: string = "https://cas-dev.3boxlabs.com"

[Networks.ELP]

[Networks.ELP]: string = "https://cas.3boxlabs.com"

[Networks.LOCAL]

[Networks.LOCAL]: string = "http://localhost:8081"

[Networks.MAINNET]

[Networks.MAINNET]: string = "https://cas.3boxlabs.com"

[Networks.TESTNET_CLAY]

[Networks.TESTNET_CLAY]: string = "https://cas-clay.3boxlabs.com"

Const DEFAULT_APPLY_COMMIT_OPTS

DEFAULT_APPLY_COMMIT_OPTS: object

anchor

anchor: boolean = true

publish

publish: boolean = true

sync

sync: SyncOptions = SyncOptions.PREFER_CACHE

Const DEFAULT_CREATE_FROM_GENESIS_OPTS

DEFAULT_CREATE_FROM_GENESIS_OPTS: object

anchor

anchor: boolean = true

publish

publish: boolean = true

sync

sync: SyncOptions = SyncOptions.PREFER_CACHE

Const DEFAULT_LOAD_OPTS

DEFAULT_LOAD_OPTS: object

sync

sync: SyncOptions = SyncOptions.PREFER_CACHE

syncTimeoutSeconds

syncTimeoutSeconds: number = 3

Const DEFAULT_LOAD_OPTS

DEFAULT_LOAD_OPTS: object

sync

sync: SyncOptions = SyncOptions.PREFER_CACHE

Const ETH_CHAIN_ID_MAPPINGS

ETH_CHAIN_ID_MAPPINGS: object

Maps some of Ethereum chain IDs to network configuration

eip155:1

eip155:1: object

chain

chain: string = "ETH"

chainId

chainId: number = 1

network

network: string = "mainnet"

networkId

networkId: number = 1

type

type: string = "Production"

eip155:3

eip155:3: object

chain

chain: string = "ETH"

chainId

chainId: number = 3

network

network: string = "ropsten"

networkId

networkId: number = 3

type

type: string = "Test"

Const SUPPORTED_CHAINS_BY_NETWORK

SUPPORTED_CHAINS_BY_NETWORK: object

[Networks.DEV_UNSTABLE]

[Networks.DEV_UNSTABLE]: string[] = ["eip155:3", "eip155:4"]

[Networks.ELP]

[Networks.ELP]: string[] = ["eip155:1"]

[Networks.INMEMORY]

[Networks.INMEMORY]: string[] = ["inmemory:12345"]

[Networks.LOCAL]

[Networks.LOCAL]: string[] = ["eip155:1337"]

[Networks.MAINNET]

[Networks.MAINNET]: string[] = ["eip155:1"]

[Networks.TESTNET_CLAY]

[Networks.TESTNET_CLAY]: string[] = ["eip155:3", "eip155:4"]

Ceramic Core

Getting started

Installation

Usage

Ceramic API

Development

Contributing

License

Index

References

Enumerations

Classes

Interfaces

Type aliases

Variables

Functions

Object literals

References

CeramicConfig

CeramicModules

CeramicParameters

StateStore

Type aliases

IPFSPubsubMessage

Type declaration

data: Uint8Array

from: string

key: Uint8Array

seqno: Uint8Array

signature: Uint8Array

topicIDs: string[]

LoadDocumentFunc

Type declaration

Type parameters

T: Stream

Parameters

streamId: CommitID

Returns Promise<T>

Props

Type declaration

Optional networkName?: string

Optional pinningBackends?: PinningBackendStatic[]

Optional pinningEndpoints?: string[]

Optional stateStoreDirectory?: string

PubsubMessage

QueryMessage

Type declaration

id: string

stream: StreamID

typ: QUERY

Registry

RepositoryDependencies

Type declaration

anchorService: AnchorService

conflictResolution: ConflictResolution

context: Context

dispatcher: Dispatcher

handlers: HandlersMap

pinStore: PinStore

stateValidation: StateValidation

ResponseMessage

Type declaration

id: string

tips: Map<string, CID>

typ: RESPONSE

Task

Type parameters

TaskResultType

Type declaration

Returns Promise<TaskResultType>

UpdateMessage

Type declaration

stream: StreamID

tip: CID

typ: UPDATE

Variables

Const APPLY_ANCHOR_COMMIT_ATTEMPTS

Const BASE_CHAIN_ID

Const CHAIN_ID

Const DEFAULT_CACHE_LIMIT