Specification Clarifications for Reference Implementation

[lessuselesss]

BIP-Keychain Specification Clarifications for Reference Implementation

Hi @akarve,

I'm creating the first reference implementation of your BIP-Keychain specification in TypeScript/Deno and have encountered several ambiguities that need clarification to ensure correctness.

Implementation Context

• Repository: https://github.com/lessuselesss/bip-keychain-ref
• Language: TypeScript with Deno runtime
• Target Use Case: Git-based repository key derivation for DAOgora bounty payment system
• Status: Pre-implementation analysis complete, ready to begin coding

Specification Clarifications Needed

1. Hardened Derivation Rules

The specification states: "application may set the leading bit depending on whether or not hardened derivation is desired"

Questions:

• When should hardened vs non-hardened derivation be used for semantic segments?
• Should there be a default policy (e.g., all hardened except final index)?
• Are there security implications for specific patterns?

2. Optional Nonce Implementation

The spec mentions: hmac(...) || optional_nonce

Questions:

• What is the exact format and length of the optional nonce?
• When should nonces be used (key rotation scenarios)?
• How should nonce concatenation work with the JCS output?

3. Error Handling Specifications

Questions:

• How should invalid JSON-LD segments be handled?
• What should happen with malformed semantic paths?
• Are there specific error codes or messages expected?

4. JSON-LD Validation Requirements

Questions:

• Must all segments be valid Schema.org entities, or just well-formed JSON-LD?
• Are there restrictions on nested object depth or property counts?
• How strict should URI validation be for @context values?

5. BIP-85 Integration Details

The spec uses: bip85_ent(master, m/83696968'/67797668'/{parent_semantic_image})

Questions:

• Should this follow standard BIP-85 entropy derivation exactly?
• What happens for the root level where there's no parent path?
• Is the 64-byte entropy output always used as the full HMAC key?

6. Test Vector Validation

The specification mentions: "TODO: Test vectors"

Questions:

• Would you be willing to review test vectors from our reference implementation?
• Can we create canonical test cases for the website password example in the spec?
• What would be the best way to ensure our implementation matches your intent?

Our Implementation Progress

We've successfully verified all major dependencies:

• ✅ HMAC-SHA512 via @noble/hashes
• ✅ BIP-32 HD wallets via @scure/bip32
• ✅ RFC 8785 JSON Canonicalization (basic implementation)
• ⚠️ BIP-85 (will implement custom solution)

Request

Would you be available for a brief technical discussion or code review once we have a working implementation? We want to ensure the first reference implementation correctly represents your specification.

Our goal is to have this completed within 10-12 days and would greatly appreciate any guidance you can provide.

Thank you for creating this innovative approach to semantic key derivation!

Reference Implementation Repository: https://github.com/lessuselesss/bip-keychain-ref

Best regards,
The DAOgora Development Team

[akarve]

howdy, good to hear from you.

When should hardened vs non-hardened derivation be used for semantic segments?
Should there be a default policy (e.g., all hardened except final index)?
Are there security implications for specific patterns?

In practice all extant applications use hardened keys at every segment. See footnote 1 in BIP 85, it covers the implications. I would say hardened is the default until and unless there's a good reason not to harden.

[akarve]

The spec mentions: hmac(...) || optional_nonce

Oh I see. Well first I should say I proposed this spec to the bitcoin list and it never went anywhere so I stopped working on it. Feel free to revive. Original thread was Pre-BIP feedback: Secrets keychain with semantic derivation.

[akarve]

You can reach me at dowsing.seaport0d at icloud.com if I can be helpful. As mentioned it didn't go anywhere BIP wise so I stopped working on it but there's something interesting here.

[akarve]

Would you be willing to review test vectors from our reference implementation?

sure i'm still working on bipsea and i have been meaning to add a "free path" function anyway so yeah

Can we create canonical test cases for the website password example in the spec?

sure if you deem this worth continuing given that it hasn't gathered enough steam to become a BIP

What would be the best way to ensure our implementation matches your intent?

test vecs and a spec is cool. email above.