Skip to content

Format BTCMnemonic docs for AppleDoc #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
KingParmenides wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Format BTCMnemonic docs for AppleDoc #142

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 54 additions & 26 deletions CoreBitcoin/BTCMnemonic.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,63 +3,91 @@
#import <Foundation/Foundation.h>

typedef NS_ENUM(int8_t, BTCMnemonicWordListType) {
// English wordlist specified by BIP39.
/** English wordlist specified by BIP39. */
BTCMnemonicWordListTypeEnglish = 0,

// If this is specified when importing mnemonic, checksum can not be verified.
/** Unknown wordlist. When importing a mnemonic, the checksum cannot be verified. */
BTCMnemonicWordListTypeUnknown = -1,
};

@class BTCKeychain;

// Implementation of BIP39: Mnemonic code for generating deterministic keys.
/**
* Implements BIP39 mnemonic codes for generating deterministic keys.
*/
@interface BTCMnemonic : NSObject

// Type of the wordlist being used.
/** Type of the wordlist being used. */
@property(nonatomic, readonly) BTCMnemonicWordListType wordListType;

// Raw entropy buffer used as an input.
/** Raw entropy buffer used as input. */
@property(nonatomic, readonly) NSData* entropy;

// A list of words composed from the rawEntropy using the specified wordlist.
// This wordlist can be written down by the user and used to recover the seed.
/**
* List of words composed from the receiver's entropy using the specified wordlist.
*
* These words can be written down by the user and used to recover the seed.
*/
@property(nonatomic, readonly) NSArray* words;

// Optional password. If not specified, returns an empty string.
/** Optional password. If no password was specified, returns an empty string. */
@property(nonatomic, readonly) NSString* password;

// Returns a wallet seed computed from words and password that you can use in BIP32 or alike.
// Note: The name "seed" means an input for the external key derivation scheme (e.g. BIP32),
// not to this mnemonic implementation. Input for the mnemonic is `entropy`, `password` and `wordListType`.
/**
* Wallet seed computed from words and password for use with BIP32 or similar schemes.
*
* @discussion In this API, "seed" means an input for an external key derivation
* scheme, such as BIP32. The inputs for this mnemonic implementation are
* `entropy`, `password`, and `wordListType`.
*/
@property(nonatomic, readonly) NSData* seed;

// Root keychain instantiated with a given seed.
/** Root keychain instantiated with the receiver's seed. */
@property(nonatomic, readonly) BTCKeychain* keychain;

// Compact binary representation of the mnemonic.
/** Compact binary representation of the mnemonic. */
@property(nonatomic, readonly) NSData* data;

// Binary representation of the mnemonic with computed seed appended (so it can be cached).
/** Binary representation of the mnemonic with the computed seed appended for caching. */
@property(nonatomic, readonly) NSData* dataWithSeed;

// Inits mnemonic with a raw entropy buffer, optional password and a wordlist.
// If `password` is nil, it is treated as an empty string.
// `entropy` length in bits must be divisible by 32 (128, 160, 192, 224, 256 bits).
// Returns nil if entropy has incorrect size or wordlist is not supported.
/**
* Initializes a mnemonic with a raw entropy buffer, optional password, and wordlist.
*
* @param entropy Raw entropy. Its length in bits must be divisible by 32:
* 128, 160, 192, 224, or 256 bits.
* @param password Optional password. If `nil`, it is treated as an empty string.
* @param wordListType Wordlist used to encode the mnemonic words.
*
* @return Initialized mnemonic, or `nil` if entropy has an incorrect size or
* the wordlist is not supported.
*/
- (id) initWithEntropy:(NSData*)entropy password:(NSString*)password wordListType:(BTCMnemonicWordListType)wordListType;

// Inits mnemonic with user's words, optional password and an optional wordlist type.
// If `password` is nil, it is treated as an empty string.
// If `wordListType` is BTCMnemonicWordListTypeUnknown, checksum is not verified.
// Returns nil if checksum is invalid.
/**
* Initializes a mnemonic with user-provided words, optional password, and wordlist type.
*
* @param words Mnemonic words to import.
* @param password Optional password. If `nil`, it is treated as an empty string.
* @param wordListType Wordlist used by the words. If this is
* `BTCMnemonicWordListTypeUnknown`, the checksum is not verified.
*
* @return Initialized mnemonic, or `nil` if the checksum is invalid.
*/
- (id) initWithWords:(NSArray*)words password:(NSString*)password wordListType:(BTCMnemonicWordListType)wordListType;

// Deserializes mnemonic from its binary representation
// (which contains wordlist type, raw entropy, password and optional computed seed).
// If the data was produced by `-dataWithSeed` method, seed will not be recomputed.
/**
* Deserializes a mnemonic from its binary representation.
*
* @param data Binary representation containing wordlist type, raw entropy,
* password, and optional computed seed.
*
* @return Initialized mnemonic. If the data was produced by `-dataWithSeed`,
* the seed is loaded from data and is not recomputed.
*/
- (id) initWithData:(NSData*)data;

// Clears all sensitive information from memory.
/** Clears all sensitive information from memory. */
- (void) clear;

@end