Integrate Logos into your application

Choose how your application reaches the Logos stack, and where the nodes it depends on run.

Version

This document is accurate for Testnet v0.3. Sections marked Planned describe work that is not part of a release yet.

This page describes how to incorporate the Logos stack, including Logos Blockchain, the Logos Execution Zone (LEZ), Logos Storage, and Logos Delivery, into an existing or planned product or decentralised application. It sets out two paths for integration, the benefits of each path, and what is currently available compared with what is still being built.

Each capability on this page carries one of two statuses:

Status	Meaning
Available	Part of a release, with documentation you can follow today.
Planned	Not released yet. Some of it already works on development branches. The Logos Core specifications are still raw drafts, so this material describes where the project is heading, not a frozen interface: names and details can change. Integrator feedback is welcome: tell us what you need.

The basics

• Logos capabilities are modules. Blockchain, LEZ, Storage, and Delivery each ship as Logos modules that the Logos Core runtime loads, isolates, and connects. See What is Logos? for the architecture.
• There are two ways to integrate. Build your application from Logos modules and run it in Logos Basecamp or logosctl (recommended), or host Logos Core inside your own application and bundle the modules you need.
• Both paths use the same runtime and the same modules. They differ in how your application is built and distributed, not in what it can reach.
• Modules call each other through their contracts, never directly. The same call works whether the target module runs in the same process, in another process, or on another machine, so whether a node runs locally or remotely is a deployment choice.

Two choices that shape an integration

What your application is built from

Building your application from Logos modules is the recommended way to integrate, and the one that gets the most out of Logos. Your application runs in the Logos runtime that Basecamp and logosctl already provide: it calls the modules it depends on through the runtime, and other modules can call it in turn. It also inherits what the runtime adds on top of the protocols: module isolation, distribution without a central service, and a place in an ecosystem where other developers build on your modules. See What you get.

An application not built from modules, such as an existing mobile wallet or a server backend, needs to host Logos Core itself instead. It links the Logos Core host library, bundles the runtime and the modules it uses, and calls those modules from its own code. It keeps its own code and distribution, and gives up some of what the runtime offers. See What you give up compared with a Basecamp app.

Where the node runs

The major components of the Logos stack run as nodes. Blockchain and LEZ nodes follow their chain, hold its state, and relay transactions; Storage and Delivery nodes take part in their peer-to-peer networks to store, retrieve, and carry data. A node can run in one of two places:

• On the user's device. This is how Logos is designed to be used: its nodes are deliberately lightweight so that they run on consumer hardware. No third party sees what the user queries or submits, and the node talks to the peer-to-peer networks directly. The node can run:
  • inside the application, which costs artefact size and the CPU, network, battery, and storage a running node uses while it runs, or
  • on another device the user owns, such as a home computer running Basecamp or logosctl, which the user's application reaches remotely. The user keeps the privacy of running their own node without running it on, for example, their phone.
• In your infrastructure. You run the nodes and the user's application holds the keys. This suits exchanges, custodians, and wallets that cannot run a node on the user's device, at a cost to privacy. Serving many users' applications this way is under design.

Which of these suits your users bears on privacy as well as on cost. See What a remote node costs you.

Your situation	How to integrate	Where the node runs
New desktop or mobile application (mobile is Planned)	Build a Basecamp app	On the user's device, in the application or on another device they own
Server backend, exchange, or custodian	Build a logosctl service, or host Logos Core	Your infrastructure
Existing desktop application	Host Logos Core	On the user's device, in the application or on another device they own, or in your infrastructure
Existing mobile application	Host Logos Core (Planned)	On the user's device, in the application or on another device they own, or in your infrastructure

The modules you integrate

Planned

This section describes the target architecture. Today the Logos Blockchain node and wallet are combined in a single blockchain_module, and the LEZ module (lez_core) provides the LEZ wallet and reaches an LEZ sequencer directly. Separating each chain into a wallet module and a node module is planned.

Each Logos chain is served by two modules: a wallet module and a node module.

• Wallet modules handle keys, derivation, signing, and proving. Both chains need proofs generated on the client: LEZ executes and proves transactions on private accounts locally, and Logos Blockchain value transfers carry a zero-knowledge proof in place of a signature. Wallet modules therefore run where the keys are, which is normally in the user's application. Support for hardware signers, starting with Keycard, is planned.
• Node modules follow their network over peer-to-peer connections, serve chain state, and relay the transactions the wallets produce.
• An LEZ node depends on a Logos Blockchain node to obtain the finalised LEZ state. An LEZ node that acts as a sequencer also uses a Logos Blockchain wallet (the dotted line).
• A wallet reaches its node only through the node API. This is what lets the node run in the application, on another device the user owns, or in your infrastructure without any change to the wallet.

Storage and Delivery follow the same pattern without a wallet: an application calls the Storage module or the Delivery module directly. Logos Delivery protects its network against spam with Rate Limiting Nullifiers (RLN), and publishers hold an RLN membership registered on LEZ.

Build a Basecamp app or logosctl service

Recommended. Your application is a set of Logos modules: one or more core modules for its logic and, for a graphical application, a UI module. Users run it in Logos Basecamp, and operators run the core modules headlessly with logosctl on a server, as a Logos node.

What you get

• The whole stack by composition. Blockchain, LEZ, Storage, and Delivery are modules your modules depend on. An application composed from them inherits their metadata protection and private state support, whether or not its developer built anonymity measures directly.
• Isolation. Each module runs in its own operating system process, so a crash in one module does not take down the others. A plain process only contains crashes. If you need containment as well, you will be able to select a stronger placement per module (Planned): the sandbox placement adds limits enforced by the operating system on the file system, network, process creation, and resources, using namespaces and cgroups on Linux, and the runtime refuses to start the module if the platform cannot provide them. A container placement is also planned. Finer permission management is in development.
• A fault and audit boundary. Each module is developed, audited, and upgraded independently.
• Distribution without a central service. Once Basecamp or logosctl is installed, modules are discovered in its catalogue, and downloading them over Logos Storage instead of HTTP is being rolled out. Signature checks are planned: Logos's own keys are trusted by default, users can add the publishers they trust, and each package is checked when it is downloaded and again before it runs.
• An ecosystem around your modules. Other developers' modules can depend on yours and call it, the same way yours call the Logos modules. A native Basecamp integration makes your product part of the stack rather than a client of it.

Platforms

Platform	Status
Linux and macOS desktop, in Basecamp	Available
Linux server, with logosctl	Available
Windows	In progress
Android and iOS, in Basecamp	In progress

Start building

• Build and run a Logos core module
• Wrap a C library as a Logos module
• Build a Logos C++ UI module
• Install and load a module in Logos Basecamp
• Run a Logos node with logosctl

A module is a compiled native library that exposes its methods through a C-compatible interface (FFI). It is usually a shared library, and can be linked statically where dynamic loading is not available. In principle, any language that can build such a library can be used to write one. A Logos SDK for the language makes this much easier: it provides the module plumbing and generates typed clients for the modules yours depends on. For the languages with an SDK, see Languages.

Host Logos Core in your application

Planned

Hosting Logos Core in a third-party application is currently supported only on development branches. This path is not released yet.

Your application keeps its own code, user interface, and distribution, and hosts the Logos Core runtime inside it:

1. Your application ships the runtime and the module packages it needs inside its own bundle.
2. At start-up, your application starts the runtime through the Logos Core host library for its language. The host libraries wrap a small C interface, which is what makes bindings for further languages practical, and your application does not need to run a particular event loop.
3. Logos Core loads the modules, resolves their dependencies, and manages their lifecycle, exactly as it does in Basecamp.
4. Your application calls modules through typed clients generated from each module's contract (a CDDL schema), and subscribes to their events.

Your own application code does not need to be implemented as a Logos module. Choosing to package it as a module allows your application to be easily distributed via Basecamp.

This is not a library wrapper per Logos component. Your application gets the module runtime itself, so every Logos module, including third-party modules, is reachable the same way, and the runtime chooses where each module runs.

Where modules run

The runtime can run each module in a process of its own, run every module in a single runtime process, or run inside your application's process with no child processes at all. This last option is what is required by platforms that forbid spawning processes, such as iOS. The placement does not change your application's code. However, a module in a process of its own is kept from taking down the other modules and your application with a fault, and only the sandbox and container placements add containment beyond that.

What you give up compared with a Basecamp app

• Basecamp distribution. You ship and update your application through your own channels, such as app stores, so decentralised discovery and distribution do not apply to it.
• The ecosystem effect. Code that is not a module cannot be reused by other developers' modules or run by Basecamp users.
• Some isolation. When modules run inside your application's process, a fault in a module can reach your application.
• Packaging work. You build and ship the runtime and modules for each platform you support.

If you host Logos Core yourself, consider publishing your core logic as modules as well, so that Basecamp users and other developers can reach it too.

Languages

The table shows where a Logos SDK exists or is planned. Any language that can produce a native library with a C-compatible interface can still be used to write a module without one. Not planned yet means no work is scheduled. If you need that language, tell us.

Language	Write a module	Host Logos Core in your application
C++	Available	Planned
Rust	Available	Planned
Kotlin	Not planned yet	Planned
Swift	Not planned yet	Planned
Go	Not planned yet	Not planned yet
JavaScript and React Native	Planned	Not planned yet
Dart and Flutter	Not planned yet	Not planned yet
Python	Not planned yet	Not planned yet: logos-logoscore-py runs logosctl as a separate process

Mobile

Planned

Logos Basecamp for Android and iOS is planned. Kotlin and Swift libraries that let a mobile application host Logos Core, with its modules bundled inside the application package, are also planned. Integrator feedback is welcome on which comes first.

The Logos Core design includes a mode intended for mobile and simple packaged applications, in which the modules are linked into the application and called directly.

Whether a phone runs the Logos nodes itself depends on how it is used. A phone on Wi-Fi and on charge at home is a very different setting from one on a mobile network and on battery, and running a Blockchain node on a phone has not been benchmarked yet.

What the design already ensures is that the two halves can be split. Wallet modules run on the phone, where the keys are, and the nodes they use can run on another device the user owns, such as a home computer. Running them in your infrastructure for your users is under design. See Calling modules locally and remotely.

Calling modules locally and remotely

A module is never linked against another module's library, the way a program is linked against the shared libraries it depends on. It calls the other module's contract through the runtime, which authorises the call and carries it to wherever the target runs.

Locally

Available. Each module runs in its own process and calls other modules over a local socket. An access policy, set before the runtime starts, decides which modules may call which, for example only the modules that declare a dependency on it.

Planned. A runtime without Qt, the single-process and in-application placements described under Where modules run, and access grants per method rather than per module.

Remotely: a node on another device the user owns

Planned

Peering works on development branches. This functionality is not released yet.

A user runs a node on another device they own, in Basecamp or logosctl, and pairs their application with it through peering, either by comparing a six-digit code on both screens or with a single-use invite. The runtime on that device exports the node module, and the application's runtime imports it. Paired runtimes connect over mutual TLS 1.3 with pinned keys.

The imported module appears under a local name. Modules in the application, and the application's generated clients, call it exactly as they would call a local module, and its events arrive the same way. When the remote runtime restarts, the import becomes ready again; calls in flight at that moment fail, and events sent in the meantime are not redelivered.

Both sides decide. The importing runtime chooses which of its own modules may use the import, and the exporting runtime's policy chooses what each of them may reach. A grant currently opens the whole module, including administrative methods such as stopping the node, so pair only with applications you trust.

Remotely: a node in your infrastructure

Planned

Peering at this scale is in the design stage. The draft Logos Core specification defines the access-control pieces described below. This functionality is not implemented yet.

The mechanism is the same peering: your users' applications import the node modules that your runtime exports. Peering as it stands is built for a small number of runtimes that know each other, such as a phone and its owner's home computer. To serve many users from your infrastructure, it needs to gain the following:

The draft specification covers who may do what:

• Grants per method and per event. A grant can limit a user's application to the methods it needs, such as reading chain state and relaying transactions. The limit is enforced before the module's code runs.
• Expiry and revocation. Each grant can expire, and can be revoked individually while the node keeps running.
• Audit. Every access decision leaves a record.
• Automated onboarding. Enrolling a user's runtime is itself an operation that a service of yours can be authorised to perform, so users do not have to be paired by hand.

There is no anonymous access, by design: each user's runtime is enrolled with its own keys, so the operator can tell users apart.

Still open are how users are enrolled in practice, how one user's events are kept from reaching another, and rate limits and connection scale, which the specification leaves to each deployment.

If your integration depends on this, tell us how many users would connect, and which methods they would need.

Why remote module access

• One interface, local or remote. The same contract and the same generated client serve a module wherever it runs. Moving a node from the application to another device is a deployment change, not a code change.
• Typed contracts and generated clients. Every module publishes its contract as a CDDL schema, and clients are generated from it for each supported language. There is no request format to hand-write or keep in sync, and a module can describe its own contract at run time.
• Events built in. Subscriptions work across the network, so an application receives new blocks or incoming messages as they happen, without polling and without a separate notification service.
• No RPC server to build. A module's contract is its remote interface. Exposing a module is a deployment setting, not a separate service to write, version, and operate.
• Any module. Storage, Delivery, and your own modules are exposed and reached the same way as the chain nodes.
• Composition across machines. With peering, a module in one runtime can depend on a module in another, so a distributed application is built from the same parts as a local one. This enables hybrid deployments: for example, users can run a one-command node for storage or staking on a NAS or Raspberry Pi, and access it from a phone or laptop.
• Access control on both sides. The importing runtime chooses which of its modules may use an import, and the exporting runtime's policy chooses what each remote module may reach. Anything the policy does not list is refused.
• Mutual authentication. Peering pairs runtimes with a code or a single-use invite, issues certificates to each, and connects them over a secure channel with pinned keys. Each connection is opened with a single-use ticket that expires within seconds and is bound to that connection, so there is no long-lived credential to steal or replay.
• No downgrade. A connection that cannot be mutually authenticated is refused. It never falls back to a weaker one.
• Nothing to probe. A caller that is refused cannot tell whether the module exists.
• Explicit compatibility. When a connection is set up, each side sends the hash of the contract it holds, and the connection is refused before any call if the two differ. A mismatch fails up front instead of in use.

What a remote node costs you

Running the node somewhere other than in the application changes what the node operator can see. When the same party runs both the application and the node, such as a custodian running both in its own infrastructure or a user pairing with a node on their own home computer, the trust assumptions are the same as running the node locally. When they are different parties, the node operator sees your network identity, the credentials you connect with, and what you query and submit. You also rely on that operator for correctness: a remote node can return wrong results, and the connection does not prove otherwise.

What that exposes depends on the component:

• LEZ. Private transactions remain mostly private. The node receives commitments and nullifiers, but private account state is encrypted by the recipient's viewing key and stays with the account owner. Any public account involved in a transaction is visible, as it is to every node, so the operator may be able to correlate public accounts with a user's PII.
• Logos Blockchain. Transaction contents are public on the ledger in the current testnet version. Privacy comes from the Blend Network, which hides where a transaction originates. Submitting through someone else's node bypasses Blend for that transaction, so the operator can link its contents to you. To benefit from Blend, submit through your own node.
• Storage and Delivery. Privacy comes from taking part in the mix, gossip, and peer discovery networks directly. Routing reads and writes through someone else's node weakens it.

Tell us what you need

Integrator feedback shapes which Planned items come first. When you talk to us, it helps to know:

• Which platforms you ship on: desktop, server, Android, iOS, or the web.
• Which language and framework your application uses.
• Where you want the nodes to run: in the application, on another device your users own, or in your infrastructure.
• Which major components you need: LEZ, Logos Blockchain, Storage, or Delivery.
• Whether you would ship your logic as Logos modules, and what would stop you.
• For a node you run for your users: how many users would connect, and which methods they would need.

Talk to your Logos point of contact, or join the conversation on the Logos Discord or the Logos forum.