@bsv/sdk 1.2.6 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/primitives/PublicKey.ts

@@ -30,7 +30,7 @@ export default class PublicKey extends Point {
    * const myPrivKey = new PrivateKey(...)
    * const myPubKey = PublicKey.fromPrivateKey(myPrivKey)
    */
-  static fromPrivateKey (key: PrivateKey): PublicKey {
+  static fromPrivateKey(key: PrivateKey): PublicKey {
     const c = new Curve()
     const p = c.g.mul(key)
     return new PublicKey(p.x, p.y)
@@ -46,7 +46,7 @@ export default class PublicKey extends Point {
    * @example
    * const myPubKey = PublicKey.fromString("03....")
    */
-  static fromString (str: string): PublicKey {
+  static fromString(str: string): PublicKey {
     const p = Point.fromString(str)
     return new PublicKey(p.x, p.y)
   }
@@ -61,7 +61,7 @@ export default class PublicKey extends Point {
    * @example
    * const myPubKey = PublicKey.fromString("03....")
    */
-  static fromDER (bytes: number[]): PublicKey {
+  static fromDER(bytes: number[]): PublicKey {
     const p = Point.fromDER(bytes)
     return new PublicKey(p.x, p.y)
   }
@@ -76,7 +76,7 @@ export default class PublicKey extends Point {
    * new PublicKey(point1);
    * new PublicKey('abc123', 'def456');
    */
-  constructor (
+  constructor(
     x: Point | BigNumber | number | number[] | string | null,
     y: BigNumber | number | number[] | string | null = null,
     isRed: boolean = true
@@ -84,6 +84,12 @@ export default class PublicKey extends Point {
     if (x instanceof Point) {
       super(x.getX(), x.getY())
     } else {
+      // Common gotcha: constructing PublicKey with a DER value when you should use .fromString()
+      if (y === null && isRed === true && typeof x === 'string') {
+        if (x.length === 66 || x.length === 130) {
+          throw new Error('You are using the "new PublicKey()" constructor with a DER hex string. You need to use "PublicKey.fromString()" instead.')
+        }
+      }
       super(x, y, isRed)
     }
   }
@@ -102,7 +108,7 @@ export default class PublicKey extends Point {
    * const myPrivKey = new PrivateKey(...)
    * const sharedSecret = myPubKey.deriveSharedSecret(myPrivKey)
    */
-  deriveSharedSecret (priv: PrivateKey): Point {
+  deriveSharedSecret(priv: PrivateKey): Point {
     if (!this.validate()) {
       throw new Error('Public key not valid for ECDH secret derivation')
     }
@@ -123,7 +129,7 @@ export default class PublicKey extends Point {
    * const mySignature = new Signature(...)
    * const isVerified = myPubKey.verify(myMessage, mySignature)
    */
-  verify (msg: number[] | string, sig: Signature, enc?: 'hex' | 'utf8'): boolean {
+  verify(msg: number[] | string, sig: Signature, enc?: 'hex' | 'utf8'): boolean {
     const msgHash = new BigNumber(sha256(msg, enc), 16)
     return verify(msgHash, sig, this)
   }
@@ -138,7 +144,7 @@ export default class PublicKey extends Point {
    * @example
    * const derPublicKey = myPubKey.toDER()
    */
-  toDER (enc?: 'hex' | undefined): number[] | string {
+  toDER(enc?: 'hex' | undefined): number[] | string {
     if (enc === 'hex') return this.encode(true, enc) as string
     return this.encode(true) as number[]
   }
@@ -151,7 +157,7 @@ export default class PublicKey extends Point {
    * @example
    * const publicKeyHash = pubkey.toHash()
    */
-  toHash (enc?: 'hex'): number[] | string {
+  toHash(enc?: 'hex'): number[] | string {
     const pkh = hash160(this.encode(true))
     if (enc === 'hex') {
       return toHex(pkh)
@@ -173,7 +179,7 @@ export default class PublicKey extends Point {
    * const testnetAddress = pubkey.toAddress([0x6f])
    * const testnetAddress = pubkey.toAddress('testnet')
    */
-  toAddress (prefix: number[] | string = [0x00]): string {
+  toAddress(prefix: number[] | string = [0x00]): string {
     if (typeof prefix === 'string') {
       if (prefix === 'testnet' || prefix === 'test') {
         prefix = [0x6f]
@@ -192,7 +198,7 @@ export default class PublicKey extends Point {
    * @param invoiceNumber The invoice number used to derive the child key
    * @returns The derived child key.
    */
-  deriveChild (privateKey: PrivateKey, invoiceNumber: string): PublicKey {
+  deriveChild(privateKey: PrivateKey, invoiceNumber: string): PublicKey {
     const sharedSecret = this.deriveSharedSecret(privateKey)
     const invoiceNumberBin = toArray(invoiceNumber, 'utf8')
     const hmac = sha256hmac(sharedSecret.encode(true), invoiceNumberBin)
@@ -219,7 +225,7 @@ export default class PublicKey extends Point {
    * @example
    * const publicKey = Signature.fromMsgHashAndCompactSignature(msgHash, 'IMOl2mVKfDgsSsHT4uIYBNN4e...', 'base64');
    */
-  static fromMsgHashAndCompactSignature (msgHash: BigNumber, signature: number[] | string, enc?: 'hex' | 'base64'): PublicKey {
+  static fromMsgHashAndCompactSignature(msgHash: BigNumber, signature: number[] | string, enc?: 'hex' | 'base64'): PublicKey {
     const data = toArray(signature, enc)
     if (data.length !== 65) {
       throw new Error('Invalid Compact Signature')

package/src/primitives/__tests/PublicKey.test.ts

@@ -27,6 +27,12 @@ describe('PublicKey', () => {
     })
   })
 
+  describe('Constructor', () => {
+    it('Should throw when accidentally passing in DER', () => {
+      expect(() => new PublicKey('036af279b60aa437d48bb0e2ec0b0c6b5cfaa976663f1f08ad456fd7fff149321d')).toThrow()
+    })
+  })
+
   describe('Instance methods', () => {
     test('deriveSharedSecret should derive a shared secret Point', () => {
       const sharedSecret = publicKey.deriveSharedSecret(privateKey)

package/src/script/templates/PushDrop.ts

@@ -2,6 +2,7 @@ import { ScriptTemplate, LockingScript, UnlockingScript, OP } from '../index.js'
 import { Utils, Hash, TransactionSignature, Signature, PublicKey } from '../../primitives/index.js'
 import { Wallet } from '../../wallet/Wallet.interfaces.js'
 import { Transaction } from '../../transaction/index.js'
+import { SecurityLevel } from '../../wallet/Wallet.interfaces.js'
 
 /**
  * For a given piece of data to push onto the stack in script, creates the correct minimally-encoded script chunk,
@@ -93,14 +94,14 @@ export default class PushDrop implements ScriptTemplate {
    * Creates a PushDrop locking script with arbitrary data fields and a public key lock.
    *
    * @param {number[][]} fields - The token fields to include in the locking script.
-   * @param {[0 | 1 | 2, string]} protocolID - The protocol ID to use.
+   * @param {[SecurityLevel, string]} protocolID - The protocol ID to use.
    * @param {string} keyID - The key ID to use.
    * @param {string} counterparty - The counterparty involved in the transaction, "self" or "anyone".
    * @param {boolean} [forSelf=false] - Flag indicating if the lock is for the creator (default no).
    * @param {boolean} [includeSignature=true] - Flag indicating if a signature should be included in the script (default yes).
    * @returns {Promise<LockingScript>} The generated PushDrop locking script.
    */
-  async lock(fields: number[][], protocolID: [0 | 1 | 2, string], keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: 'before' | 'after' = 'before'): Promise<LockingScript> {
+  async lock(fields: number[][], protocolID: [SecurityLevel, string], keyID: string, counterparty: string, forSelf = false, includeSignature = true, lockPosition: 'before' | 'after' = 'before'): Promise<LockingScript> {
     const { publicKey } = await this.wallet.getPublicKey({
       protocolID,
       keyID,
@@ -148,7 +149,7 @@ export default class PushDrop implements ScriptTemplate {
   /**
    * Creates an unlocking script for spending a PushDrop token output.
    *
-   * @param {[0 | 1 | 2, string]} protocolID - The protocol ID to use.
+   * @param {[SecurityLevel, string]} protocolID - The protocol ID to use.
    * @param {string} keyID - The key ID to use.
    * @param {string} counterparty - The counterparty involved in the transaction, "self" or "anyone".
    * @param {string} [sourceTXID] - The TXID of the source transaction.
@@ -159,7 +160,7 @@ export default class PushDrop implements ScriptTemplate {
    * @returns {Object} An object containing functions to sign the transaction and estimate the script length.
    */
   unlock(
-    protocolID: [0 | 1 | 2, string],
+    protocolID: [SecurityLevel, string],
     keyID: string,
     counterparty: string,
     signOutputs: 'all' | 'none' | 'single' = 'all',

package/src/transaction/Transaction.ts

@@ -479,13 +479,9 @@ export default class Transaction {
    * @param changeDistribution - Specifies how the change should be distributed
    * amongst the change outputs
    *
-   * TODO: Benford's law change distribution.
    */
-  async fee (modelOrFee?: FeeModel | number, changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
+  async fee (modelOrFee: FeeModel | number = new SatoshisPerKilobyte(10), changeDistribution: 'equal' | 'random' = 'equal'): Promise<void> {
     this.cachedHash = undefined
-    if (typeof modelOrFee === 'undefined') {
-      modelOrFee = new SatoshisPerKilobyte(10)
-    }
     if (typeof modelOrFee === 'number') {
       const sats = modelOrFee
       modelOrFee = {

package/src/wallet/CachedKeyDeriver.ts

@@ -1,5 +1,6 @@
 import { PrivateKey, PublicKey, SymmetricKey } from '../primitives/index.js'
 import KeyDeriver from './KeyDeriver.js'
+import { SecurityLevel } from './Wallet.interfaces.js'
 
 /**
  * A cached version of KeyDeriver that caches the results of key derivation methods.
@@ -26,14 +27,14 @@ export default class CachedKeyDeriver {
   /**
      * Derives a public key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @param {boolean} [forSelf=false] - Whether deriving for self.
      * @returns {PublicKey} - The derived public key.
      */
   derivePublicKey (
-    protocolID: [0 | 1 | 2, string],
+    protocolID: [SecurityLevel, string],
     keyID: string,
     counterparty: PublicKey | string | 'self' | 'anyone',
     forSelf: boolean = false
@@ -51,13 +52,13 @@ export default class CachedKeyDeriver {
   /**
      * Derives a private key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {PrivateKey} - The derived private key.
      */
   derivePrivateKey (
-    protocolID: [0 | 1 | 2, string],
+    protocolID: [SecurityLevel, string],
     keyID: string,
     counterparty: PublicKey | string | 'self' | 'anyone'
   ): PrivateKey {
@@ -74,14 +75,14 @@ export default class CachedKeyDeriver {
   /**
      * Derives a symmetric key based on protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {SymmetricKey} - The derived symmetric key.
      * @throws {Error} - Throws an error if attempting to derive a symmetric key for 'anyone'.
      */
   deriveSymmetricKey (
-    protocolID: [0 | 1 | 2, string],
+    protocolID: [SecurityLevel, string],
     keyID: string,
     counterparty: PublicKey | string | 'self' | 'anyone'
   ): SymmetricKey {
@@ -117,13 +118,13 @@ export default class CachedKeyDeriver {
      * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
      * Caches the result for future calls with the same parameters.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @returns {number[]} - The specific key association as a number array.
      */
   revealSpecificSecret (
     counterparty: PublicKey | string | 'self' | 'anyone',
-    protocolID: [0 | 1 | 2, string],
+    protocolID: [SecurityLevel, string],
     keyID: string
   ): number[] {
     const cacheKey = this.generateCacheKey('revealSpecificSecret', counterparty, protocolID, keyID)

package/src/wallet/KeyDeriver.ts

@@ -1,4 +1,5 @@
 import { PrivateKey, PublicKey, SymmetricKey, Hash, Utils } from '../primitives/index.js'
+import { SecurityLevel } from '../wallet/Wallet.interfaces.js'
 
 /**
  * Class responsible for deriving various types of keys using a root private key.
@@ -21,13 +22,13 @@ export default class KeyDeriver {
 
   /**
      * Derives a public key based on protocol ID, key ID, and counterparty.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @param {boolean} [forSelf=false] - Whether deriving for self.
      * @returns {PublicKey} - The derived public key.
      */
-  derivePublicKey (protocolID: [0 | 1 | 2, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone', forSelf: boolean = false): PublicKey {
+  derivePublicKey (protocolID: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone', forSelf: boolean = false): PublicKey {
     counterparty = this.normalizeCounterparty(counterparty)
     if (forSelf) {
       return this.rootKey.deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID)).toPublicKey()
@@ -38,12 +39,12 @@ export default class KeyDeriver {
 
   /**
      * Derives a private key based on protocol ID, key ID, and counterparty.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {PrivateKey} - The derived private key.
      */
-  derivePrivateKey (protocolID: [0 | 1 | 2, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): PrivateKey {
+  derivePrivateKey (protocolID: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): PrivateKey {
     counterparty = this.normalizeCounterparty(counterparty)
     return this.rootKey.deriveChild(counterparty, this.computeInvoiceNumber(protocolID, keyID))
   }
@@ -51,13 +52,13 @@ export default class KeyDeriver {
   /**
      * Derives a symmetric key based on protocol ID, key ID, and counterparty.
      * Note: Symmetric keys should not be derivable by everyone due to security risks.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
      * @returns {SymmetricKey} - The derived symmetric key.
      * @throws {Error} - Throws an error if attempting to derive a symmetric key for 'anyone'.
      */
-  deriveSymmetricKey (protocolID: [0 | 1 | 2, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): SymmetricKey {
+  deriveSymmetricKey (protocolID: [SecurityLevel, string], keyID: string, counterparty: PublicKey | string | 'self' | 'anyone'): SymmetricKey {
     if (counterparty === 'anyone') {
       throw new Error(
         'Symmetric keys (such as encryption keys or HMAC keys) should not be derivable by everyone, because messages would be decryptable by anyone who knows the identity public key of the user, and HMACs would be similarly forgeable.'
@@ -97,11 +98,11 @@ export default class KeyDeriver {
   /**
      * Reveals the specific key association for a given protocol ID, key ID, and counterparty.
      * @param {PublicKey | string | 'self' | 'anyone'} counterparty - The counterparty's public key or a predefined value ('self' or 'anyone').
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @returns {number[]} - The specific key association as a number array.
      */
-  revealSpecificSecret (counterparty: PublicKey | string | 'self' | 'anyone', protocolID: [0 | 1 | 2, string], keyID: string): number[] {
+  revealSpecificSecret (counterparty: PublicKey | string | 'self' | 'anyone', protocolID: [SecurityLevel, string], keyID: string): number[] {
     counterparty = this.normalizeCounterparty(counterparty)
     const sharedSecret = this.rootKey.deriveSharedSecret(counterparty)
     const invoiceNumberBin = Utils.toArray(this.computeInvoiceNumber(protocolID, keyID), 'utf8')
@@ -130,12 +131,12 @@ export default class KeyDeriver {
 
   /**
      * Computes the invoice number based on the protocol ID and key ID.
-     * @param {[0 | 1 | 2, string]} protocolID - The protocol ID including a security level and protocol name.
+     * @param {[SecurityLevel, string]} protocolID - The protocol ID including a security level and protocol name.
      * @param {string} keyID - The key identifier.
      * @returns {string} - The computed invoice number.
      * @throws {Error} - Throws an error if protocol ID or key ID are invalid.
      */
-  private computeInvoiceNumber (protocolID: [0 | 1 | 2, string], keyID: string): string {
+  private computeInvoiceNumber (protocolID: [SecurityLevel, string], keyID: string): string {
     const securityLevel = protocolID[0]
     if (!Number.isInteger(securityLevel) || securityLevel < 0 || securityLevel > 2) {
       throw new Error('Protocol security level must be 0, 1, or 2')

package/src/wallet/ProtoWallet.ts

@@ -23,6 +23,7 @@ import {
   ProtocolString5To400Bytes,
   PubKeyHex,
   SatoshiValue,
+  SecurityLevel,
   TXIDHexString,
   VersionString7To30Bytes,
   Wallet
@@ -256,7 +257,7 @@ export default class ProtoWallet implements Wallet {
   async getPublicKey (
     args: {
       identityKey?: true
-      protocolID?: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID?: [SecurityLevel, ProtocolString5To400Bytes]
       keyID?: KeyIDStringUnder800Bytes
       privileged?: BooleanDefaultFalse
       privilegedReason?: DescriptionString5to50Bytes
@@ -338,7 +339,7 @@ export default class ProtoWallet implements Wallet {
     args: {
       counterparty: PubKeyHex
       verifier: PubKeyHex
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       privileged?: BooleanDefaultFalse
@@ -348,7 +349,7 @@ export default class ProtoWallet implements Wallet {
       prover: PubKeyHex
       verifier: PubKeyHex
       counterparty: PubKeyHex
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       encryptedLinkage: Byte[]
       encryptedLinkageProof: Byte[]
@@ -390,7 +391,7 @@ export default class ProtoWallet implements Wallet {
   async encrypt (
     args: {
       plaintext: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'
@@ -412,7 +413,7 @@ export default class ProtoWallet implements Wallet {
   async decrypt (
     args: {
       ciphertext: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'
@@ -434,7 +435,7 @@ export default class ProtoWallet implements Wallet {
   async createHmac (
     args: {
       data: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'
@@ -457,7 +458,7 @@ export default class ProtoWallet implements Wallet {
     args: {
       data: Byte[]
       hmac: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'
@@ -484,7 +485,7 @@ export default class ProtoWallet implements Wallet {
     args: {
       data?: Byte[]
       hashToDirectlySign?: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'
@@ -512,7 +513,7 @@ export default class ProtoWallet implements Wallet {
       data?: Byte[]
       hashToDirectlyVerify?: Byte[]
       signature: Byte[]
-      protocolID: [0 | 1 | 2, ProtocolString5To400Bytes]
+      protocolID: [SecurityLevel, ProtocolString5To400Bytes]
       keyID: KeyIDStringUnder800Bytes
       privilegedReason?: DescriptionString5to50Bytes
       counterparty?: PubKeyHex | 'self' | 'anyone'

package/src/wallet/Wallet.interfaces.ts

@@ -191,7 +191,30 @@ export type ErrorDescriptionString20To200Bytes = string
 
 export type WalletNetwork = 'mainnet' | 'testnet'
 
-export type WalletProtocol = [0 | 1 | 2, ProtocolString5To400Bytes]
+/**
+ * @enum {number} SecurityLevels
+ *
+ * Silent = 0 Silently grants the request with no user interation.
+ * App = 1 Requires user approval for every application.
+ * Counterparty = 2 Requires user approval per counterparty per application.
+ */
+export enum SecurityLevels {
+  Silent = 0,
+  App = 1,
+  Counterparty = 2
+}
+
+/**
+ *
+ * SecurityLevel for protocols.
+ * 0 = Silently grants the request with no user interation.
+ * 1 = Requires user approval for every application.
+ * 2 = Requires user approval per counterparty per application.
+ *
+ */
+export type SecurityLevel = 0 | 1 | 2
+
+export type WalletProtocol = [SecurityLevel, ProtocolString5To400Bytes]
 
 export type WalletCounterparty = PubKeyHex | 'self' | 'anyone'
 
@@ -528,13 +551,20 @@ export interface ListOutputsResult {
 
 /**
    * @param {WalletProtocol} protocolID - The security level and protocol string under which the data should be encrypted.
+   * @param {SecurityLevel} securityLevel - The security level of the protocol.
+   * @param {WalletProtocol} protocolID - The security level and protocol string under which the data should be encrypted.
+   * @param {SecurityLevel} protocolID[0] - SecurityLevel:
+   * 0 = Silently grants the request with no user interation.
+   * 1 = Requires user approval for every application.
+   * 2 = Requires user approval per counterparty per application.
+   * @param {ProtocolString5To400Bytes} protocolID[1] - The name of the protocol.
    * @param {KeyIDStringUnder800Bytes} keyID - Key ID under which the encryption will be performed.
    * @param {DescriptionString5to50Bytes} [privilegedReason] - Reason provided for privileged access, required if this is a privileged operation.
    * @param {WalletCounterparty} [counterparty] - Public key of the counterparty (if two-party encryption is desired).
    * @param {BooleanDefaultFalse} [privileged] - Whether this is a privileged request.
  */
 export interface KeyLinkageArgs {
-  protocolID: WalletProtocol
+  protocolID: [SecurityLevel, ProtocolString5To400Bytes]
   keyID: KeyIDStringUnder800Bytes
   counterparty?: WalletCounterparty
   privileged?: BooleanDefaultFalse

package/src/wallet/WalletClient.ts

@@ -1,4 +1,4 @@
-import { AcquireCertificateArgs, AcquireCertificateResult, Base64String, BasketStringUnder300Bytes, BEEF, BooleanDefaultFalse, BooleanDefaultTrue, Byte, CertificateFieldNameUnder50Bytes, CreateActionArgs, CreateActionResult, DescriptionString5to50Bytes, DiscoverCertificatesResult, EntityIconURLStringMax500Bytes, EntityNameStringMax100Bytes, HexString, InternalizeActionArgs, ISOTimestampString, KeyIDStringUnder800Bytes, LabelStringUnder300Bytes, ListActionsArgs, ListActionsResult, ListCertificatesResult, ListOutputsArgs, ListOutputsResult, OriginatorDomainNameStringUnder250Bytes, OutpointString, OutputTagStringUnder300Bytes, PositiveInteger, PositiveIntegerDefault10Max10000, PositiveIntegerMax10, PositiveIntegerOrZero, ProtocolString5To400Bytes, ProveCertificateArgs, ProveCertificateResult, PubKeyHex, SatoshiValue, SignActionArgs, SignActionResult, TXIDHexString, VersionString7To30Bytes, Wallet } from './Wallet.interfaces.js'
+import { AcquireCertificateArgs, AcquireCertificateResult, Base64String, BasketStringUnder300Bytes, BEEF, BooleanDefaultFalse, BooleanDefaultTrue, Byte, CertificateFieldNameUnder50Bytes, CreateActionArgs, CreateActionResult, DescriptionString5to50Bytes, DiscoverCertificatesResult, EntityIconURLStringMax500Bytes, EntityNameStringMax100Bytes, HexString, InternalizeActionArgs, ISOTimestampString, KeyIDStringUnder800Bytes, LabelStringUnder300Bytes, ListActionsArgs, ListActionsResult, ListCertificatesResult, ListOutputsArgs, ListOutputsResult, OriginatorDomainNameStringUnder250Bytes, OutpointString, OutputTagStringUnder300Bytes, PositiveInteger, PositiveIntegerDefault10Max10000, PositiveIntegerMax10, PositiveIntegerOrZero, ProtocolString5To400Bytes, ProveCertificateArgs, ProveCertificateResult, PubKeyHex, SatoshiValue, SecurityLevel, SignActionArgs, SignActionResult, TXIDHexString, VersionString7To30Bytes, Wallet } from './Wallet.interfaces.js'
 import WindowCWISubstrate from './substrates/window.CWI.js'
 import XDMSubstrate from './substrates/XDM.js'
 import WalletWireTransceiver from './substrates/WalletWireTransceiver.js'
@@ -95,7 +95,7 @@ export default class WalletClient implements Wallet {
     return await (this.substrate as Wallet).relinquishOutput(args, this.originator)
   }
 
-  async getPublicKey (args: { identityKey?: true, protocolID?: [0 | 1 | 2, ProtocolString5To400Bytes], keyID?: KeyIDStringUnder800Bytes, privileged?: BooleanDefaultFalse, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse }): Promise<{ publicKey: PubKeyHex }> {
+  async getPublicKey (args: { identityKey?: true, protocolID?: [SecurityLevel, ProtocolString5To400Bytes], keyID?: KeyIDStringUnder800Bytes, privileged?: BooleanDefaultFalse, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse }): Promise<{ publicKey: PubKeyHex }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).getPublicKey(args, this.originator)
   }
@@ -105,36 +105,36 @@ export default class WalletClient implements Wallet {
     return await (this.substrate as Wallet).revealCounterpartyKeyLinkage(args, this.originator)
   }
 
-  async revealSpecificKeyLinkage (args: { counterparty: PubKeyHex, verifier: PubKeyHex, protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, privileged?: BooleanDefaultFalse }): Promise<{ prover: PubKeyHex, verifier: PubKeyHex, counterparty: PubKeyHex, protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, encryptedLinkage: Byte[], encryptedLinkageProof: Byte[], proofType: Byte }> {
+  async revealSpecificKeyLinkage (args: { counterparty: PubKeyHex, verifier: PubKeyHex, protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, privileged?: BooleanDefaultFalse }): Promise<{ prover: PubKeyHex, verifier: PubKeyHex, counterparty: PubKeyHex, protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, encryptedLinkage: Byte[], encryptedLinkageProof: Byte[], proofType: Byte }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).revealSpecificKeyLinkage(args, this.originator)
   }
 
-  async encrypt (args: { plaintext: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ ciphertext: Byte[] }> {
+  async encrypt (args: { plaintext: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ ciphertext: Byte[] }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).encrypt(args, this.originator)
   }
 
-  async decrypt (args: { ciphertext: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ plaintext: Byte[] }> {
+  async decrypt (args: { ciphertext: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ plaintext: Byte[] }> {
     return await (this.substrate as Wallet).decrypt(args, this.originator)
   }
 
-  async createHmac (args: { data: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ hmac: Byte[] }> {
+  async createHmac (args: { data: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ hmac: Byte[] }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).createHmac(args, this.originator)
   }
 
-  async verifyHmac (args: { data: Byte[], hmac: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
+  async verifyHmac (args: { data: Byte[], hmac: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).verifyHmac(args, this.originator)
   }
 
-  async createSignature (args: { data?: Byte[], hashToDirectlySign?: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ signature: Byte[] }> {
+  async createSignature (args: { data?: Byte[], hashToDirectlySign?: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', privileged?: BooleanDefaultFalse }): Promise<{ signature: Byte[] }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).createSignature(args, this.originator)
   }
 
-  async verifySignature (args: { data?: Byte[], hashToDirectlyVerify?: Byte[], signature: Byte[], protocolID: [0 | 1 | 2, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse, privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
+  async verifySignature (args: { data?: Byte[], hashToDirectlyVerify?: Byte[], signature: Byte[], protocolID: [SecurityLevel, ProtocolString5To400Bytes], keyID: KeyIDStringUnder800Bytes, privilegedReason?: DescriptionString5to50Bytes, counterparty?: PubKeyHex | 'self' | 'anyone', forSelf?: BooleanDefaultFalse, privileged?: BooleanDefaultFalse }): Promise<{ valid: true }> {
     await this.connectToSubstrate()
     return await (this.substrate as Wallet).verifySignature(args, this.originator)
   }

package/src/wallet/substrates/WalletWireProcessor.ts

@@ -3,6 +3,7 @@ import WalletWire from './WalletWire.js'
 import { Utils } from '../../primitives/index.js'
 import calls from './WalletWireCalls.js'
 import Certificate from '../../auth/Certificate.js'
+import { SecurityLevel } from '../Wallet.interfaces.js'
 
 /**
  * Processes incoming wallet calls received over a wallet wire, with a given wallet.
@@ -1914,8 +1915,8 @@ export default class WalletWireProcessor implements WalletWire {
     }
   }
 
-  private decodeProtocolID(reader: Utils.Reader): [0 | 1 | 2, string] {
-    const securityLevel = reader.readUInt8() as 0 | 1 | 2
+  private decodeProtocolID(reader: Utils.Reader): [SecurityLevel, string] {
+    const securityLevel = reader.readUInt8() as SecurityLevel
     const protocolLength = reader.readVarIntNum()
     const protocolBytes = reader.read(protocolLength)
     const protocolString = Utils.toUTF8(protocolBytes)