https://github.com/archetech/archon
Reference implementation for the did:cid DID method
https://github.com/archetech/archon
agents btc credentials decentralized did encryption identity ipfs lightning reputation
Last synced: 3 months ago
JSON representation
Reference implementation for the did:cid DID method
- Host: GitHub
- URL: https://github.com/archetech/archon
- Owner: archetech
- License: mit
- Created: 2026-01-08T19:03:41.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-28T19:09:04.000Z (3 months ago)
- Last Synced: 2026-03-28T20:20:52.054Z (3 months ago)
- Topics: agents, btc, credentials, decentralized, did, encryption, identity, ipfs, lightning, reputation
- Language: TypeScript
- Homepage:
- Size: 28.2 MB
- Stars: 4
- Watchers: 0
- Forks: 3
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY_AUDIT.md
Awesome Lists containing this project
README
[](https://github.com/archetech/archon/actions/workflows/unit-test.yml) [](https://coveralls.io/github/archetech/archon?branch=main)
# Archon
Archon is a decentralized identity (DID) protocol implementation. Visit our website [archetech.github.io/archon](https://archetech.github.io/archon) for additional documentation and details.
## Quick start
Recommended system requirements:
- GNU/Linux OS with [docker](https://www.docker.com/) for containerized operation
- node 22.15.0 and npm 10.9.2 for manual and local operation
- minimum of 8Gb RAM if operating a full trustless node
```
$ git clone https://github.com/archetech/archon
$ cd archon
$ cp sample.env .env
$ ./start-node
```
### Keymaster Onboarding
For a local Keymaster wallet and identity without running a full node, use the hosted installer:
```bash
curl -fsSL https://archon.technology/install | bash
```
The installer:
- checks for Node.js and npm before prompting
- installs `@didcid/keymaster` if needed
- prompts for an ID name
- prompts for a Keymaster passphrase with no default
- prompts for a Node URL with default `https://archon.technology`
- uses `ARCHON_PASSPHRASE` and `ARCHON_NODE_URL` during setup
- runs `keymaster create-id`
After setup it prints optional `.bashrc` and `.zshrc` snippets so users can persist the Node URL and, if they choose, the passphrase for future shells.
### Local Development (for developers)
If you're developing or working on Archon follow these additional steps after cloning.
```bash
npm install
npm run build
```
## Overview
An Archon node includes several interoperating microservices. If you follow the dependency arrows on the diagram below, you will end up at the central core service, the [Gatekeeper service](https://github.com/archetech/archon/blob/main/services/gatekeeper/server/README.md) responsible for maintaining the integrity of the local DID database. The mediators are responsible for connecting the Gatekeeper to various networks such as [Hyperswarm](https://github.com/archetech/archon/blob/main/services/mediators/hyperswarm/README.md). The BTC:testnet4 (Bitcoin testnet) and BTC:signet (another Bitcoin testnet) mediators are both instances of the [Satoshi mediator](https://github.com/archetech/archon/blob/main/services/mediators/satoshi/README.md) since they are derived from Bitcoin core (they differ only in how they are configured). [Keymaster](https://github.com/archetech/archon/blob/main/packages/keymaster/README.md) is the Archon client responsible for holding the private keys and signing DID operations (create, update, delete) sent to Gatekeeper. The [Gatekeeper client app](https://github.com/archetech/archon/blob/main/apps/gatekeeper-client), [browser extension](https://github.com/archetech/archon/blob/main/apps/browser-extension/README.md), [React wallet](https://github.com/archetech/archon/blob/main/apps/react-wallet/README.md), and [Keymaster service](https://github.com/archetech/archon/blob/main/services/keymaster/server/README.md) all use the [Keymaster library](https://github.com/archetech/archon/blob/main/packages/keymaster/README.md). The [Keymaster client app](https://github.com/archetech/archon/blob/main/apps/keymaster-client) is configured to talk to the Keymaster service instead of hosting its own wallet. It uses the same [KeymasterClient](https://github.com/archetech/archon/blob/main/packages/keymaster/src/keymaster-client.ts) as the Archon CLI. There are two CLI (command line interface) components: [archon](scripts/archon-cli.js) for talking to the Keymaster service, and [admin](scripts/admin-cli.js) for talking to the Gatekeeper service. The admin script uses the same [GatekeeperClient](https://github.com/archetech/archon/blob/main/packages/gatekeeper/README.md) as the Keymaster service and the mediators.
## Node configuration
Customize your node in the archon/.env file. Environment variables are documented for each service in the READMEs linked in the Overview above.
```
ARCHON_UID=1000 # Docker host UID
ARCHON_GID=1002 # Docker host GID
ARCHON_NODE_NAME=anon # Hyperswarm node name
ARCHON_NODE_ID=anon # Node Keymaster DID name
ARCHON_GATEKEEPER_REGISTRIES=hyperswarm,BTC:testnet4,BTC:signet # Supported DID Registries
...
{adjust registry details for advanced users only}
```
Once your node is operational (start-node), you can setup local dependencies and manage your server using local CLI wallet and other command line tools:
```
$ npm ci # Installs all node package dependencies
$ ./archon -h # Displays archon CLI help
$ ./archon create-id anon BTC:testnet4 # Creates Node Keymaster DID name (set as ARCHON_NODE_ID in .env)
$ ./scripts/tbtc-cli createwallet archon # Creates Archon wallet for Bitcoin Testnet registry
$ ./scripts/tbtc-cli getnewaddress # Get a new address to fund Bitcoin Testnet wallet
$ ./scripts/tbtc-cli getwalletinfo # Get a general status of confirmed and incoming funds
```
## Command line interface wallet
Use the CLI `./archon` or the Keymaster client at `http://localhost:4226` to access the server-side wallet.
Use the Gatekeeper client at `http://localhost:4224` to access the local Gatekeeper API.
Use the React wallet at `http://localhost:4228` for the client-side browser wallet.
```
$ ./archon
Usage: archon-cli [options] [command]
Archon CLI tool
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
accept-credential [options] Save verifiable credential for current ID
add-group-member Add a member to a group
add-vault-item Add an item (file) to a vault
add-vault-member Add a member to a vault
add-alias Add an alias 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 Backup wallet to file
bind-credential Create bound credential for a user
check-wallet Validate DIDs in wallet
clone-asset [options] Clone an asset
create-asset [options] Create an empty asset
create-asset-file [options] Create an asset from a file
create-asset-image [options] Create an asset from an image file
create-asset-json [options] Create an asset from a JSON file
create-challenge [options] [file] Create a challenge (optionally from a file)
create-challenge-cc [options] Create a challenge from a credential DID
create-group [options] Create a new group
create-vault [options] Create a vault
create-id [options] Create a new decentralized ID
create-poll [options] Create a poll
create-poll-template Create a poll template
create-response Create a response to a challenge
create-schema [options] Create a schema from a file
create-schema-template Create a template from a schema
create-wallet Create a new wallet (or show existing wallet)
decrypt-did Decrypt an encrypted message DID
decrypt-json Decrypt an encrypted JSON DID
encrypt-file Encrypt a file for a DID
encrypt-message Encrypt a message for a DID
encrypt-wallet Encrypt wallet
fix-wallet Remove invalid DIDs from the wallet
get-asset Get asset by name or DID
get-credential Get credential by DID
get-group Get group by DID
get-vault-item Save an item from a vault to a file
get-alias Get DID assigned to alias
get-schema Get schema by DID
help [command] display help for command
import-wallet Create new wallet from a recovery phrase
issue-credential [options] Sign and encrypt a bound credential file
list-assets List assets owned by current ID
list-credentials List credentials by current ID
list-vault-items List items in the vault
list-vault-members List members of a vault
list-groups List groups owned by current ID
list-ids List IDs and show current ID
list-issued List issued credentials
list-aliases List DID aliases
list-schemas List schemas owned by current ID
perf-test [N] Performance test to create N credentials
publish-credential Publish the existence of a credential to the current user manifest
publish-poll Publish results to poll, hiding ballots
recover-id Recovers the ID from the DID
recover-wallet-did [did] Recover wallet from seed bank or encrypted DID
remove-group-member Remove a member from a group
remove-vault-item Remove an item from a vault
remove-vault-member Remove a member from a vault
remove-id Deletes named ID
remove-alias Removes an alias for a DID
rename-id Renames the ID
resolve-did [confirm] Return document associated with DID
resolve-did-version Return specified version of document associated with DID
resolve-id Resolves the current ID
restore-wallet-file Restore wallet from backup file
reveal-credential Reveal a credential to the current user manifest
reveal-poll Publish results to poll, revealing ballots
revoke-credential Revokes a verifiable credential
revoke-did Permanently revoke a DID
rotate-keys Generates new set of keys for current ID
set-property [value] Assign a key-value pair to an asset
show-mnemonic Show recovery phrase for wallet
show-wallet Show wallet
sign-file Sign a JSON file
test-group [member] Determine if a member is in a group
transfer-asset Transfer asset to a new controller
unpublish-credential Remove a credential from the current user manifest
unpublish-poll Remove results from poll
update-asset-file Update an asset from a file
update-asset-image Update an asset from an image file
update-asset-json Update an asset from a JSON file
update-poll Add a ballot to the poll
use-id Set the current ID
verify-file Verify the signature in a JSON file
verify-response Decrypt and validate a response to a challenge
view-poll View poll details
vote-poll [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:
ipfs-add-file Add a file to IPFS
ipfs-add-json Add JSON file to IPFS
ipfs-add-text Add text to IPFS
ipfs-get-file Get a file from IPFS
ipfs-get-json Get JSON from IPFS
ipfs-get-text Get text from IPFS
export-batch Export all events in a batch
export-did Export DID to file
export-dids Export all DIDs
get-block [blockHeightOrHash] Get block info for registry
get-dids [updatedAfter] [updatedBefore] [confirm] [resolve] Fetch all DIDs
get-status Report gatekeeper status
hash-dids Compute hash of batch
help [command] display help for command
import-batch-file [registry] Import batch of events
import-did Import DID from file
import-dids 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 [confirm] Return document associated with DID
show-queue Show queue for a registry
verify-db Verify all the DIDs in the db
verify-did Return verified document associated with DID
```
## Upgrade
To upgrade to the latest version:
```
$ ./stop-node
$ git pull
$ ./start-node
```