Quick Start
kc
Keychain (kc) is the reference implementation of the Multi-Dimensional Identity Protocol. Visit keychain.org for additional documentation and details.
Quick start
Recommended system requirements:
- GNU/Linux OS with Docker for containerized operation
- Node.js 22.15.0 and npm 10.8.2 or newer for manual and local operation
- Enough memory and storage for the selected services and registries
$ git clone https://github.com/KeychainMDIP/kc
$ cd kc
$ cp sample.env .env
$ # Edit .env and set KC_ENCRYPTED_PASSPHRASE to a strong value.
$ ./start-node gatekeeper keymaster hypr-mediator cli
start-node is a repository-root Docker Compose wrapper. The command above starts a core node that exchanges operations over Hyperswarm and includes the CLI container, without starting the Bitcoin-family nodes. Running ./start-node without service names starts every Compose service, including all blockchain nodes and mediators. See the deployment guide for isolated and optional-service configurations.
REST API references: Gatekeeper OpenAPI and Keymaster OpenAPI.
Local Development (for developers)
This repository is an npm workspace. For development, run the initial dependency installation and build from the repository root. The root build compiles the internal packages in dependency order. Package-specific build scripts can be run after this initial build.
npm ci
npm run build
Overview
Gatekeeper validates DID operations and maintains the local DID event database. Keymaster holds the server wallet and signs operations sent to Gatekeeper. Hyperswarm and Satoshi mediators distribute those operations over P2P and blockchain registries. Search Server builds a read model from Gatekeeper for Explorer and wallet search.
The browser wallet hosts the Keymaster library and stores its wallet locally. The server wallet and kc CLI use Keymaster's HTTP client. The admin CLI and mediators use Gatekeeper's HTTP client. See the deployment guide for the current service list and startup options.
Node configuration
Customize your node in the kc/.env file. Environment variables are documented for each service in the READMEs linked in the Overview above.
When running the services outside ./start-node, the supported configuration methods are:
- inject environment variables directly with Docker Compose or Kubernetes
- mount a shared
.envfile at/app/.envinside the container - mount a
.envfile anywhere and setKC_ENV_FILEto that path
This matches local startup and avoids custom entrypoint wrappers just to source env files.
KC_UID=1000 # Docker host UID
KC_GID=1002 # Docker host GID
KC_NODE_NAME=anon # Hyperswarm node name
KC_NODE_ID=anon # Node Keymaster DID name
KC_GATEKEEPER_REGISTRIES=hyperswarm # Supported DID Registries
KC_IPFS_ENABLE=true # Enable Gatekeeper IPFS storage and CAS endpoints
...
{adjust registry details for advanced users only}
Once your node is operational, use the CLI wallet and other command-line tools to manage it. Keymaster automatically creates or resolves the identity named by KC_NODE_ID during startup:
$ ./kc -h # Displays kc CLI help
$ ./kc list-ids # Confirms the configured node identity
Bitcoin-family nodes and their wallet setup are optional. Start the corresponding node and mediator as described in the deployment guide before using chain-specific scripts.
Command line interface wallet
Use the CLI ./kc or the web app at http://localhost:4226 to access the server-side wallet.
Use the web app at http://localhost:4224 to access a client-side (browser) wallet.
$ ./kc
Usage: keychain-cli [options] [command]
Keychain CLI tool
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
accept-credential [options] <did> Save verifiable credential for current ID
add-group-member <group> <member> Add a member to a group
add-group-vault-item <id> <file> Add an item (file) to a group vault
add-group-vault-member <id> <member> Add a member to a group vault
add-name <name> <did> Add a name for a DID
backup-id Backup the current ID to its registry
backup-wallet-did Backup wallet to encrypted DID and seed bank
backup-wallet-file <file> Backup wallet to file
bind-credential <schema> <subject> Create bound credential for a user
check-wallet Validate DIDs in wallet
clone-asset [options] <id> Clone an asset
create-asset [options] Create an empty asset
create-asset-document [options] <file> Create an asset from a document file
create-asset-image [options] <file> Create an asset from an image file
create-asset-json [options] <file> Create an asset from a JSON file
create-challenge [options] [file] Create a challenge (optionally from a file)
create-challenge-cc [options] <did> Create a challenge from a credential DID
create-group [options] <groupName> Create a new group
create-group-vault [options] Create a group vault
create-id [options] <name> Create a new decentralized ID
create-poll [options] <file> Create a poll
create-poll-template Create a poll template
create-response <challenge> Create a response to a challenge
create-schema [options] <file> Create a schema from a file
create-schema-template <schema> Create a template from a schema
create-wallet Create a new wallet (or show existing wallet)
decrypt-did <did> Decrypt an encrypted message DID
decrypt-json <did> Decrypt an encrypted JSON DID
encrypt-file <file> <did> Encrypt a file for a DID
encrypt-message <message> <did> Encrypt a message for a DID
fix-wallet Remove invalid DIDs from the wallet
get-asset <id> Get asset by name or DID
get-credential <did> Get credential by DID
get-group <did> Get group by DID
get-group-vault-item <id> <item> <file> Save an item from a group vault to a file
get-name <name> Get DID assigned to name
get-schema <did> Get schema by DID
help [command] display help for command
import-wallet <recovery-phrase> Create new wallet from a recovery phrase
issue-credential [options] <file> Sign and encrypt a bound credential file
list-assets List assets owned by current ID
list-credentials List credentials by current ID
list-group-vault-items <id> List items in the group vault
list-group-vault-members <id> List members of a group vault
list-groups List groups owned by current ID
list-ids List IDs and show current ID
list-issued List issued credentials
list-names List DID names (aliases)
list-schemas List schemas owned by current ID
new-wallet Create a new wallet
perf-test [N] Performance test to create N credentials
publish-credential <did> Publish the existence of a credential to the current user manifest
publish-poll <poll> Publish results to poll, hiding ballots
recover-id <did> Recovers the ID from the DID
recover-wallet-did [did] Recover wallet from seed bank or encrypted DID
remove-group-member <group> <member> Remove a member from a group
remove-group-vault-item <id> <item> Remove an item from a group vault
remove-group-vault-member <id> <member> Remove a member from a group vault
remove-id <name> Deletes named ID
remove-name <name> Removes a name for a DID
rename-id <oldName> <newName> Renames the ID
resolve-did <did> [confirm] Return document associated with DID
resolve-did-version <did> <version> Return specified version of document associated with DID
resolve-id Resolves the current ID
restore-wallet-file <file> Restore wallet from backup file
reveal-credential <did> Reveal a credential to the current user manifest
reveal-poll <poll> Publish results to poll, revealing ballots
revoke-credential <did> Revokes a verifiable credential
revoke-did <did> Permanently revoke a DID
rotate-keys Generates new set of keys for current ID
set-property <id> <key> [value] Assign a key-value pair to an asset
show-mnemonic Show recovery phrase for wallet
show-wallet Show wallet
sign-file <file> Sign a JSON file
test-group <group> [member] Determine if a member is in a group
transfer-asset <id> <controller> Transfer asset to a new controller
unpublish-credential <did> Remove a credential from the current user manifest
unpublish-poll <poll> Remove results from poll
update-asset-document <id> <file> Update an asset from a document file
update-asset-image <id> <file> Update an asset from an image file
update-asset-json <id> <file> Update an asset from a JSON file
update-poll <ballot> Add a ballot to the poll
use-id <name> Set the current ID
verify-file <file> Verify the signature in a JSON file
verify-response <response> Decrypt and validate a response to a challenge
view-poll <poll> View poll details
vote-poll <poll> <vote> [spoil] Vote in a poll
admin-cli
Use the admin CLI to manage and view status of your server's DID registry operations.
$ ./admin
Usage: admin-cli [options] [command]
Admin CLI tool
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
cas-add-file <file> Add a file to the CAS
cas-add-json <file> Add JSON file to the CAS
cas-add-text <text> Add text to the CAS
cas-get-file <cid> <file> Get a file from the CAS
cas-get-json <cid> Get JSON from the CAS
cas-get-text <cid> Get text from the CAS
export-batch Export all events in a batch
export-did <did> Export DID to file
export-dids Export all DIDs
get-block <registry> [blockHeightOrHash] Get block info for registry
get-dids [updatedAfter] [updatedBefore] [confirm] [resolve] Fetch all DIDs
get-status Report gatekeeper status
hash-dids <file> Compute hash of batch
help [command] display help for command
import-batch-file <file> [registry] Import batch of events
import-did <file> Import DID from file
import-dids <file> Import DIDs from file
list-registries List supported registries
perf-test [full] DID resolution performance test
process-events Process events queue
reset-db Reset the database to empty
resolve-did <did> [confirm] Return document associated with DID
show-queue <registry> Show queue for a registry
verify-db Verify all the DIDs in the db
verify-did <did> Return verified document associated with DID
Upgrade
To upgrade to the latest version:
$ ./stop-node
$ git pull --ff-only
$ ./start-node gatekeeper keymaster hypr-mediator cli
Use the same explicit service list as your existing deployment. Running ./start-node without service names starts the full Compose stack.