OverviewQuickstart

Quickstart

Open Atlas, save a record on the device, announce it to peers, and read it back, in about 20 lines.

In this quickstart you save a record on the device, announce it to other peers, and resolve it on the receiving side. Each step names its outcome so you know what to expect before you run it.

The examples use Python-style syntax. The call names and parameters are the same in every Atlas SDK language: Rust, Python, Kotlin, Swift, browser and Dart.

Before you start

You need three things from your application:

InputWhat it is
IdentityThe principal your app acts as, with its DID and public key.
Storage pathA database location the app owns on the device.
SchemaThe name, version, and digest of the data your records carry.

Open Atlas

Open local identity and storage. The session is ready as soon as local storage is ready. Network readiness is observed separately, so the app works with no connection.

platform = Platform.open(identity, storage, application_protocols)

Outcome: a ready session. Possible errors are InvalidArgument and StorageFailure.

Save a record

Save application data under a replication scope. The call returns when the write is durable on this device. Replication to other peers continues in the background.

saved = platform.records.save(record, scope)

Outcome: a SaveResult with a stable entity_ref and a confirmed local commit. A local commit does not mean any other peer has the record yet.

Announce it

Publish a small notification that the record exists. The notification carries the entity_ref, not the data.

notice = platform.events.publish(event, publish_options)

Outcome: local acceptance of the event. Delivery to each peer is reported separately.

Listen on another peer

On the receiving peer, open a bounded receiver and wait for the next notification.

events = platform.events.subscribe(event_filter, subscription_options)
notice = await events.next()

Outcome: the next verified, fresh notification. Old and duplicate notifications are dropped for you.

Resolve the record

Fetch the data behind the notification. The state can arrive after the notification, so give the call a deadline.

record = await platform.records.resolve(notice.entity_ref, resolve_options)

Outcome: the latest authorized state available within the deadline. PendingState means the data has not arrived yet, not that it is missing.

Watch it sync and shut down

Observe replication progress for the scope, and stop the session when you are done.

progress = platform.sync.observe(scope)
await platform.shutdown()

Outcome: progress for the scope, then released resources. A committed write survives shutdown.

What you just relied on

Next steps