Once a node is running with at least one live adjacency, exchanging application data comes down to three moves: frame a typed payload into a DDO, push it toward a destination DIN, and handle arriving DDOs in a callback. The division of labor is fixed—the application owns the typeset and the payload bytes; the core owns origin, timestamp, and delivery.
push(din, ddo)What travels: the DDO
A DDO carries four elements, and knowing who fills each one is what makes the exchange predictable:
| Element | Filled by | Note |
|---|---|---|
| Typeset | application | identifies the schema for reading the payload |
| Payload | application | the opaque bytes defined by the application |
| Origin | core | the producing node; read-only |
| Timestamp | core | placed on the shared dATS time; read-only |
Because origin and timestamp are assigned by the core and never rewritten downstream, a DDO keeps the same identity across every hop, driver, and retry. That property is what the rest of this page relies on.
Frame a typed payload
Framing means turning application data into a typeset plus a serialized payload. The typeset is the schema identifier that tells the receiver how to read the bytes—version, field order and size, byte order of multibyte values, units, optional fields, and what to do with an unknown version.
Serialize deterministically: the same values must always produce the same bytes. Fields have defined sizes, multibyte values a fixed byte order, and any variable-length content is preceded by its length. Handing the core a raw native struct breaks this—the compiler may insert padding, enum widths differ across languages, and endianness varies by architecture. The payload stays an opaque sequence to the core; it becomes meaningful only when the receiver matches it to the typeset's decoder. A compact measurement schema, for instance, might fix schema_version, flags, measurement_id, value, and unit_code at known offsets—but the typeset may equally describe JSON, CBOR, or Protocol Buffers.
Push to a peer
Sending is a single call: push(destination_din, ddo). The application names the destination DIN and the core does the rest—assigns origin and timestamp, selects the queue, and chooses a route.
pushFor the send to succeed, three conditions have to hold, and they are independent of each other: the peer must be reachable (a mapping or a valid route), the policy must authorize the exchange, and—if the receiver needs comparable timestamps—dATS must be synchronized.
Losing the current channel mid-send does not force you to rebuild anything. The core retries on the next driver or searches for another hop; identity, typeset, timestamp, and payload are unchanged. What happens on failure is governed by policy: setDDOPolicy chooses discard, retry, or retry with increasing delays, and setOptions sets queue sizes and the maximum number of attempts. A retry policy provides at-least-once delivery—the message arrives, but a resend can produce a duplicate.
Handle it in an on-received callback
There are two reception models, and an SDK can expose either or both:
pulladdTypeset · automaticWith polling, a notification tells you a DDO is available in the sender's queue; you check how many are pending and obtain each payload with an explicit pull. With a typeset handler, addTypeset registers a function invoked automatically when a DDO of that type arrives; high-level SDKs can pull the payload for you and drop it into an inbox.
Either way, the on-received callback runs in the core's own context, which imposes two rules. First, do not run slow work in the core thread—copy what you need and hand the actual processing to an application queue, an event loop, or concurrent storage, so a heavy consumer never stalls the node. Second, protect the core from your own errors; an exception escaping the callback must not take the core down with it. When you are done, release the resource that represents the DDO according to the platform's model.
doPerform, and keep them valid for the whole lifetime of the node.At-least-once means planning for duplicates and reorder
Because retries and alternate routes can duplicate a DDO or deliver it out of order, deduplication and ordering are the application's responsibility, not the core's. Put the identifiers you need inside the payload—defined by the typeset schema—rather than expecting the transport to supply them:
- a message ID or idempotency key to discard duplicates;
- a sequence number to restore order;
- a correlation ID to tie a reply to its request;
- optionally a state version or validity window.
The core guarantees delivery under the configured policy; making that delivery exactly-once or strictly ordered is done in the payload.
Large payloads: framing vs streaming
DDO size and the link's MTU are independent quantities. When a frame exceeds what a driver can move in one operation, the transport segments it and reassembles it on the other side; the receiver sees the DDO only after the whole frame is rebuilt, and an error on any chunk invalidates the entire object.
This is the line between the two exchange modes. Fragmentation rebuilds a single atomic message, so a DDO is the right unit for a typed, self-contained payload. When data is continuous and consumed as it arrives, open a stream session instead (use → send/receive → end): streams share identities and transports with DDOs but keep separate queues and delivery semantics.
Minimal sequence
The send and receive halves, arranged around the native lifecycle. Register the handler before the core starts; construct the DDO from a typeset and payload; let push add origin and timestamp.
DaasAPI node(&eventHandler); // IDaasApiEvent reports "a DDO has arrived"
node.doInit(sid, din);
node.enableDriver(_LINK_INET4, "192.168.1.2:4000");
node.map(remote_din, _LINK_INET4, "192.168.1.3:4000");
node.addTypeset(MEAS_TYPESET, onMeasurement);// per-typeset handler, BEFORE doPerform
Ddo ddo(MEAS_TYPESET, payload); // frame: typeset + serialized payload
node.push(remote_din, ddo); // send: core assigns origin + timestamp
node.doPerform(PERFORM_CORE_THREAD); // process; onMeasurement fires on arrival
// ...
node.doEnd();
// onMeasurement runs in the core context:
// copy or enqueue the payload, return quickly, then release the DDO resource.
Method names and signatures above are illustrative; each SDK exposes this same flow through its own idiomatic constructs—listeners or event streams for the callback, automatic resource management for the release—and its reference documentation gives the exact types and concurrency guarantees.