iris-crypto 0.1.0

Cryptographic primitives for Iris Nockchain Wallet
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

# iris-crypto WebAssembly Package

This package provides Nockchain cryptography primitives compiled to WebAssembly, allowing you to use `derive_master_key` and related functions from TypeScript/JavaScript.

## Building

To build the WASM package:

```bash
wasm-pack build --target web --out-dir pkg -- --features wasm
```

## Usage

### In a Web Browser

```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>iris-crypto Demo</title>
</head>
<body>
    <script type="module">
        import init, { deriveMasterKeyFromMnemonic } from './pkg/iris_crypto.js';

        async function main() {
            // Initialize the WASM module
            await init();

            // Derive master key from mnemonic
            const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
            const masterKey = deriveMasterKeyFromMnemonic(mnemonic, "");

            console.log("Private Key:", Array.from(masterKey.private_key));
            console.log("Public Key:", Array.from(masterKey.public_key));
            console.log("Chain Code:", Array.from(masterKey.chain_code));

            // Derive a child key
            const childKey = masterKey.deriveChild(0);
            console.log("Child Private Key:", Array.from(childKey.private_key));

            // Free the WASM memory
            masterKey.free();
            childKey.free();
        }

        main();
    </script>
</body>
</html>
```

### In Node.js

```javascript
import init, { deriveMasterKey, deriveMasterKeyFromMnemonic } from './pkg/iris_crypto.js';
import { readFileSync } from 'fs';

async function main() {
    // Initialize with the WASM file
    const wasmBuffer = readFileSync('./pkg/iris_crypto_bg.wasm');
    await init(wasmBuffer);

    // Derive from mnemonic
    const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
    const masterKey = deriveMasterKeyFromMnemonic(mnemonic, "");

    console.log("Master Key derived successfully");
    console.log("Private Key length:", masterKey.private_key.length);
    console.log("Public Key length:", masterKey.public_key.length);
    console.log("Chain Code length:", masterKey.chain_code.length);

    // Derive children
    const child0 = masterKey.deriveChild(0);
    const child1 = masterKey.deriveChild(1);

    // Hardened derivation (index >= 2^31)
    const hardenedChild = masterKey.deriveChild(0x80000000);

    // Clean up
    masterKey.free();
    child0.free();
    child1.free();
    hardenedChild.free();
}

main();
```

### TypeScript

The package includes full TypeScript definitions:

```typescript
import init, {
    deriveMasterKey,
    deriveMasterKeyFromMnemonic,
    WasmExtendedKey
} from './pkg/iris_crypto.js';

await init();

// Derive from mnemonic with TypeScript types
const mnemonic: string = "your mnemonic here";
const passphrase: string = "";

const masterKey: WasmExtendedKey = deriveMasterKeyFromMnemonic(mnemonic, passphrase);

// Type-safe access
const privateKey: Uint8Array | undefined = masterKey.private_key;
const publicKey: Uint8Array = masterKey.public_key;
const chainCode: Uint8Array = masterKey.chain_code;

// Derive child
const childKey: WasmExtendedKey = masterKey.deriveChild(0);
```

## API

### Functions

#### `deriveMasterKey(seed: Uint8Array): WasmExtendedKey`

Derives a master key from raw seed bytes using SLIP-10.

- **Parameters:**
  - `seed`: Raw seed bytes (typically 64 bytes from BIP39)
- **Returns:** `WasmExtendedKey` containing the master private key, public key, and chain code

#### `deriveMasterKeyFromMnemonic(mnemonic: string, passphrase?: string): WasmExtendedKey`

Derives a master key from a BIP39 mnemonic phrase.

- **Parameters:**
  - `mnemonic`: BIP39 mnemonic phrase (12-24 words)
  - `passphrase`: Optional BIP39 passphrase (defaults to empty string)
- **Returns:** `WasmExtendedKey` containing the master private key, public key, and chain code

### Classes

#### `WasmExtendedKey`

Represents an extended key with derivation capability.

**Properties:**
- `private_key: Uint8Array | undefined` - Private key (32 bytes), undefined for public-only keys
- `public_key: Uint8Array` - Public key (97 bytes: 1 byte prefix + 12 belts × 8 bytes)
- `chain_code: Uint8Array` - Chain code for derivation (32 bytes)

**Methods:**
- `deriveChild(index: number): WasmExtendedKey` - Derives a child key at the given index
  - For hardened derivation, use indices >= 2^31 (0x80000000)
  - For non-hardened derivation, use indices < 2^31
- `free(): void` - Frees the WebAssembly memory (important to prevent memory leaks)

## Implementation Details

This package uses:
- SLIP-10 for hierarchical deterministic key derivation
- Cheetah curve arithmetic from Nockchain
- Custom field arithmetic optimized for the Cheetah curve
- TIP5 hash function for internal operations

The implementation is compatible with Nockchain's wallet derivation scheme.

## License

See the main repository LICENSE file.