PeerborneConfig

Defined in: packages/core/src/peerborne-config.ts:256

PeerborneConfig is a settings object for peerborne.

Properties

compaction?

optional compaction?: Partial<CompactionConfig>

Defined in: packages/core/src/peerborne-config.ts:328

Configuration for history compaction. When provided with enabled: true, the document will periodically create snapshot nodes to compact the Merkle-DAG change history.

enableNetworkStats?

optional enableNetworkStats?: boolean

Defined in: packages/core/src/peerborne-config.ts:338

Enable network statistics tracking. When true, a NetworkStats counter container is created and accessible via peerborne.networkStats. Callers must invoke record*() methods explicitly; automatic event wiring will be added in a follow-up.

Default: false.

enableSigning?

optional enableSigning?: boolean

Defined in: packages/core/src/peerborne-config.ts:321

Enable application-level signing for ordinary sync and snapshots. Initial network loads, security advertisements, invitation catch-up, and BeeKEM membership operations are always signed and verified, regardless of this setting. Invitation creation and acceptance reject when it is false.

WARNING: With false, ordinary sync and snapshot signatures are not checked, so any peer that can decrypt document traffic can forge ordinary changes. Only use it in trusted development or testing environments.

Default

true

enableTopicValidators?

optional enableTopicValidators?: boolean

Defined in: packages/core/src/peerborne-config.ts:306

Enable GossipSub topic validators for transport-level authorization enforcement and peer scoring. They are installed during activation and removed during close(). The application receiver still validates messages when this optional transport check is disabled.

Default

false

helia?

optional helia?: HeliaInit & object

Defined in: packages/core/src/peerborne-config.ts:278

Configuration for Helia/libp2p.

Helia 7 accepts libp2p creation options here, not an already-created libp2p node.

Type Declaration

bitswap?

optional bitswap?: BitswapOptions

libp2p?

optional libp2p?: CreateLibp2pOptions<ServiceMap>

loadQuorumAllowSinglePeer?

optional loadQuorumAllowSinglePeer?: boolean

Defined in: packages/core/src/peerborne-config.ts:460

Allow the initial-load quorum gate to pass with a single responding peer when the effective K is 1.

Effective K can resolve to 1 because only one peer is known, or because loadQuorumK is configured as 1 even when multiple peers are known. When this flag is true, the loader may accept the sole probed peer’s negotiated advertisement and proceed with the full load. An explicit Q greater than 1 remains a hard floor and is not overridden by this flag.

Trust caveat: with K=1 there is no second opinion, so this flag selects single-peer trust semantics regardless of which advertisement protocol is negotiated. A warning is logged when this path is taken.

When false (the default), any effective-K=1 load fails with LoadQuorumFailedError. Callers that intentionally use one probe should either disable the quorum gate or enable this flag and accept the warning.

Default

false

loadQuorumEnabled?

optional loadQuorumEnabled?: boolean

Defined in: packages/core/src/peerborne-config.ts:376

Require Q distinct trusted signing authorities to agree on one V4 security-state and complete response-manifest digest. Every vote and selected response must match the locally captured trust tuple and fresh request challenge. An explicit Q is a hard floor, independent of peer availability. Distinct transport identities do not create extra votes.

Setting false permits selection of one trusted signed V4 response while retaining challenge, tuple, and frontier validation. It provides no independent corroboration and never permits unsigned bootstrap.

Default

true

loadQuorumK?

optional loadQuorumK?: number

Defined in: packages/core/src/peerborne-config.ts:392

Maximum number of peers to probe in parallel for the initial-load advertisement step. The effective K is min(loadQuorumK, knownPeers.length), so no more distinct peers are selected than are currently known.

When three peers are known, the default of 3 paired with the default Q requires two matching votes while limiting open latency and bandwidth. That numerical majority does not establish Byzantine fault tolerance without corresponding peer identity, selection, and authentication assumptions.

Default

loadQuorumQ?

optional loadQuorumQ?: number

Defined in: packages/core/src/peerborne-config.ts:424

Minimum number of accepted votes that must agree on the same negotiated advertisement digest. Together, loadQuorumK and this value define the configured Q-of-K policy. Once at least one peer is known, an explicit Q is a hard trust floor: if fewer than Q peers can be probed, loading fails closed instead of reducing Q to the currently reachable cohort. With no known peers (effectiveK = 0), the loader retains its new-document/no-peer skip path because there is no remote state to accept.

When Q is omitted, it is the strict numerical majority Math.floor(effectiveK / 2) + 1, derived from the effective K after limiting the configured K to the known-peer count.

Worked examples (effectiveK -> default Q):

effectiveK=1 -> Q=1 (single-peer pass-through; requires loadQuorumAllowSinglePeer: true)
effectiveK=2 -> Q=2 (both peers must agree)
effectiveK=3 -> Q=2
effectiveK=4 -> Q=3
effectiveK=5 -> Q=3
effectiveK=7 -> Q=4

An explicit valid Q is used as configured, even when it is not a majority of K. It is also preserved when a partition lowers the effective K, which makes the load fail closed if Q can no longer be reached. Choosing Q=1 or another non-majority threshold provides only that amount of agreement and must not be interpreted as Byzantine-majority protection.

Default

Math.floor(effectiveK / 2) + 1

loadQuorumTimeoutMs?

optional loadQuorumTimeoutMs?: number

Defined in: packages/core/src/peerborne-config.ts:438

Per-peer timeout (milliseconds) for the initial-load quorum advertisement probes. A peer that does not respond within this window is recorded as a non-vote (NOT a disagreement); see load-quorum.ts::decideLoadQuorum for the distinction.

Default chosen to be larger than typical RTT + protocol-negotiation latency on a wide-area mesh, but small enough that a partitioned peer does not stall document open by more than ~5 seconds.

Default

pubsubDocumentPrefix

pubsubDocumentPrefix: string

Defined in: packages/core/src/peerborne-config.ts:296

Prefix to apply to document pubsub topics.

Defaults to DEFAULT_DOCUMENT_TOPIC_PREFIX to namespace document traffic on the pubsub mesh. Topic names are routing labels, not authentication; wire decoding and admission checks remain mandatory.

Set to an empty string ('') to disable prefixing; topic strings will be the bare document path. Every peer sharing a document must use the same prefix.

Default

DEFAULT_DOCUMENT_TOPIC_PREFIX

resolveLoadSecurityCommitments?

optional resolveLoadSecurityCommitments?: (documentPath) => LoadSecurityCommitments | Promise<LoadSecurityCommitments>

Defined in: packages/core/src/peerborne-config.ts:268

Atomic, locally trusted control/group commitments for network loads. Required when serving or loading V4 state. The loader captures one tuple before probing; a missing or invalid tuple rejects the load. This callback does not derive trust from a peer’s response.

Parameters

documentPath

string

Returns

LoadSecurityCommitments | Promise<LoadSecurityCommitments>

resolveTrustedDocumentWriters?

optional resolveTrustedDocumentWriters?: (documentPath) => readonly unknown[] | Promise<readonly unknown[]>

Defined in: packages/core/src/peerborne-config.ts:258

Writer identities trusted out of band for a first network load.

Parameters

documentPath

string

Returns

readonly unknown[] | Promise<readonly unknown[]>

validateDocumentPath?

optional validateDocumentPath?: (documentPath, userPublicKey) => boolean | Promise<boolean>

Defined in: packages/core/src/peerborne-config.ts:484

Optional callback to validate document paths before creation.

Called when open() determines the document is new (i.e., load() returned false — no peers could provide the document). Note that load() can also return false during network partitions when peers are unavailable.

Validation runs before pubsub subscription and protocol handler registration, so rejected paths never temporarily join the topic.

If the callback returns false, open() throws new Error('Document path "<path>" is not allowed for the current user').
If the callback throws, open() rethrows the error as-is (if it is already an Error) or wraps it via new Error(String(err)).

May return a boolean or a Promise for async validation. Return true to allow creation, false to reject it. When absent, all document paths are allowed.

Parameters

documentPath

string

The path of the document being created.

userPublicKey

unknown

The public key of the current user.

Returns

boolean | Promise<boolean>

webrtcIceServers?

optional webrtcIceServers?: readonly Readonly<IceServer>[]

Defined in: packages/core/src/peerborne-config.ts:361

Optional override for the WebRTC ICE server list used by the webRTC() and webRTCDirect() transports. When undefined, the built-in DEFAULT_WEBRTC_ICE_SERVERS list (Google + Cloudflare + Twilio public STUN endpoints) is used so peers can discover their public address mappings without depending on Circuit Relay for the data plane.

Privacy note: Using the public STUN defaults discloses each peer’s public IP/port mapping to the third-party STUN operators. For privacy-sensitive deployments, pass [] to disable STUN entirely (e.g. for fully-internal LAN deployments where mDNS is sufficient), or supply self-hosted STUN/TURN servers.

Note: this field is informational once the libp2p config has already been built by defaultConfig; to actually change the ICE configuration, pass the override into defaultConfig(bootstrap, ice) (or getDefaultConfig(ice)) so it is wired into the transports at construction time.

Default

DEFAULT_WEBRTC_ICE_SERVERS