Entities & Sovereignty

What you’ll get here

what an “entity” is in Smart Engines, how the network remembers it, and the two sovereignty modes — partial and full — that decide who signs for it on-chain.

Everything you create through Smart Engines — an account, a token, an HCS topic, a smart-app, a smart-agent — is an entity. Every entity carries a label that answers one question: who has to sign to act on this thing? That label is the sovereignty mode, and it’s enforced by the type system at compile time and at every request boundary at runtime, not by a checkbox in a UI.

🧠 For Normies

An “entity” is just any on-chain object the system manages for you. “Sovereignty” is about control: does the validator cluster sign for it alone, or do you share control with it? Smart Engines makes you pick one of two answers, and then it enforces your choice cryptographically.

---

What an entity is

An entity is a binding: an on-chain ID, tied to a chain, tied to the validators that govern it, tied to its DKG-generated key material. These are the entity types:

Entity type	Example	Created by
account / wallet	A managed chain account	user / smart-app
token	An XRPL issued token	user / smart-app
topic	A Hedera HCS topic	user / smart-app
smart-app	A deployed application identity	user
agent	A smart-agent identity	user
settlement-quorum	Cross-cluster settlement set	protocol
protocol-treasury	Protocol-owned account, one per chain. It does not pay for customer entity creation, which is payer-funded	genesis
protocol-runner-pool	Protocol-owned account, one per chain, that holds the runner-reward share	genesis
cluster-operator	A cluster’s on-chain identity	genesis
faucet	Testnet only: the account the test-token faucet dispenses from, under its own canonical rule	testnet genesis
tenant-secrets-master	Per-environment key entity that protects app secrets	protocol

🧠 For Normies

Users and smart-apps create the everyday things (accounts, tokens, topics). The protocol itself creates a few special entities — like the treasury that pays network fees — but those use the exact same “no single key” machinery. There’s no privileged backdoor entity.

The entity registry

Each entity produces a binding record that the network stores on every validator and replicates between them. The binding bytes are also pinned to IPFS as content-addressable public proof. The binding records which validators govern the entity, the threshold t, and the per-slot public keys.

🧠 For Normies

The “binding” is the network’s memory of an entity: which validators are responsible for it and how many of them have to agree to act on it. Every validator keeps a copy, and a public fingerprint is pinned to IPFS so it can’t be quietly rewritten.

---

Who pays to create an entity: the payer funds it

Creating an entity costs money on the underlying chain — funding a new account’s reserve, paying the create-transaction fee, issuing a token. In Smart Engines, the wallet creating the entity funds it. The smart-app pays by default; a customer can opt in to pay for their own. The payer is resolved in one place — the explicit payer in the request, otherwise the authenticated wallet, otherwise the request is refused with 400 — and never silently falls back to a protocol or operator key.

This holds on Hedera and XRPL, the chains that are live today, and for accounts and tokens alike. What the payer funds is only the chain cost — the new entity’s on-chain authority is native multisig from birth, controlled by the canonical rules, exactly as described below. Paying for an entity does not make you its sole signer.

Entity shape	Example chains	What “payer-funded” means
Create-with-key	Hedera Live, Solana Coming next	Payer is the create-transaction fee-payer; the multisig is the controlling key from the first block
Account-model	XRPL Live, Stellar Coming next	Payer funds the new address; validators then threshold-sign the multisig install and master-key lock. An XRPL token is its own issuer account, and any issuer flags it requested (compliant, wipeable) are set first, before the multisig install
Deterministic address	Bitcoin Coming next, Polkadot Coming next	Payer signs a funding transfer to the pre-derived multisig address; no finalize step

🧠 For Normies

When you (or your app) create an account or token, you pay the blockchain’s fee for it — not Smart Engines, not some shared house wallet. But paying the bill doesn’t hand you the keys: the thing is born under the validator multisig and its public rules from the very first moment. You funded it; you don’t unilaterally control it.

Note — not to be confused with cold-start funding

A separate, one-shot genesis funding wallet exists only to fund the protocol treasury at network birth; it plays no part in everyday customer entity creation. Deleting it at the end of genesis is built, not yet enabled. Customer entities are payer-funded, full stop.

---

How an entity is created: host-mediated, two-phase

Entity creation does not hit the validator directly. The internet-facing door is the host tier (smart-host BaaS). The host authenticates the caller, checks entity ownership, and resolves the source/payer server-side, then relays the request to the validator over the cluster-internal network. The validator’s transaction-prepare surface is not publicly routable; the SDK reaches entity creation only through the host’s /api/v3/baas/entities/... endpoints.

Creation itself is two-phase and payer-signed:

1. Prepare — POST /api/v3/baas/entities/prepare-create (host) → the validators run the per-entity DKG (binding persisted, nothing submitted on-chain yet) and return the unsigned payer-funding transaction.

2. Execute — the caller signs the funding blob and calls POST /api/v3/baas/entities/execute-create (host); the validators finalize — threshold-signing the multisig install where the chain needs it — and the entity is live under its native multisig.

This is why “payer-funded” and “not your sole signer” hold at once: the payer signs only the funding leg in phase 1; the authority is the multisig the validators install in phase 2.

🧠 For Normies

You never talk to the validator over the open internet. You talk to the host, which checks who you are and then relays your request inward. Creating an account takes two steps: the system hands you an unsigned “pay for this” transaction, you sign and return it, and only then does the network switch on the account — already under the shared multisig, not under your key.

Agents are payer-funded entities too

A smart-agent is created the exact same way — entityType: 'agent' is a first-class citizen of the same two-phase prepare→execute flow, on XRPL. An agent is an account-shaped DKG entity bound to a type=agent rule; it follows the same path as an account. It is funded by the payer and born under the validator multisig, identical to an account or token. Two-phase agent creation settles only on XRPL, so a two-phase agent on any other chain is refused (400).

---

The two sovereignty modes

There are exactly two modes:

securityMode: 'partial' | 'full'

The default is 'full'.

Caution

There is no owner-only mode (an owner key with no validator in the signing path). Any request carrying another securityMode, such as 'none', fails validation at the schema boundary.

Mode	Who signs	What’s on-chain
partial (product name: “mixed”)	User + validator both sign	A nested authorization set: the user’s key and the validator multisig
full	Validator multisig alone	The validator multisig only

The schema also enforces an invariant: partial requires both an entityId and an appOwnerPublicKey; full requires entityId (the owner key is ignored).

🧠 For Normies

• partial (“mixed”): you and the validators both have to sign — like a joint account where both signatures are required. You can always veto.
• full: the validator cluster signs alone (still as a quorum, never one machine). You delegate the signing entirely, but it’s still a group of validators, not a single key.

Note there is no “the cluster holds your key alone with no quorum” option and no “single key” option. Both modes are multi-party.

---

What the chain actually sees

The validator multisig is never a single opaque key. It is always a visible, chain-native, multi-member authorization set — so anyone looking at a block explorer (HashScan for Hedera, Bithomp for XRPL) can see the multi-member structure. Each chain expresses it with its own native primitive. The members are either the entity’s own DKG slot keys or the validators’ own keys for that chain:

Chain	On-chain authorization primitive
Hedera Live	KeyList of ed25519 keys, with a threshold
XRPL Live	SignerList of member accounts, with a quorum (master key disabled)
Stellar Coming next	Weighted signer set via setOptions (low/med/high thresholds)
Polkadot Coming next	pallet_multisig — deterministic SS58 address from sorted signatories + threshold

🧠 For Normies

“Visible multisig” is a deliberate product promise: the multi-party control isn’t hidden inside one clever key — it shows up on the public explorer as an honest-to-goodness list of signers with a “need N of them” rule. You can verify the decentralization yourself.

Signer structure: partial vs full

%%{init: {'flowchart':{'htmlLabels':true,'curve':'basis'}}}%%
flowchart TD
    subgraph FULL["full — validator multisig alone"]
        F0["On-chain authorization set"]
        F0 --> FT["threshold t of n"]
        FT --> FV1["validator key 1"]
        FT --> FV2["validator key 2"]
        FT --> FVN["… validator key n"]
    end

    subgraph PARTIAL["partial / mixed — user + validator"]
        P0["On-chain authorization set"]
        P0 --> POuter["outer threshold = 2"]
        POuter --> PUser["user / appOwner key"]
        POuter --> PInner["validator multisig (nested)"]
        PInner --> PIT["inner threshold t of n"]
        PIT --> PV1["validator key 1"]
        PIT --> PV2["validator key 2"]
        PIT --> PVN["… validator key n"]
    end

🧠 For Normies

In full, the chain requires “any t of the n validators.” In partial, the chain requires “the user, plus any t of the n validators” — your key is one of the required signers, so nothing happens without you. On Hedera that’s a nested KeyList; on XRPL a weighted signer set.

---

Per-entity DKG: fresh slots for every entity

Every entity created in partial or full mode runs its own DKG ceremony, so every entity gets fresh slot keys; slot keys are never reused across entities. Each validator holds only its own share of each slot key; the cluster publishes only the public keys. Some entities, such as XRPL entities created through the API, list each validator’s own key for that chain instead of slot keys; those validator keys are the same across the entities that list them.

When the validator set changes later, the cluster reshares the off-chain secret shares — and the slot public keys stay the same, so an on-chain list built from slot keys does not change.

🧠 For Normies

Each thing you create gets a fresh set of slot keys — no two entities share one, so cracking one tells an attacker nothing about another. If validators come and go, they re-share the off-chain pieces among themselves, but the slot keys published on the blockchain stay put.

---

Sovereignty is not the same as rules

Two orthogonal questions run before any transaction is signed:

Question	Concern	Lives in
Who signs this?	Sovereignty — key topology	securityMode + the on-chain authorization set
Is this action allowed right now?	Rules — business policy	the Rules Engine

A rule (e.g. “minting only allowed during this window”) can fire in either sovereignty mode. They compose; they don’t replace each other.

---

Next steps

DKG & TSSThe DKG ceremony that produces each entity’s keys.

Zero Single-SigWhy the on-chain set is always multi-member.

Rules EngineThe public policy layer that gates actions.

Network & TiersWhere these entities are created and signed.

GlossaryTerm definitions.