メインコンテンツへスキップ

APIリファレンス

このセクションでは、Walletオブジェクトとそのファクトリ関数の詳細なドキュメントを提供します。各関数の説明、パラメータ、戻り値、およびウォレットの作成、メッセージの署名、署名の検証などの一般的な操作のための実用的なコード例を見つけることができます。

このセクションでは、Walletオブジェクトとそのファクトリ関数の詳細なドキュメントを提供します。各関数の説明、パラメータ、戻り値、およびウォレットの作成、メッセージの署名、署名の検証などの一般的な操作のための実用的なコード例を見つけることができます。

ファクトリ関数

これらの関数は、Walletインスタンスを作成する主要な方法です。各関数は、新しいウォレットをゼロから作成する場合でも、既存のキーから作成する場合でも、DIDアドレスから作成する場合でも、特定の目的を果たします。

fromSecretKey()

秘密鍵から完全なウォレットインスタンスを作成します。この方法で作成されたウォレットは、署名と検証の両方に使用できます。

パラメータ

  • sk string | Buffer | Uint8Array (required) — 秘密鍵。通常は16進数形式です。
  • _type DIDTypeArg (default: 'default') — DIDタイプの構成。'default'や'eth'のような事前定義された文字列、またはカスタムタイプオブジェクトが可能です。詳細については、@arcblock/didドキュメントを参照してください。

戻り値

  • wallet WalletObject — 署名と検証が可能な新しいウォレットオブジェクト。

例

Signing and Verifying a Message

javascript
const assert = require('assert');
const { fromSecretKey } = require('@ocap/wallet');

// 16進数形式の秘密鍵
const sk = '0xD67C071B6F51D2B61180B9B1AA9BE0DD0704619F0E30453AB4A592B036EDE644E4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';

// デフォルトのDIDタイプを使用してウォレットを作成
const wallet = fromSecretKey(sk);

const message = 'data to sign';
const signature = wallet.sign(message);

console.log('生成された署名:', signature);

const isValid = wallet.verify(message, signature);
assert.ok(isValid, "署名は正常に検証されるべきです。");
console.log('検証成功！');

fromPublicKey()

公開鍵からウォレットインスタンスを作成します。このタイプのウォレットは秘密鍵がないため、メッセージの署名には使用できず、署名の検証にのみ使用できます。

パラメータ

  • pk string | Buffer | Uint8Array (required) — 公開鍵。通常は16進数形式です。
  • _type DIDTypeArg (default: 'default') — DIDタイプの構成。キーに関連付けられたハッシュおよび署名アルゴリズムを決定します。

戻り値

  • wallet WalletObject — 署名の検証が可能な新しいウォレットオブジェクト。

例

Verifying a known signature

javascript
const assert = require('assert');
const { fromPublicKey } = require('@ocap/wallet');

const pk = '0xE4852B7091317E3622068E62A5127D1FB0D4AE2FC50213295E10652D2F0ABFC7';
const message = 'data to sign';
const knownSignature = '0x8122c608f61b04f6b574f005dc8e0463d393a7fb50e0426bca587b20778a8a9f6376bab87bc3983b0a5f1c9581f6d94162317c715a3c1c0f086be1e514399109';

const wallet = fromPublicKey(pk);

// このウォレットは署名を検証できます
const isValid = wallet.verify(message, knownSignature);
assert.ok(isValid, "署名は検証されるべきです。");

// 秘密鍵がないため、これはエラーをスローします
try {
  wallet.sign(message);
} catch (e) {
  console.error(e.message); // secretKeyなしではデータに署名できません
}

fromAddress()

DIDアドレスから最小限のウォレットインスタンスを作成します。公開鍵と秘密鍵が不明なため、このウォレットは署名や検証には使用できません。主な用途は、アドレスにエンコードされたDIDタイプ情報を検査することです。

パラメータ

  • address string (required) — 有効なDIDアドレス（例：'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr'）。

戻り値

  • wallet WalletObject — アドレスと派生したタイプ情報を含む新しいウォレットオブジェクト。

例

Inspecting a DID Address

javascript
const { fromAddress } = require('@ocap/wallet');
const { types } = require('@ocap/mcrypto');

const appId = 'zNKtCNqYWLYWYW3gWRA1vnRykfCBZYHZvzKr';
const wallet = fromAddress(appId);

console.log('ウォレットアドレス:', wallet.address);
console.log('ロールタイプ:', wallet.type.role); // 2 (ROLE_APPLICATION)
console.log('PKタイプ:', wallet.type.pk);     // 1 (ED25519)
console.log('ハッシュタイプ:', wallet.type.hash);   // 2 (SHA3)

fromRandom()

ランダムに作成されたキーペアで新しいウォレットを生成します。これは、新しいアイデンティティを作成する標準的な方法です。

パラメータ

  • _type DIDTypeArg (default: 'default') — 新しいウォレットのDIDタイプ。'eth'を使用してEthereum互換のウォレットを生成します。

戻り値

  • wallet WalletObject — ランダムに生成されたキーペアを持つ新しいウォレットオブジェクト。

例

Creating a new standard and an Ethereum wallet

javascript
const { fromRandom } = require('@ocap/wallet');

// 標準ウォレットを作成（base58アドレス）
const standardWallet = fromRandom();
console.log('標準DIDアドレス:', standardWallet.address);
console.log('秘密鍵:', standardWallet.secretKey);

// Ethereum互換ウォレットを作成（base16アドレス）
const ethWallet = fromRandom('eth');
console.log('Ethereumアドレス:', ethWallet.address);
console.log('秘密鍵:', ethWallet.secretKey);

fromJSON()

シリアル化されたJSONオブジェクトからウォレットインスタンスを再構築します。通常はwallet.toJSON()メソッドによって作成されたものです。

パラメータ

  • json SerializedWallet (required) — シリアル化されたウォレットオブジェクト。
    • type string (required) — DIDタイプの文字列。
    • pk string (required) — 16進数形式の公開鍵。
    • sk string (required) — 16進数形式の秘密鍵。
    • address string (required) — DIDアドレス。

戻り値

  • wallet WalletObject — JSONデータから復元されたウォレットオブジェクト。

例

Serializing and Deserializing a Wallet

javascript
const assert = require('assert');
const { fromRandom, fromJSON } = require('@ocap/wallet');

const originalWallet = fromRandom();

// ウォレットをJSONオブジェクトにシリアル化する
const walletJSON = originalWallet.toJSON();
console.log('シリアル化されたウォレット:', walletJSON);

// JSONオブジェクトからウォレットを復元する
const restoredWallet = fromJSON(walletJSON);

assert.equal(originalWallet.address, restoredWallet.address, 'アドレスは一致するべきです');
assert.equal(originalWallet.secretKey, restoredWallet.secretKey, '秘密鍵は一致するべきです');

console.log('ウォレットは正常に復元されました！');

isValid()

指定されたオブジェクトが有効なWalletObjectであるかどうかをチェックします。これは、タイプガードやウォレットが必要なプロパティとメソッドを持っていることを確認するのに役立ちます。

パラメータ

  • wallet any (required) — チェックするオブジェクト。
  • canSign boolean (default: true) — trueの場合、関数は秘密鍵とsignメソッドの存在もチェックします。

戻り値

  • isValid boolean — オブジェクトが有効なウォレットの場合はtrueを返し、そうでない場合はfalseを返します。

例

Validating Wallet Objects

javascript
const { fromRandom, fromPublicKey, isValid } = require('@ocap/wallet');

const signingWallet = fromRandom();
const verifyingWallet = fromPublicKey(signingWallet.publicKey);

// 完全なウォレットは署名に有効です
console.log('署名ウォレットは署名に有効ですか？', isValid(signingWallet)); // true

// 公開鍵からのウォレットは署名に有効ではありません
console.log('検証ウォレットは署名に有効ですか？', isValid(verifyingWallet)); // false

// しかし、署名機能が不要な場合は有効です
console.log('検証ウォレットは検証に有効ですか？', isValid(verifyingWallet, false)); // true

// 空のオブジェクトは有効なウォレットではありません
console.log('空のオブジェクトは有効なウォレットですか？', isValid({})); // false

Walletオブジェクト

WalletObjectはファクトリ関数によって返されるコアエンティティです。暗号キー、DIDアドレス、および暗号操作を実行するためのメソッドを保持します。

プロパティ

  • address string — 公開鍵とタイプ情報から派生したDIDアドレス。
  • publicKey BytesType — 公開鍵。フォーマット（例：16進文字列、Buffer）はウォレットの作成方法に依存します。
  • secretKey BytesType — 秘密鍵。公開鍵またはアドレスから作成されたウォレットの場合、これはundefinedです。
  • type DIDType — DIDタイプ情報（ロール、pk、ハッシュ、アドレスエンコーディング）を含むオブジェクト。

メソッド

.sign()

ウォレットの秘密鍵を使用してデータの一部に署名します。

パラメータ

  • data BytesType (required) — 署名されるデータ。
  • hashBeforeSign boolean (default: true) — trueの場合、データは署名前にウォレットのハッシュアルゴリズムを使用してハッシュ化されます。
  • encoding string (default: 'hex') — 署名の出力エンコーディング（'hex'、'base64'、'base58'、'buffer'など）。

戻り値

  • signature BytesType — 指定されたエンコーディングで生成された署名。

.verify()

ウォレットの公開鍵を使用して、データに対する署名を検証します。

パラメータ

  • data BytesType (required) — 署名された元のデータ。
  • signature BytesType (required) — 検証する署名。
  • hashBeforeVerify boolean (default: true) — trueの場合、署名プロセスと一致させるために、検証前にデータがハッシュ化されます。

戻り値

  • isValid Promise<boolean> — 署名が有効な場合はtrueに解決され、そうでない場合はfalseに解決されるPromise。

.hash()

ウォレットに設定されたハッシュアルゴリズムを使用してデータをハッシュ化します。

パラメータ

  • data BytesType (required) — ハッシュ化されるデータ。
  • round number (default: 1) — ハッシュ化のラウンド数。
  • encoding string (default: 'hex') — ハッシュの出力エンコーディング。

戻り値

  • hash BytesType — 指定されたエンコーディングでの結果のハッシュ。

.ethSign()

Ethereum固有の署名アルゴリズム（eth_signの動作）を使用してメッセージに署名します。'eth'タイプのウォレットでのみ利用可能です。

パラメータ

  • data string (required) — 署名されるデータ。
  • hashBeforeSign boolean (default: true) — trueの場合、データは最初にEthereum固有のethHashメソッドを使用してハッシュ化されます。

戻り値

  • signature string — 生成されたEthereum署名。

.ethVerify()

Ethereum署名から署名者のアドレスを回復し、ウォレットのアドレスと比較します。'eth'タイプのウォレットでのみ利用可能です。

パラメータ

  • data string (required) — 署名された元のデータ。
  • signature string (required) — Ethereum署名。
  • hashBeforeVerify boolean (default: true) — trueの場合、検証前にethHashを使用してデータがハッシュ化されます。

戻り値

  • isValid boolean — 回復されたアドレスがウォレットのアドレスと一致する場合はtrueを返し、そうでない場合はfalseを返します。

.toJSON()

ウォレットの状態をプレーンなJSONオブジェクトにシリアル化します。これは、ウォレットデータの保存や送信に役立ちます。

戻り値

  • serialized SerializedWallet — ウォレットのタイプ、キー、アドレスを含むJSONオブジェクト。