Skip to main content

Namespaces

Namespaces are Fabric-X's unit of logical partitioning within a network. Where classic Fabric uses multiple channels to separate workloads, Fabric-X uses a single channel (arma) and splits it into namespaces. Each namespace is backed by a dedicated postgres table per committer.

What a namespace is​

A namespace is:

  • A logical name registered on-chain via a namespace-creation transaction.
  • A physical table (ns_<name>) in every committer's postgres database.
  • A scope for token-sdk-x applications — state reads and writes carry a namespace qualifier.

Namespaces are cheap. You can create many per network, and ChainLaunch adds rows to each committer's state database as part of the namespace-creation transaction committing.

Creating a namespace​

Via the web UI​

  1. Open the network detail page for your Fabric-X network.
  2. Click Create namespace.
  3. Enter a name. Fabric-X enforces the regex ^[a-z0-9_]+$ with a maximum length of 60 characters: lowercase letters, digits, and underscores only — no hyphens, no uppercase. The UI rejects invalid names client-side with a toast; if a hyphenated or uppercase name reaches the network it comes back as MALFORMED_NAMESPACE_ID_INVALID.
  4. Pick the submitter organization — the party whose router will broadcast the creation transaction.
  5. Submit.

The UI waits for the transaction to commit and surfaces the resulting txId.

Via the API​

curl -s -u admin:admin123 \
  -X POST "http://localhost:8100/api/v1/networks/fabricx/$NETWORK_ID/namespaces" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "token",
    "submitterOrgId": 1,
    "waitForFinality": true
  }'

Response:

{
  "id": 17,
  "name": "token",
  "status": "committed",
  "txId": "fa5670f38f45..."
}

Fields:

FieldMeaning
nameNamespace name. Must be unique within the network. Required regex: ^[a-z0-9_]+$, max 60 characters. Hyphens and uppercase are rejected.
submitterOrgIdThe organization whose router will broadcast the transaction.
waitForFinalityIf true, the call blocks until the transaction commits. If false, returns immediately with status: "pending".
finalityTimeoutSecondsOptional. Defaults to 60. How long to wait for the committer to confirm before returning a finality-timeout error.

What happens on the wire​

A namespace-creation request travels the full Fabric-X flow:

  1. ChainLaunch builds a namespace-creation transaction signed by the submitter org's signing identity.
  2. It broadcasts the transaction to the submitter's orderer-group router.
  3. The transaction is batched, ordered via Arma consensus, and assembled into a block.
  4. Every committer's sidecar pulls the block and feeds it through the commit pipeline.
  5. The coordinator creates the ns_<name> table in postgres as part of commit.
  6. The explorer reports the namespace as committed.

Behind the scenes, this is the same path a token-sdk-x transaction takes — namespace creation just happens to be a transaction that ChainLaunch constructs on your behalf.

Verifying the postgres backing​

Each committer has its own postgres container. Connect to any of them and list namespace tables:

docker exec -it <network-name>-committer-p1-postgres \
  psql -U fabricx -d <network_name>_p1 -c '\dt ns_*'

You should see ns_<name> for every committed namespace plus ns__meta — the metadata table that tracks namespace registration state.

Listing namespaces​

curl -s -u admin:admin123 \
  "http://localhost:8100/api/v1/networks/fabricx/$NETWORK_ID/namespaces" \
  | jq '.items[] | {id, name, status, txId}'

Returns all namespaces created in the network with their commit status.

Using namespaces from token-sdk-x​

Inside a token-sdk-x application, the namespace is a qualifier on every state operation. Your application code references a namespace by name; the SDK constructs transactions that address that namespace's table on commit. Consult the token-sdk-x documentation for the exact API shape — ChainLaunch's responsibility ends at making sure the namespace exists on-chain and is materialized in postgres.

Deleting a namespace​

Namespace deletion is not supported from ChainLaunch today. Namespaces live for the lifetime of the network. If you need to remove one, you'll need to tear down and rebuild the network — see the teardown steps in Create a network manually.

Naming rules​

Hard requirements (enforced by fabric-x-committer):

  • Match ^[a-z0-9_]+$ — lowercase letters, digits, and underscores only.
  • Max 60 characters.
  • Non-empty.

Names that violate the regex are rejected on commit with MALFORMED_NAMESPACE_ID_INVALID. The web UI checks the same rule client-side to fail fast.

Recommended in addition:

  • Avoid leading digits (postgres identifier rules — surfaces only when the name maps directly into a SQL identifier).
  • Keep names stable — they're baked into on-chain state.

Names to avoid:

  • _meta — used internally (ns__meta is reserved).
  • Anything starting with pg_ — reserved by postgres.

Troubleshooting​

SymptomLikely causeFix
MALFORMED_NAMESPACE_ID_INVALIDName contains a hyphen, uppercase letter, or is longer than 60 charsRename to match ^[a-z0-9_]+$, ≤ 60 chars.
finality wait failed: committer timed outCommitter can't reach its postgres database — common on macOS/Windows when the network was created without local-dev modeRecreate the network with Local development mode checked, or restart the committer node so its config rewrite picks up host.docker.internal.
dial ... context deadline exceededSubmitter's router unreachable from serverCheck the router container is running; on macOS/Windows ensure the network was created with localDev: true (or that CHAINLAUNCH_FABRICX_LOCAL_DEV=true is set on the server).
ABORTED_SIGNATURE_INVALIDStale ledger from a previous network with the same nameTeardown per Create a network manually.
status: "pending" never transitionsCommitter not keeping up, or waitForFinality: false was usedRetry with waitForFinality: true, or check committer logs via the node detail page.
namespace already existsDuplicate creation attemptUse the list endpoint to confirm; no-op in practice.

See also​