vetkd skill: frontend TypeScript examples are wrong for @dfinity/vetkeys 0.4.0; test_key_1 cycle cost incorrect

[marc0olo]

Summary

We built a production-grade vetKeys app from scratch using the ICP skill files as the primary reference — a decentralized family password manager called KeyChain (marc0olo/icp-skill-password-manager). During development, we hit several build-breaking and runtime errors that were directly caused by incorrect information in the vetkd skill. A secondary gap exists in the icp-cli binding-generation reference.

The errors below were verified by fetching the live skill files, not from memory.

---

1. vetkd skill — Frontend TypeScript API is wrong for @dfinity/vetkeys 0.4.0

The skill pins @dfinity/vetkeys at v0.4.0 in the prerequisites but then documents an API that does not exist in that version. All three errors below occur together when following the skill's TypeScript example.

1a. TransportSecretKey.fromSeed() does not exist

What the skill says:

const seed = crypto.getRandomValues(new Uint8Array(32));
const transportSecretKey = TransportSecretKey.fromSeed(seed);
const transportPublicKey = transportSecretKey.publicKey();

What @dfinity/vetkeys 0.4.0 actually provides:

const transportSecretKey = TransportSecretKey.random();
const transportPublicKey = transportSecretKey.publicKeyBytes();

Both fromSeed() and publicKey() are absent from the 0.4.0 package. Calling them throws a runtime TypeError: TransportSecretKey.fromSeed is not a function.

1b. vetKey.toDerivedKeyMaterial() does not exist

What the skill says:

const aesKeyMaterial = vetKey.toDerivedKeyMaterial();
const aesKey = await crypto.subtle.importKey(
  "raw",
  aesKeyMaterial.data.slice(0, 32), // 256-bit AES key
  { name: "AES-GCM" },
  false,
  ["encrypt", "decrypt"],
);

What 0.4.0 actually provides:

// asDerivedKeyMaterial is async and returns DerivedKeyMaterial directly
const keyMaterial = await vetKey.asDerivedKeyMaterial();

// DerivedKeyMaterial has built-in encrypt/decrypt — no manual importKey needed
const ciphertext = keyMaterial.encryptMessage(plaintext, domainSeparator);
const plaintext  = await keyMaterial.decryptMessage(ciphertext, domainSeparator);

The method was renamed from toDerivedKeyMaterial to asDerivedKeyMaterial, is now async, and the returned DerivedKeyMaterial exposes encryptMessage/decryptMessage directly. There is no .data property. Following the skill results in a runtime crash and a manual AES-GCM wiring that is both unnecessary and incorrect.

---

2. vetkd skill — test_key_1 cycle cost is wrong on mainnet

What the skill says (table and mistake 8):

test_key_1 | Local + Mainnet | Development & testing | 10_000_000_000

Actual runtime error when following the skill:

vetkd_derive_key request sent with 10_000_000_000 cycles,
but 26_153_846_153 cycles are required.

test_key_1 costs the same ~26B cycles as key_1 on mainnet because the cost is determined by the subnet holding the master key, not the key name. The skill itself explains this correctly in the fees paragraph ("Fees depend on the subnet where the master key resides") but then contradicts itself in the table and in mistake 8.

The skill also correctly says "send more cycles than the current cost so that future subnet size increases do not cause calls to fail; unused cycles are refunded" — but only as a note for canisters that may be blackholed. This guidance should be applied to the code example itself, regardless of key name.

Suggested fix for the Rust example:

// Send 30B cycles — actual cost for both test_key_1 and key_1 is ~26.15B.
// Fees depend on subnet size, not key name. Unused cycles are refunded.
let (response,): (VetKdDeriveKeyResponse,) = ic_cdk::api::call::call_with_payment128(
    Principal::management_canister(),
    "vetkd_derive_key",
    (request,),
    30_000_000_000u128,
)

---

3. icp-cli binding-generation reference — Result type representation undocumented

The binding-generation reference documents opt T → T | null but does not cover how Result<T, E> Candid types are represented in the generated bindings.

@icp-sdk/bindgen generates discriminated unions:

{ __kind__: "Ok";  Ok:  T }
{ __kind__: "Err"; Err: E }

This is not obvious. The natural patterns ("Ok" in result, result.Ok !== undefined) do not work and silently fail or produce type errors. Without documentation, developers will use these patterns and get no useful error — queries simply return nothing or access is denied.

Suggested addition:

// Result<T, E> is a discriminated union — check __kind__, not property existence
const result = await actor.some_method();
if (result.__kind__ === "Err") {
  console.error(result.Err);
} else {
  console.log(result.Ok);
}

Similarly, Candid variants (e.g. variant { Read; Write; Manage }) become string enums:

import { AccessLevel } from "./bindings/backend";
// Use:     entry.access === AccessLevel.Write
// Not:     "Write" in entry.access  (does not work)

---

4. internet-identity skill — UserInterrupt not documented

When a user closes the Internet Identity popup without authenticating, authClient.login() calls onError with a UserInterrupt error. This is expected behavior, not a real failure, but the skill does not mention it.

The skill's onError example:

onError: (error) => {
  console.error("Login failed:", error);
  reject(error);
}

As written, this logs/surfaces a UserInterrupt as an error on every popup dismissal.

Suggested addition:

onError: (error) => {
  // UserInterrupt means the user closed the popup — not an error
  if (String(error).includes("UserInterrupt")) return;
  console.error("Login failed:", error);
  reject(error);
},

---

Reference implementation

All errors above were encountered during the construction of marc0olo/icp-skill-password-manager — a working end-to-end vetKeys app with:

• Rust backend using ic-stable-structures 0.7, ic-cdk 0.19, raw vetkd_derive_key calls
• React/TypeScript frontend using @dfinity/vetkeys 0.4.0, @icp-sdk/auth 5.x, @icp-sdk/bindgen 0.3.x
• Client-side-only encryption: the canister never sees plaintext
• Shared vault access control (Read / Write / Manage)

The working crypto.ts (source) shows the correct 0.4.0 API in full context.

[marc0olo]

Correction to section 2: cycle error occurred on local PocketIC, not mainnet

To be precise: the 26_153_846_153 cycle requirement was hit during local development on a PocketIC instance, not on mainnet.

This makes the skill's documentation more wrong than initially stated. The skill's table lists test_key_1 as:

Key name	Environment	Cycles (approx.)
test_key_1	Local + Mainnet	10_000_000_000

The "Local + Mainnet" environment column implies test_key_1 works with 10B cycles locally as well. But the actual error on a local PocketIC replica was:

vetkd_derive_key request sent with 10_000_000_000 cycles,
but 26_153_846_153 cycles are required.

So the 10B figure is wrong for both environments the skill claims it covers. The local PocketIC vetKD simulation requires the same ~26B cycles as the mainnet key_1 key.

This is the more impactful failure: developers testing locally (the expected starting point) will immediately hit a cycle rejection that the skill gives them no reason to anticipate. Sending 10B cycles and seeing a cryptic rejection with no prior warning from the skill is a poor first-time experience.

[marc0olo]

Additional pitfalls not yet covered in this issue

Four more issues were encountered during development that are not yet documented in the relevant skill files. All are reproducible from the reference implementation.

---

5. stable-memory skill — StableBTreeMap iterator API undocumented (ic-stable-structures 0.7.2)

The stable-memory skill correctly shows Storable implementations and insert/get operations, but never shows iteration over a StableBTreeMap. In ic-stable-structures 0.7.2, iterators yield LazyEntry<K, V, M> — not (K, V) tuples as one might expect from Rust's standard iterator conventions.

The common (broken) pattern:

// BROKEN — does not compile in 0.7.2
map.borrow().iter().for_each(|(key, val)| {
    // ...
});

The correct pattern (using entry.key() / entry.value()):

// CORRECT
map.borrow().iter().filter_map(|entry| {
    let k = entry.key();
    let v = entry.value();
    // ...
})

Note that collecting keys also requires .clone() since entry.key() borrows from the lazy entry:

.map(|entry| entry.key().clone())
.collect()

This pattern is used throughout the reference implementation:

• src/backend/src/lib.rs L291–L295 — iterating ACCESS_MAP
• src/backend/src/lib.rs L374–L376 — collecting keys for deletion
• src/backend/src/lib.rs L441–L445 — prefix range scan

Suggested addition to stable-memory skill: add one iteration example showing the LazyEntry accessor pattern, including a range scan with take_while for prefix queries.

---

6. icp-cli binding-generation reference — Principal import path undocumented

Any app that handles vault sharing, access control, or user input of a principal ID needs to parse and use Principal on the frontend. The correct import is:

import { Principal } from "@icp-sdk/core/principal";

No skill file mentions this. The internet-identity and binding-generation references both use @icp-sdk/core/agent for HttpAgent/Actor, which leads developers to look there first. Importing Principal from @icp-sdk/core/agent fails at runtime.

Reference: frontend/src/components/ShareModal.tsx L2

Suggested addition to binding-generation reference: a one-liner noting that Principal is exported from @icp-sdk/core/principal, not @icp-sdk/core/agent.

---

7. icp-cli binding-generation reference — Candid blob maps to Uint8Array, not number[]

The binding-generation reference documents opt T → T | null but says nothing about how Candid blob fields are typed. The generated bindings use Uint8Array throughout — not number[] or Array<number>. Wrapping blobs in Array.from() produces a TypeScript type error against the generated signatures.

Incorrect:

// TYPE ERROR — backend expects Uint8Array, not number[]
actor.get_encrypted_vetkey(Array.from(vaultId), Array.from(transportPublicKey));

Correct:

// Uint8Array passed directly — no Array.from() needed
actor.get_encrypted_vetkey(vaultId, transportPublicKey);

Reference: frontend/src/crypto.ts L84–L86 (comment explains this explicitly)

Suggested addition to binding-generation reference: note that all Candid blob types become Uint8Array in the generated bindings. Pass Uint8Array directly — do not wrap in Array.from().

---

8. icp-cli binding-generation reference — bindings must be generated before tsc in the build script

The Vite plugin generates bindings at dev/build time, but tsc (used for type-checking in CI or standalone builds) runs before that and fails with:

error TS2307: Cannot find module './bindings/backend' or its corresponding type declarations.

The binding-generation reference says "The .did file must exist on disk before the frontend builds" but does not address this ordering issue for projects that run tsc independently.

The fix is to prepend the @icp-sdk/bindgen CLI call to the build script so bindings exist before tsc runs:

"build": "npx @icp-sdk/bindgen --did-file ../src/backend/backend.did --out-dir ./src/bindings --force && tsc && vite build"

Reference: frontend/package.json L7

Note: --did-file and --out-dir are the correct CLI flag names — --did and --out (which seem natural) do not work.

Suggested addition to binding-generation reference: explicitly document the build script ordering pattern and the correct CLI flag names (--did-file, --out-dir).

[marc0olo]

Clarification on stable-memory skill + into_bytes (ic-stable-structures 0.7)

The stable-memory skill itself is correct — its Storable implementation example includes into_bytes. This pitfall is therefore not a bug in the stable-memory skill.

However, it is worth documenting here because it was still a real compile-time error during development, and the root cause is a gap in the vetkd skill.

What happened

The vetkd skill lists ic-stable-structures = "0.7" as a dependency in its Rust Cargo.toml example, but:

1. It never cross-references the stable-memory skill for how to implement Storable
2. It does not mention that into_bytes is a breaking addition in 0.7 — it did not exist in ic-stable-structures 0.6

Anyone who has used ic-stable-structures 0.6 before, or who finds an older code example online, will write a Storable impl with only to_bytes, from_bytes, and BOUND — which compiled fine in 0.6 but fails in 0.7 with:

error[E0046]: not all trait items implemented, missing: `into_bytes`

Because the vetkd skill introduces the 0.7 dependency without flagging this breaking change, developers are set up to hit this error if they don't also read the stable-memory skill.

The correct Storable impl (ic-stable-structures 0.7)

impl Storable for BKey {
    fn to_bytes(&self) -> Cow<[u8]> { Cow::Borrowed(&self.0) }
    fn into_bytes(self) -> Vec<u8> { self.0 }  // required since 0.7 — missing causes compile error
    fn from_bytes(b: Cow<[u8]>) -> Self { BKey(b.to_vec()) }
    const BOUND: Bound = Bound::Bounded { max_size: MAX_KEY, is_fixed_size: false };
}

Reference: src/backend/src/lib.rs L48–L52

Suggested fix

In the vetkd skill's Cargo.toml section, add a note alongside ic-stable-structures = "0.7":

ic-stable-structures 0.7 introduced a breaking change to the Storable trait: into_bytes(self) -> Vec<u8> is now required. If you implement Storable for custom types, see the stable-memory skill for the correct implementation pattern.