Getting Started

This guide provides a quick, step-by-step walkthrough to get you up and running with ocap-libs. In just a few minutes, you'll install the necessary packages, create your first Decentralized Identity (DID), generate a compatible crypto wallet, and learn how to use some helpful utilities.

Step 1: Install the Packages#

First, you need to install the core packages. You'll need libraries for DID creation, wallet management, cryptography, and general utilities.

Open your terminal and run the following command:

Installation Command

pnpm install @arcblock/did @ocap/wallet @ocap/mcrypto @ocap/util

This command installs four essential packages:

  • @arcblock/did: The main library for creating and managing Decentralized Identities.
  • @ocap/wallet: A utility for creating and using crypto wallets for signing and verification.
  • @ocap/mcrypto: Handles the underlying cryptographic functions, such as key generation.
  • @ocap/util: Provides shared helper functions for data encoding, conversion, and more.

Step 2: Create a Wallet and DID#

Now that the packages are installed, let's create a wallet and its corresponding DID. The wallet holds the cryptographic keys, and the DID is the public identifier derived from those keys.

Create a new JavaScript file (e.g., create-did.js) and add the following code:

Create Wallet and DID

const { fromSecretKey: walletFromSecretKey } = require('@ocap/wallet');
const { fromSecretKey: didFromSecretKey } = require('@arcblock/did');
const Mcrypto = require('@ocap/mcrypto');
const assert = require('assert');

// Destructure required types from Mcrypto
const { types } = Mcrypto;

// 1. Generate a new cryptographic key pair using Ed25519
const keyPair = Mcrypto.Signer.Ed25519.genKeyPair();
console.log('Generated Secret Key (Buffer):', keyPair.secretKey);

// 2. Define the properties for our DID and Wallet
// This ensures they are generated with the same cryptographic settings.
const spec = {
  role: types.RoleType.ROLE_ACCOUNT, // Role type for a standard user account
  pk: types.KeyType.ED25519,          // Public key algorithm
  hash: types.HashType.SHA3,         // Hashing algorithm
};

// 3. Create a wallet instance from the secret key
const wallet = walletFromSecretKey(keyPair.secretKey, spec);
console.log('\nWallet Address:', wallet.address);

// 4. Create a DID from the same secret key and spec

See all 7 lines

Run the script from your terminal:

node create-did.js

You will see the newly generated secret key, wallet address, and DID printed to the console. Notice that the wallet's address is the core component of the full DID string.

Step 3: Sign and Verify a Message#

A primary function of a wallet is to prove ownership of a DID by signing messages. This is crucial for authentication and authorizing actions.

Let's add signing and verification to our script:

Sign and Verify

// ... (keep the code from Step 2) ...

// 6. Sign a message to prove ownership of the wallet/DID
const message = 'Hello, decentralized world!';
const signature = wallet.sign(message);

console.log('\nOriginal Message:', message);
console.log('Generated Signature:', signature);

// 7. Verify the signature against the original message
const isVerified = wallet.verify(message, signature);
assert.ok(isVerified, 'Signature should be verified successfully.');

console.log(`\nIs the signature valid? ${isVerified}`);
console.log('✅ Success! The signature has been verified.');

When you run the updated script, it will first create the wallet and DID, then sign a message and successfully verify that the signature is valid.

Step 4: Use a Utility Function#

The @ocap/util package provides many helpful functions. For example, the secret key generated in Step 2 is a Buffer. You can use utilities to convert it into a more readable format like Hex or Base58.

Using Utilities

// ... (keep the code from Step 3) ...
const { toHex } = require('@ocap/util');

// 8. Convert the secret key buffer to a hex string for display or storage
const secretKeyHex = toHex(keyPair.secretKey);
console.log('\nSecret Key (Hex Format):', secretKeyHex);
console.log('✅ Success! Used a utility to format the secret key.');

This simple example shows how utilities can simplify common data manipulation tasks.

Next Steps#

Congratulations! You have successfully created a decentralized identity, generated a wallet, used it to sign and verify a message, and leveraged a utility function. You now have the basic building blocks for integrating DIDs into your applications.

To learn more, dive into the core concepts and detailed API references for each package:

Overview
@arcblock/did