The collaboration-network profile is a signed, versioned bootstrap document. It selects one collaboration namespace and describes how a Runtime may find its initial Carrier peers. It is configuration authority only: the profile signer does not author user messages, grant capsule authority, establish Chat membership, or act as a Carrier peer merely by signing a profile.
A bootstrap Runtime can keep a stable UDP listener with the existing Runtime
configuration command, for example
elastos config set carrier_bind_addr 0.0.0.0:4433. Choose a free address for each
Runtime, restart it, then export
its bootstrap receipt. Gateway and full server startup use that address on each
restart. Invalid configuration or an occupied explicit address stops startup;
an absent setting keeps the default listener and ephemeral-port fallback.
The setting changes the listener address only. Carrier network policy and
collaboration authority keep their own checks.
Tip — pin the bootstrap Runtime's Carrier address before exporting its receipt. The bootstrap receipt, and so every Home's network file, records the bootstrap Runtime's exact IP address and UDP port. Without
carrier_bind_addr, a Runtime takes0.0.0.0:4433when that port is free and a random port otherwise, so a restart can move it. Pin a port that every joining Home can reach, for example0.0.0.0:4433:127.0.0.1answers only on the same machine, while the receipt usually names the LAN or public address. When two Runtimes share one machine, give each its own port. See Troubleshooting.
The canonical JSON envelope uses lexicographically ordered object keys with no
insignificant whitespace and has exactly three fields: payload, signature,
and signer_did. The canonical bytes of its payload field are signed with the
domain elastos.collaboration-network.profile.v1. The payload schema is
elastos.collaboration-network.profile/v1 and contains:
- a stable, canonical
network_id; - a revision beginning at 1 and increasing by exactly one;
previous_profile_sha256, absent at revision 1 and equal to the SHA-256 of the preceding canonical envelope thereafter;- the signer DID, which must equal the envelope signer;
- at most 16 unique Carrier bootstrap peers, each binding a canonical node ID to a canonical v1 connect ticket. Its topic is null, it contains one to eight complete endpoints, and every endpoint has that exact ID;
- an optional
default_conversationdescriptor containing one canonical raw SHA-256 CID. The signed profile authenticates the exact content-addressed grant bytes; the grant is not separately signed, and its CID is not secret.
The v1 default-conversation grant contains only its schema, the stable network
ID, a canonical conversation ID, a canonical sender service, and the
profile_scoped_signer admission policy. Each message payload has exactly the
shape { product, signed_profile }. The Runtime binds the operation to that
whole envelope, then verifies that the Profile authorizes both the sending
Runtime endpoint and the signer for the exact service and payload type. The
product receives only the inner payload and verified Profile. There is no
legacy payload parser. This is an open network-room policy; it does not prove
contact, private membership, delivery, or trust beyond that bounded authority.
Validation is pure. The caller supplies both the expected network ID and the
complete trusted profile-signer DID set. Validation never derives trust from a
release publisher, sources.json, a Carrier identity, or a hostname. It does
not read or write files, provision identity, connect Carrier, fetch or apply the
optional grant, join Chat, or create any session or state.
Runtime startup selects collaboration only from the owner-only canonical JSON
file collaboration-network-v1.json directly under the Runtime data root. Its
schema is elastos.collaboration-network.startup-config/v1 and its complete
field set is:
schema;expected_network_id;trusted_profile_signer_dids, the complete trusted profile-signer DID set;profile_chain_base64, the complete ordered signed profile chain beginning at revision 1, with every canonical envelope encoded as canonical standard base64;- optional
default_conversation_grant_base64, containing the exact canonical grant bytes named by the signed profile.
The file contains no release publisher, hostname, IP address, ambient seed, or fallback. Absence selects isolation. A present file is validated and accepted before Carrier subscription or worker startup; invalid permissions, bounds, encoding, trust, chain, or grant fail closed.
Every Home joins the shared Community room by default. The signed release names that network, and setup installs it; a Home stays isolated only when its person chooses isolation.
The release network lists one bootstrap peer: the Community node on the seed host. This node runs its own Runtime with its own account, data root, Carrier port and resource limits, apart from the release and update service. In 0.8.0 Carrier is direct-only: a Home reaches this node over a direct Carrier path, with no relay. Carrier owns connection policy and peer resolution through one connect-by-DID entry point. Relay support and cross-network acceptance are planned in #345 and #354.
The release availability contract while this node is unreachable is:
- Homes already connected keep exchanging Community messages and catch-up.
- A Home that starts or restarts cannot join Community.
- Discovery and new contact requests stop.
- New Direct messages show Sending. Runtime retries them for up to 24 hours, then shows Expired.
- Homes keep all messages they already received.
Chat states Community unreachable when its Community connection is unavailable, or Community can't connect. Restart Home to reconnect. after Home has used up its repairs (#451).
An address change requires the next signed network revision in a release. More bootstrap peers and participant Homes acting as bootstrap are tracked in #324.
The release pins the network in components.json as collaboration_network:
head_cid, the raw SHA-256 CIDv1 of the exact startup configuration bytes;expected_network_id;trusted_profile_signer_dids, the complete trusted signer set.
The release ships those bytes beside components.json as
collaboration-network-release-v1.json. The release signature covers
components.json, so the release publisher vouches for the pin, and the pin
fixes the exact configuration, network and signer set. Setup then checks the
configuration with the same validator Runtime startup uses. Runtime startup
itself still reads only collaboration-network-v1.json.
The release delivers that file the same way it delivers model-catalog.json.
Release staging binds it to the pin, the custodian signer also requires the
pin's network ID and signer set to equal the file's, and release
publication admits it only when its bytes match the pin and pass the startup
validator. Installed setup fetches the exact pinned CID from the trusted source
over Carrier, with the startup configuration's 3 MiB byte bound checked before
the body is read. elastos update and Home's System update also fetch it by its
pinned CID with the Runtime and components.json, while Home still runs and
before the new Runtime replaces the old one. elastos update installs it as its last
update step; System update installs it right after activation, before Home
restarts. A refusal before or during that step restores the previous release
files. Undo restores the earlier release and keeps the joined network, its
accepted revision, contacts, and messages, including state written after the
update. An older release pin cannot replace a newer accepted configuration.
Leaving Community is a separate action. A Home that stays isolated
fetches nothing. An offline update hop refuses a changed pin, like other support
changes.
The Home's owner can select Leave Community in System. This choice applies to the whole Home. Runtime stops Community messages, presence and Discovery, while it keeps the admitted network, accepted-head witness, contacts, Direct messages and stored history. Other Homes keep their own choices. A guest can see the setting; the current owner controls it.
The owner can select Rejoin Community to reverse the choice. Runtime uses the current admitted network head and the saved Discovery preferences. Restart and update preserve the owner-only membership record separately from the network configuration and product state. Previously published Discovery announcements keep their signed expiry; leaving stops their renewal.
Joining Community does not announce anyone. Chat files one Inbox request per
person; the answer is Always while Home is online, Only while Community is
open, Later or Never, and the Community section of System → Security offers Always, Only while open
and Hidden. Showing is a capability token the Runtime mints for that person
(subject: their principal; action message; resource
elastos://chat/presence/<network>/<conversation>/always or /while-open;
no expiry), kept in their owner-only
.AppData/ElastOS/Home/community-presence.json and never given to a capsule.
Every announcement validates it with all twelve capability checks against
the live store: the Runtime timer asks for /always, Chat's 15-second
heartbeat while Community is visible asks for /while-open. Hidden, a mode
change and a Profile change revoke the token; an epoch bump revokes every
grant, and Chat asks again. A shown person's signed presence carries their
Profile to the Community topic (including the seed's Community node),
expiring 45 seconds after the last renewal, and signs the Home's requests for
earlier posts. Undecided, Later and Never announce nothing. Discovery is a
separate choice, for being found outside Community and for contact requests.
Leave Community stops presence for everyone on the Home, whatever they chose.
After Undo, Community presence follows the Discovery switch in People again.
If you chose Hidden or Only while open in alpha.23 and Discovery is on, you
will be announced; turn Discovery off in People to stay hidden.
Setup and update apply the release network to the data root:
- A new Home receives
collaboration-network-v1.jsonfrom the release copy and prints one line saying it joins the Community room and how to stay isolated. - An update that pins a newer revision of the same network and signer set replaces the file only when the new chain strictly extends the installed chain. The accepted-head marker then advances at the next start.
- A Home that already holds a configuration for another network keeps it.
elastos setup --isolated(orinstall.sh --isolated) records the owner-only choicecollaboration-isolated-v1. Before the first start it also removes the release network file that setup installed, so Runtime never joins it; setup and update then leave the release network uninstalled. Setup refuses and keeps the file when Runtime already accepted a network (thecollaborationstate directory exists), because Runtime refuses to drop an accepted network, and when the file is not the network the installed release pins, because it then belongs to the Home's operator. Runtime startup also treats the recorded choice as isolation until it has accepted a network, so an interrupted--isolatedrun never joins, and startup and--isolatedshare one lock so they cannot interleave. Leaving Community after joining is a separate, later step.- Source-home setup keeps its explicit
ELASTOS_COLLABORATION_STARTUP_MODE(configuredorisolated) and ignores the release pin.
A release without collaboration_network leaves every Home's collaboration
configuration unchanged. The operator provisioning below creates the network
and its configuration bytes that a release then pins.
elastos collaboration-config creates fixture startup files and verifies exact
candidate files. The offline custodian creates production startup files through
the initial-profile operation below. Key creation, profile generation, and
verification are offline. The separate explicit local
bootstrap export attaches only to the selected running Runtime. The
configuration authority is the signer explicitly named in
trusted_profile_signer_dids. Runtime device, Carrier, Wallet, passkey, and
user-message authority keep their own identities and checks.
The production Community network's profile signer is the release maintainer
DID. Runtime checks each signing role separately: the signed release pins the
file's CID and its signer set, and profile signatures use their own domain,
elastos.collaboration-network.profile.v1. The approved offline release
custodian signs production profiles outside CI.
The existing release-signing interface, scripts/release-signer.py, uses the
custodian's Ed25519 PEM key through OpenSSL. The collaboration-config file
interface accepts an owner-only raw 32-byte Ed25519 key for the disposable test
and fixture networks below. Production keys stay in their existing custody
workflow.
The custodian runs the installed, reviewed release-signer.py with
--operation community-profile. This operation supports revision 1 with no
previous profile hash. Later chain revisions need their own reviewed operation.
It signs the exact approved profile through the existing maintainer PEM and
publicly verifies the signature before writing a new read-only output set.
The release/head signing operation keeps its existing domain checks.
Prepare inert community-profile-input.json with these exact fields:
schema (elastos.collaboration-network.signing-input/v1), source
(commit, tree), domain (elastos.collaboration-network.profile.v1),
profile (the unsigned profile schema above), default_conversation_grant
(the canonical grant), and trusted_profile_signer_dids (the approved set).
The profile names the existing maintainer DID, exactly one approved bootstrap
receipt (release preparation verifies the file with the Runtime's operator
receipt, which names one peer), and the raw CID of that grant. The grant names
the same network, the approved conversation, sender service chat, and policy
profile_scoped_signer. Before the DID prompt the signer shows the network,
conversation, revision, signer set, bootstrap node and its ticket addresses,
and the payload and grant hashes.
The bootstrap Runtime and its placement are explicit operator inputs; an
artifact host has its own installation role.
The protected custodian policy retains the source, interpreter, tool, OpenSSL,
PEM path, and file/total quotas described in the
release signer instructions.
Set operation to community-profile and manifest_sha256 to the exact input
file hash. Its community_profile object has these exact fields:
expected_network_idandconversation_id: the approved identifiers.revision:1;previous_profile_sha256:null.trusted_profile_signer_dids: the same explicit signer set as the input.profile_payload_sha256: SHA-256 of the canonical unsigned profile bytes.default_conversation_grant_sha256: SHA-256 of the canonical grant bytes.
Canonical bytes use sorted object keys, compact UTF-8 JSON, and no trailing newline. Keep this policy outside the candidate input directory. It approves the unsigned inputs before the final Community file CID or release manifest exists. Run the installed tool with a clean environment and confirm the complete maintainer DID at its prompt:
env -i /path/to/pinned-python -I -S /path/to/installed-release-signer.py \
--operation community-profile --manifest community-profile-input.json \
--policy /path/to/approved-community-policy.json \
--input-root /path/to/unsigned-community-input \
--output-root /path/to/new-community-outputThe output contains collaboration-network-release-v1.json and
collaboration-network-release-pin-v1.json. The latter supplies the
collaboration_network fragment for the components manifest, with the exact
startup-file CID, network ID and signer set. The tool checks ticket bounds,
canonical encoding and node binding. The reviewed, key-free Runtime verifier
checks complete transport semantics before the output goes into the source.
It reads only owner-only files, and the signer writes read-only (0444)
outputs, so check an owner-only copy:
install -d -m 700 /path/to/check
install -m 600 /path/to/new-community-output/collaboration-network-release-v1.json /path/to/check/
elastos collaboration-config verify \
--input /path/to/check/collaboration-network-release-v1.json
The release then carries the output like model-catalog.json: a reviewed
pull request puts the startup file at the repository root and the pin
fragment's collaboration_network object in components.json, and release
preparation binds that source pin to this exact output through
RELEASE_COMMUNITY_DIR and runs the package's own Runtime verifier
(Publishing a release). Profile signing
creates inert files; publication and activation use their own explicit
operator approval.
For an isolated test fixture, create a disposable authority key as a separate explicit action. Give the fixture an owner and cleanup condition, keep its trust store separate from real Homes, and keep its private key out of source and logs:
elastos collaboration-config create-authority-key --key <owner-only-key-path>
Export one canonical owner-only bootstrap receipt from the intended running local Runtime before returning to the offline flow:
elastos collaboration-config export-local-bootstrap-receipt \
--data-root <explicit-runtime-data-root> \
--runtime-kind gateway \
--output <owner-only-bootstrap-receipt>
Select gateway for an elastos gateway process or operator for an
elastos serve process. This explicit operator step reads only that exact
runtime kind's coordinates in the supplied data root,
attaches through the loopback operator boundary, and asks only the local
Carrier Provider for its ticket and node ID. It does not call a public
well-known endpoint, inspect Provider files, or create identity or product
state. Its output uses the existing bootstrap-peer contract:
{"connect_ticket":"<canonical-ticket>","node_id":"<canonical-node-id>"}.
The ticket is written only to the create-new owner-only file and is never
printed. The remaining key, generation, and verification steps are offline and
supply no hostname, address, or seed default. Generate revision 1 and then
verify the exact output:
elastos collaboration-config generate-initial \
--authority-key <owner-only-key-path> \
--network-id <network-id> \
--conversation-id <conversation-id> \
--bootstrap-peer <owner-only-bootstrap-receipt> \
--output <data-root>/collaboration-network-v1.json
elastos collaboration-config verify \
--input <data-root>/collaboration-network-v1.json
When the bootstrap Runtime's address changes, export a fresh bootstrap receipt and generate the next signed revision from the current file with the same authority key. The network ID, trusted signer set and default-conversation grant stay the same; only the bootstrap peers change:
elastos collaboration-config generate-revision \
--authority-key <owner-only-key-path> \
--input <current collaboration-network-v1.json> \
--bootstrap-peer <owner-only-bootstrap-receipt> \
--output <next collaboration-network-v1.json>
Ship the new revision in the next release with its pin; update then advances each joined Home along the same chain.
Generation fixes the logical sender service to Chat (chat); Runtime startup
separately binds the operation capsule to chat-room. The command creates the
canonical profile_scoped_signer grant, binds its raw SHA-256 CID into the
signed revision-1 profile, and writes the canonical startup configuration with
create-new owner-only semantics. Verification is pure: it uses the same
startup/profile/grant validators as Runtime but does not accept an
accepted-head marker, create a Runtime device identity, join Carrier, or write
product state. Its receipt contains only public identifiers and hashes; it
never prints the authority key or connect ticket.
At Runtime startup, an absent profile means isolated mode; Runtime never substitutes a network of its own. Joining the default network is a setup and update step governed by the release pin above. A profile with another valid network ID is a separate namespace and is rejected when a different network was requested. Updates fail closed on signature, canonicalization, bounds, signer, network, revision, or previous-hash errors.
The Runtime-internal loader accepts configuration only as the complete ordered canonical chain from revision 1 through the selected head. After configuration, an owner-only accepted-head marker binds the network ID, revision, exact head envelope hash, and canonical trusted-signer-set hash. While that namespace and marker are retained, every ordinary restart must present the complete chain containing the exact accepted head before advancing it; omission, rollback, replacement, fork, network change, and trust-root change fail closed. A present configuration namespace with a missing marker also fails closed. If the selected head names a default-conversation grant, its exact canonical bytes are required and verified against the signed CID. Loading this configuration does not create a Runtime device key, product state, or Carrier session.
The accepted-head marker is a retained local rollback witness, not an external or cryptographic rollback anchor. Deleting the entire collaboration state namespace or data root is an operator reset indistinguishable from first run. It does not protect against an actor who can rewrite or delete that whole root.