Get the SDK

Guides/Bootstrap a segment

Guide

Bootstrap a segment

Bring up the first node and turn it into the entry point for a new segment — the hosting side of discovery, seen from the beginning.

Most nodes enter a network that already exists: they search, find an entry point, and join. But that entry point has to come from somewhere. When no segment exists yet, one node has to open it—claim a SID, take a concrete identity, bring up a transport, and start answering for the segment so that other nodes can discover and join it.

This guide follows that path: bringing up the first node and turning it into the entry point for a new segment. It is the hosting side of discovery, seen from the beginning.

identitySID + DIN
coreinitialization
driver +reachable address
expose thesegment
acceptancefor the join
corestartup
peers discover,join, and sync
The bootstrap path, end to end.

The first node defines the segment

A segment does not exist as an object somewhere; it exists because at least one node claims a SID and starts answering for it. The first node is therefore the one that fixes the segment's identity and becomes the point other nodes reach.

This changes how identity is assigned compared with joining. A node that joins an existing network may start with a SID or DIN set to 0, because it will acquire or confirm those values during the join. The first node has no one to acquire them from: it assigns itself a concrete SID—the logical domain it is opening—and a unique, non-zero DIN within that domain.

SID/DIN may be 0acquired during join
SID chosen · DIN concreteno negotiation
Identity is negotiated when joining, and assigned when opening.

Sharing this SID is what will later establish membership for other nodes—but membership alone never guarantees delivery. Even after the segment is open, a peer still needs a usable link or route, a driver, and a policy that authorizes the exchange.

Bring up identity and a transport

Initialization applies the chosen SID and DIN to the local node, and only then is at least one driver enabled with a local address.

doInit(sid, din)node identity
enableDriver(link, uri)technology + local address

For a node that must host a segment, the local address matters: it has to be one that other nodes can actually reach. An IP driver binds a reachable interface and port; BLE, serial, or a DriverKit transport uses its own address format. A loopback or otherwise unreachable address will initialize cleanly and still leave the segment invisible to everyone else.

Each bootstrap step is verified before the next. If initialization or driver activation fails, the node does not continue with a partial configuration—it releases what it created or applies an alternative configuration. A half-open node that has claimed a SID but exposed no reachable transport is worse than one that has not started at all.

Expose the segment for discovery

Bringing up a driver does not by itself make the segment discoverable. The node also has to take a role that answers discovery requests.

setDiscoveryState controls that role, with four settings: disabled, search only, host only, and bidirectional. To open a segment, the first node uses host only (respond to discovery and offer entry) or bidirectional (also search for other networks). The other two settings—disabled and search only—never expose the segment and would leave joining nodes with nothing to find.

joining node
node exposingSID + entry + link
Discovery has two roles; the first node takes the hosting one.

When a discovery request arrives, a hosting node responds by indicating its entry node, its SID, and the link over which the peer can reach it. That response is what the joining node selects before performing the join.

Open acceptance for the join, then let it tighten

Reachability and authorization are separate properties. A node can be reachable and still refuse traffic whose origin does not satisfy its acceptance policy. setAcceptRequestsLevel sets that boundary along a ladder from strict to permissive:

none
mapped nodes only
+ same network
+ routed traffic
all
The acceptance ladder, strict to permissive.

The default accepts mapped nodes and nodes on the same network. That creates a chicken-and-egg problem at bootstrap: the very first contact from a node that wants to join comes from a peer that is not yet mapped and not yet a confirmed member. Discovery handles this by temporarily requiring the node to accept messages even from nodes it has not mapped; once the join completes and the mapping exists, the ordinary policy applies again. In practice this means the hosting node opens its acceptance wide enough to receive the first contact and lets it return to a stricter level once peers are established—rather than leaving it permissive indefinitely.

Routing does not bypass any of this: every node applies its own acceptance rules before accepting or forwarding, so opening a segment is not the same as trusting whatever appears on it.

Register events before you start

The core reports what happens through the event interface (IDaasApiEvent), and it can only report events for a handler that was registered before the core started producing them. For a hosting node the relevant events include: a node accepted as an incoming participant, a network detected or a join completed, dATS synchronization completed, remote node state, and an available DDO.

Callbacks run in the core's own context. Anything expensive—storage, parsing, application logic—should be handed to an application queue, event loop, or worker so it does not slow the core thread. The handler also has to stay valid for the entire lifetime of the node, and it must protect the core from its own errors.

Start processing

doPerform starts the core. With a dedicated thread the call is made once and internal processing runs on its own. In cyclic mode, typical of embedded and real-time systems, progress must be driven continuously—a single call does not keep the node alive.

doInit(sid, din)
enableDriver(link, uri)
setDiscoveryStatehost / bidirectional
setAcceptRequestsLevel
doPerform(mode)
Call order for a node that opens a segment.

Once the core is running, the node does the hosting work automatically: it answers discovery, negotiates joins, completes time synchronization, and creates the first mapping for each peer that comes in.

What a join looks like from the host side

From the first node's perspective, admitting a new participant is a short sequence driven by the control plane:

discovery requestarrives
host offers entrySID · entry node · link
peer selectsand joins
time sync +effective SID/DIN
first mappingcreated
events fireaccepted · joined · synced
Admitting a participant, from the host's point of view.

The joining node receives its effective SID and DIN from this exchange—the values it must use from that point on, replacing any temporary 0. On the host side, the result is a concrete adjacency: a mapping that ties the new peer's logical identity to the technology and address used to reach it. Two mapped nodes are already the smallest working network; further peers and forwarding extend the topology from there.

The first node anchors dATS

Every node has its own clock, which drifts relative to the others. dATS brings all of them onto a reference shared by the segment, without a central time server. The first synchronization exchange with a joining node computes the offset that node needs; once acquired, the peer produces shared time locally as local time + offset, and later exchanges correct accumulated drift.

joining nodelocal time
+ offset
shared timeof the segment

Because it opens the segment, the first node is the reference the earliest peers align to. setATSMaxError sets the tolerated offset; getSyncedTimestamp returns a shared time only while the node is connected and synchronized. Timestamps assigned to a DDO at its source are never rewritten downstream, so the shared reference stays meaningful end to end.

Readiness

The first node has finished bootstrapping the segment when:

At that point the node is not just alive—it is an entry point other nodes can find and join.

Minimal sequence

The opening path uses the same native calls as any node, arranged for a host that starts a segment rather than joining one. Note the absence of an up-front map: peers are not known in advance here—they arrive through discovery and join, and their mappings are created by that exchange.

C++ · libDaas
DaasAPI node(&eventHandler);              // register IDaasApiEvent BEFORE starting

node.doInit(sid, din);                    // concrete identity: this node opens SID
node.enableDriver(_LINK_INET4, "192.168.1.2:4000");  // a reachable local address

node.setDiscoveryState(/* host or bidirectional */); // expose the segment
node.setAcceptRequestsLevel(/* wide enough for first contact */);
node.addTypeset(/* handler for DDOs peers will send */);   // optional

node.doPerform(PERFORM_CORE_THREAD);      // start; peers can now discover and join
// ... node answers discovery, negotiates joins, syncs time, maps peers ...
node.doEnd();                             // stop and release resources

Persist what you opened

Once the segment is up, the node can retain the configuration needed to reopen it on restart: its effective identity, drivers, mappings, policies, and useful topology state, saved through IDepot. For the first node the effective SID and DIN are simply the values it assigned—there were no negotiated values to capture—but drivers and any mappings built during operation are still worth persisting.

On restart the saved configuration is a starting point, not proof of anything: the node re-enables its drivers, re-exposes the segment, and verifies its mappings before treating them as usable.

From here

With one node hosting the segment, additional nodes come up on the discovery + join path and reach this node as their entry point. When addresses are known in advance, manual configuration—a direct map between peers—is the alternative to discovery. Either way, the operational model stays the same: nodes, identities, and DDOs, over whichever transports the drivers provide.

Watch a segment come up node by node.

Open the Lab Simulator