bR2bR Protocol v1.0 — Open Standard — bRRAIn Docs

The bRRAIn-to-bRRAIn (bR2bR) handshake protocol specification. Reference implementation under Apache 2.0; spec text under CC-BY 4.0.

bR2bR Protocol v1.0 — Open Standard

Status: Draft · Version: 1.0 · Published: 2026-04-20

bR2bR is a contractual handshake protocol between humans, AI agents, robots, and electronics. It operates on top of bRRAIn (the memory platform) but is independently implementable: any system can issue compliant identity tuples, publish Device Profiles, and run sessions.

1. Licensing

  • Reference implementation (source code of id.brrain.io + SDKs): Apache License 2.0
  • This specification document: Creative Commons Attribution 4.0 International (CC-BY 4.0)

Attribution for the spec: "bR2bR Protocol v1.0, bRRAIn · https://docs.brrain.io/bR2bR-spec-v1"

Implementers may ship conformant clients, registries, and gateways without royalty. Trademark "bRRAIn" and the bR2bR wordmark are not sublicensed by this spec.

2. Terminology

| Term | Definition | |---|---| | bRRAInID | 4-part hex install-level identifier. One per running bRRAIn install. | | bRRAInUserID | 5-part hex identifier for a user, device, agent, or organization. The unit that handshakes. | | Device Profile | AAS-compatible descriptor (IEC 63278) attached to a bRRAInUserID. | | Session | A billable, time-bounded exchange between two bRRAInUserIDs. | | Registry | The server that issues + attests identities. Canonical: id.brrain.io. | | Federation | The agreement between registries to honor each other's attestations. Post-1.0. |

3. Identifier formats

3.1 bRRAInID (install)

16 hex characters, conventionally rendered as aaaa-bbbb-cccc-dddd. Generated by CSPRNG. Collision probability at 64 bits is negligible for the supported population (< 10⁹ installs).

3.2 bRRAInUserID (user/device)

Five segments, hex-encoded, total 15–30 hex characters:

| Segment | Width | Meaning | |---|---|---| | country | 3 hex | ISO 3166 numeric, hex-padded (e.g. 840 = USA) | | city | 5 hex | Registry-assigned city code | | industry | 4 hex | ECLASS/IRDI tier mapped to 16-bit code | | device-type | 8 hex | class(1) + manufacturer(3) + model-family(2) + variant(2) | | user-number | 1–16 hex | Registry-assigned serial |

Canonical rendering: {country}-{city}-{industry}-{device-type}-{user-number} (all lowercase, - separators).

Normalization: Implementations MUST lowercase before comparison and strip whitespace/dashes. Hash functions for dedupe MUST operate on the canonical form.

Capacity: Per tuple position, ~1.8 × 10¹⁹ possible identities — the design target is "one identifier per atom of economic activity on Earth" and then some.

4. HTTP API surface

All endpoints return JSON. Public endpoints set Cache-Control: public, max-age=60 unless otherwise noted. TLS 1.2+ required.

4.1 Issue an install

POST /api/v1/registry/installs
  body:  { "org_id"?: int, "machine_fingerprint"?: string }
  200:   { "brrain_id", "brrain_id_formatted", "issued_at" }

4.2 Issue a user/device identity

POST /api/v1/registry/user-ids
  body:  { country_code, city_code, industry_code,
           device_class, device_manufacturer, device_model_family, device_variant,
           user_number?, public_profile? }
  201:   the full UserID row

4.3 Publish a Device Profile

POST /api/v1/registry/user-ids/{full_id}/device-profile
  body:  { asset_kind, asset_id_short, manufacturer_name?, model_name?,
           serial_number?, firmware_version?, safety_class?,
           industry_classification?, submodels?, pubkey_ed25519? }
  200:   the profile row

The submodels bag MAY contain arbitrary AAS submodel elements. Conformant registries MUST preserve round-trip.

4.4 Verify

GET /api/v1/registry/verify/{full_id}
  200:   { full_id, verification_state, public_profile, revoked,
           issued_at, verified_at?, display_name?, asset_kind?,
           manufacturer_name?, model_name?, pubkey_ed25519?,
           attested_by, attested_at }

The attested_by field is the hostname of the registry that produced this response. Federated caches MUST propagate this field unchanged.

4.5 Session metering

POST /api/v1/registry/sessions
  body:  { initiator_full_id, counterparty_full_id, purpose? }
  201:   { id, opened_at, last_heartbeat_at, … }

POST /api/v1/registry/sessions/{id}/heartbeat
  200:   { "ok": true }

POST /api/v1/registry/sessions/{id}/close
  body:  { reason? }
  200:   closed session with billed_ms

The initiator pays at the Protocol-defined rate (currently 5000 ppm USD/min = $0.005/min). Rate changes require a v-bump; existing sessions price at the opening rate.

Heartbeats MUST be sent at least every 60 seconds. Registries SHOULD close sessions whose last_heartbeat_at exceeds 90 seconds of staleness and charge only through that last heartbeat.

5. Cryptographic requirements

  • Ed25519 is the sole mandatory-to-implement signature algorithm at v1.0.
  • A Device Profile MAY include a pubkey_ed25519 (32 bytes hex). When present, all handshake messages from this identity MUST be signed.
  • Registries MUST NOT accept a Device Profile whose pubkey_ed25519 is non-empty but not 64 hex chars.

Future versions may add post-quantum signatures behind a capability bit; Ed25519 remains required for backward compatibility.

6. Federation (reserved for v1.1)

Registries MAY federate by honoring each other's attestations. The federation wire format is specified at v1.1 and is out of scope here. A conformant v1.0 registry MUST NOT reject an attestation from another registry outright — it MAY downgrade to verification_state: unverified until federation is configured.

7. Conformance

A "conformant bR2bR v1.0 registry" MUST:

  1. Issue bRRAInIDs and bRRAInUserIDs in the canonical format above.
  2. Expose the five HTTP endpoints in Section 4 with the specified schemas.
  3. Enforce heartbeat + 60s/90s timing on sessions.
  4. Meter the initiator and honor the rate in effect at session open.
  5. Expose attested_by and attested_at on every verify response.
  6. Preserve submodels round-trip on Device Profiles.

A conformant client MUST:

  1. Render canonical format on display.
  2. Send heartbeats at ≥ 60-second cadence for any open session it opened.
  3. Verify counterparties before handshake-dependent action.

8. Versioning and change control

Changes classified as:

  • Patch (v1.0.x): clarifications, non-behavioural typo fixes.
  • Minor (v1.x): additive endpoints, additional optional fields, new optional signature algorithms.
  • Major (vX): breaking changes to existing formats, rates, or endpoint shapes.

The Working Group (10–12 seats, recruited through 2026) decides version bumps by rough consensus plus registry-operator majority.

9. Acknowledgments

The identifier structure draws on ITU E.164 (country-prefix economy), ECLASS/IRDI (industry classification), and IEC 63278 Asset Administration Shell (Device Profile submodels). Any errors are bRRAIn's.

End of specification. Attribution text for implementers:

This software implements the bR2bR Protocol v1.0, originally specified by bRRAIn and published under CC-BY 4.0 at docs.brrain.io/bR2bR-spec-v1. Reference implementation: Apache License 2.0, github.com/Qosil/bRRAInWebsite.