@ledgerhq/hw-app-str 6.29.0-windows-certificate.0 → 8.0.0-nightly.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @ledgerhq/hw-app-str@6.28.6 build /home/runner/work/ledger-live/ledger-live/libs/ledgerjs/packages/hw-app-str
+> @ledgerhq/hw-app-str@7.0.0 build /home/runner/work/ledger-live/ledger-live/libs/ledgerjs/packages/hw-app-str
 > tsc && tsc -m ES6 --outDir lib-es
 

package/CHANGELOG.md

@@ -1,15 +1,25 @@
 # @ledgerhq/hw-app-str
 
-## 6.29.0-windows-certificate.0
+## 8.0.0-nightly.0
 
-### Minor Changes
+### Major Changes
 
-- [#6596](https://github.com/LedgerHQ/ledger-live/pull/6596) [`77fa530`](https://github.com/LedgerHQ/ledger-live/commit/77fa530c8626df94fa7f9c0a8b3a99f2efa7cb11) Thanks [@KVNLS](https://github.com/KVNLS)! - Upgrade React Native to version 0.73.6
+- [#6923](https://github.com/LedgerHQ/ledger-live/pull/6923) [`782d637`](https://github.com/LedgerHQ/ledger-live/commit/782d637b5fba8c9c9d37609b6ad492f45a4b3737) Thanks [@overcat](https://github.com/overcat)! - Refactor `hw-app-str` and add `signSorobanAuthorization`. Please check the changelog and documentation of "@ledgerhq/hw-app-str" for more information.
 
-### Patch Changes
+## 7.0.0
+
+### Major Changes
 
-- Updated dependencies [[`77fa530`](https://github.com/LedgerHQ/ledger-live/commit/77fa530c8626df94fa7f9c0a8b3a99f2efa7cb11)]:
-  - @ledgerhq/hw-transport@6.31.0-windows-certificate.0
+- `Str.getPublicKey`'s function signature has changed. Previously, it was `getPublicKey(path: string, boolValidate?: boolean, boolDisplay?: boolean): Promise<{ publicKey: string; raw: Buffer; }>` and now it is `async getPublicKey(path: string, display = false): Promise<{ rawPublicKey: Buffer }>`
+- `Str.signTransaction` will no longer automatically fallback to `Str.signHash`. If you want to sign a hash, you have to call `Str.signHash` directly.
+- Removed the fixed limit on the maximum length of the transaction in `Str.signTransaction`. Currently, if the transaction is too large for the device to handle, `StellarUserRefusedError` will be thrown.
+- Add `Str.signSorobanAuthorization` method to sign Stellar Soroban authorization.
+- `Str.getAppConfiguration` now returns `maxDataSize`, it represents the maximum size of the data that the device can processed.
+- Add error classes for better error handling, check the documentation for more information:
+  - `StellarUserRefusedError`
+  - `StellarHashSigningNotEnabledError`
+  - `StellarDataTooLargeError`
+  - `StellarDataParsingFailedError`
 
 ## 6.28.6
 

package/README.md

@@ -1,62 +1,14 @@
 <img src="https://user-images.githubusercontent.com/4631227/191834116-59cf590e-25cc-4956-ae5c-812ea464f324.png" height="100" />
 
-## Ledger Stellar app API
+[GitHub](https://github.com/LedgerHQ/ledger-live/),
+[Ledger Devs Discord](https://developers.ledger.com/discord-pro),
+[Developer Portal](https://developers.ledger.com/)
 
-## Usage
+## @ledgerhq/hw-app-str
 
+Ledger Hardware Wallet Stellar JavaScript bindings.
 
-```js
-// when using "@ledgerhq/hw-transport-node-hid" library you need to go to
-// Settings -> Browser support in ledger stellar app and set this setting to 'No'
-import Transport from "@ledgerhq/hw-transport-node-hid";
-// import Transport from "@ledgerhq/hw-transport-u2f"; // for browser
-import Str from "@ledgerhq/hw-app-str";
-import * as StellarSdk from "@stellar/stellar-sdk";
-
-const getStrAppVersion = async () => {
-    const transport = await Transport.create();
-    const str = new Str(transport);
-    const result = await str.getAppConfiguration();
-    return result.version;
-}
-getStrAppVersion().then(v => console.log(v));
-
-const getStrPublicKey = async () => {
-  const transport = await Transport.create();
-  const str = new Str(transport);
-  const result = await str.getPublicKey("44'/148'/0'");
-  return result.publicKey;
-};
-let publicKey;
-getStrPublicKey().then(pk => {
-    console.log(pk);
-    publicKey = pk;
-});
-
-const signStrTransaction = async (publicKey) => {
-  const transaction = new StellarSdk.TransactionBuilder({accountId: () => publicKey, sequenceNumber: () => '1234', incrementSequenceNumber: () => null})
-    .addOperation(StellarSdk.Operation.createAccount({
-       source: publicKey,
-       destination: 'GBLYVYCCCRYTZTWTWGOMJYKEGQMTH2U3X4R4NUI7CUGIGEJEKYD5S5OJ', // SATIS5GR33FXKM7HVWZ2UQO33GM66TVORZUEF2HPUQ3J7K634CTOAWQ7
-       startingBalance: '11.331',
-    }))
-    .build();
-  const transport = await Transport.create();
-  const str = new Str(transport);
-  const result = await str.signTransaction("44'/148'/0'", transaction.signatureBase());
-  
-  // add signature to transaction
-  const keyPair = StellarSdk.Keypair.fromPublicKey(publicKey);
-  const hint = keyPair.signatureHint();
-  const decorated = new StellarSdk.xdr.DecoratedSignature({hint: hint, signature: result.signature});
-  transaction.signatures.push(decorated);
-  
-  return transaction;
-}
-signStrTransaction(publicKey).then(transaction => console.log(transaction.toEnvelope().toXDR().toString('base64')));
-```
-
----
+***
 
 ## Are you adding Ledger support to your software wallet?
 
@@ -64,7 +16,159 @@ You may be using this package to communicate with the Stellar Nano App.
 
 For a smooth and quick integration:
 
-- See the developers’ documentation on the [Developer Portal](https://developers.ledger.com/docs/transport/overview/) and
-- Go on [Discord](https://developers.ledger.com/discord-pro/) to chat with developer support and the developer community.
+*   See the developers’ documentation on the [Developer Portal](https://developers.ledger.com/docs/transport/overview/) and
+*   Go on [Discord](https://developers.ledger.com/discord-pro/) to chat with developer support and the developer community.
+
+***
+
+## Errors handling
+
+All functions may throw an error, it's important to handle the errors properly.
+
+We have written corresponding classes for exceptions that developers should actively handle, you can find them in the [API](#api) section.
+
+***
+
+## API
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+#### Table of Contents
+
+*   [StellarHashSigningNotEnabledError](#stellarhashsigningnotenablederror)
+*   [StellarDataParsingFailedError](#stellardataparsingfailederror)
+*   [StellarUserRefusedError](#stellaruserrefusederror)
+*   [StellarDataTooLargeError](#stellardatatoolargeerror)
+*   [Str](#str)
+    *   [Parameters](#parameters)
+    *   [Examples](#examples)
+    *   [getAppConfiguration](#getappconfiguration)
+        *   [Examples](#examples-1)
+    *   [getPublicKey](#getpublickey)
+        *   [Parameters](#parameters-1)
+        *   [Examples](#examples-2)
+    *   [signTransaction](#signtransaction)
+        *   [Parameters](#parameters-2)
+        *   [Examples](#examples-3)
+    *   [signSorobanAuthorization](#signsorobanauthorization)
+        *   [Parameters](#parameters-3)
+        *   [Examples](#examples-4)
+    *   [signHash](#signhash)
+        *   [Parameters](#parameters-4)
+        *   [Examples](#examples-5)
+
+### StellarHashSigningNotEnabledError
+
+Error thrown when hash signing is not enabled on the device.
+
+### StellarDataParsingFailedError
+
+Error thrown when data parsing fails.
+
+For example, when parsing the transaction fails, this error is thrown.
+
+### StellarUserRefusedError
+
+Error thrown when the user refuses the request on the device.
+
+### StellarDataTooLargeError
+
+Error thrown when the data is too large to be processed by the device.
+
+### Str
+
+Stellar API
+
+#### Parameters
+
+*   `transport` **Transport** a transport for sending commands to a device
+*   `scrambleKey`  a scramble key (optional, default `"l0v"`)
+
+#### Examples
+
+```javascript
+import Str from "@ledgerhq/hw-app-str";
+const str = new Str(transport)
+```
+
+#### getAppConfiguration
+
+Get Stellar application configuration.
+
+##### Examples
+
+```javascript
+str.getAppConfiguration().then(o => o.version)
+```
+
+Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{version: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), hashSigningEnabled: [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean), maxDataSize: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?}>** an object with the application configuration, including the version,
+whether hash signing is enabled, and the maximum data size in bytes that the device can sign.
+
+#### getPublicKey
+
+Get Stellar raw public key for a given BIP 32 path.
+
+##### Parameters
+
+*   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP 32 format
+*   `display`  if true, the device will ask the user to confirm the address on the device, if false, it will return the raw public key directly (optional, default `false`)
+
+##### Examples
+
+```javascript
+str.getPublicKey("44'/148'/0'").then(o => o.rawPublicKey)
+```
+
+Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{rawPublicKey: [Buffer](https://nodejs.org/api/buffer.html)}>** an object with the raw ed25519 public key.
+If you want to convert it to string, you can use [StrKey.encodeEd25519PublicKey](https://stellar.github.io/js-stellar-base/StrKey.html#.encodeEd25519PublicKey)
+
+#### signTransaction
+
+Sign a Stellar transaction.
+
+##### Parameters
+
+*   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP 32 format
+*   `transaction` **[Buffer](https://nodejs.org/api/buffer.html)** [signature base](https://stellar.github.io/js-stellar-base/Transaction.html#signatureBase) of the transaction to sign
+
+##### Examples
+
+```javascript
+str.signTransaction("44'/148'/0'", signatureBase).then(o => o.signature)
+```
+
+Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{signature: [Buffer](https://nodejs.org/api/buffer.html)}>** an object with the signature
+
+#### signSorobanAuthorization
+
+Sign a Stellar Soroban authorization.
+
+##### Parameters
+
+*   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP 32 format
+*   `hashIdPreimage` **[Buffer](https://nodejs.org/api/buffer.html)** the [Soroban authorization hashIdPreimage](https://github.com/stellar/stellar-xdr/blob/1a04392432dacc0092caaeae22a600ea1af3c6a5/Stellar-transaction.x#L702-L709) to sign
+
+##### Examples
+
+```javascript
+str.signSorobanAuthorization("44'/148'/0'", hashIdPreimage).then(o => o.signature)
+```
+
+Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{signature: [Buffer](https://nodejs.org/api/buffer.html)}>** an object with the signature
+
+#### signHash
+
+Sign a hash.
+
+##### Parameters
+
+*   `path` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** a path in BIP 32 format
+*   `hash` **[Buffer](https://nodejs.org/api/buffer.html)** the hash to sign
+
+##### Examples
+
+```javascript
+str.signHash("44'/148'/0'", hash).then(o => o.signature)
+```
 
----
+Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<{signature: [Buffer](https://nodejs.org/api/buffer.html)}>** an object with the signature

package/lib/Str.d.ts

@@ -19,35 +19,48 @@ import type Transport from "@ledgerhq/hw-transport";
 /**
  * Stellar API
  *
+ * @param transport a transport for sending commands to a device
+ * @param scrambleKey a scramble key
+ *
  * @example
  * import Str from "@ledgerhq/hw-app-str";
  * const str = new Str(transport)
  */
 export default class Str {
-    transport: Transport;
+    private transport;
     constructor(transport: Transport, scrambleKey?: string);
+    /**
+     * Get Stellar application configuration.
+     *
+     * @returns an object with the application configuration, including the version,
+     *    whether hash signing is enabled, and the maximum data size in bytes that the device can sign.
+     * @example
+     * str.getAppConfiguration().then(o => o.version)
+     */
     getAppConfiguration(): Promise<{
         version: string;
+        hashSigningEnabled: boolean;
+        maxDataSize?: number;
     }>;
     /**
-     * get Stellar public key for a given BIP 32 path.
+     * Get Stellar raw public key for a given BIP 32 path.
+     *
      * @param path a path in BIP 32 format
-     * @option boolValidate optionally enable key pair validation
-     * @option boolDisplay optionally enable or not the display
-     * @return an object with the publicKey (using XLM public key format) and
-     * the raw ed25519 public key.
+     * @param display if true, the device will ask the user to confirm the address on the device, if false, it will return the raw public key directly
+     * @return an object with the raw ed25519 public key.
+     *    If you want to convert it to string, you can use {@link https://stellar.github.io/js-stellar-base/StrKey.html#.encodeEd25519PublicKey StrKey.encodeEd25519PublicKey}
      * @example
-     * str.getPublicKey("44'/148'/0'").then(o => o.publicKey)
+     * str.getPublicKey("44'/148'/0'").then(o => o.rawPublicKey)
      */
-    getPublicKey(path: string, boolValidate?: boolean, boolDisplay?: boolean): Promise<{
-        publicKey: string;
-        raw: Buffer;
+    getPublicKey(path: string, display?: boolean): Promise<{
+        rawPublicKey: Buffer;
     }>;
     /**
-     * sign a Stellar transaction.
+     * Sign a Stellar transaction.
+     *
      * @param path a path in BIP 32 format
-     * @param transaction signature base of the transaction to sign
-     * @return an object with the signature and the status
+     * @param transaction {@link https://stellar.github.io/js-stellar-base/Transaction.html#signatureBase signature base} of the transaction to sign
+     * @return an object with the signature
      * @example
      * str.signTransaction("44'/148'/0'", signatureBase).then(o => o.signature)
      */
@@ -55,18 +68,30 @@ export default class Str {
         signature: Buffer;
     }>;
     /**
-     * sign a Stellar transaction hash.
+     * Sign a Stellar Soroban authorization.
+     *
      * @param path a path in BIP 32 format
-     * @param hash hash of the transaction to sign
+     * @param hashIdPreimage the {@link https://github.com/stellar/stellar-xdr/blob/1a04392432dacc0092caaeae22a600ea1af3c6a5/Stellar-transaction.x#L702-L709 Soroban authorization hashIdPreimage} to sign
      * @return an object with the signature
      * @example
-     * str.signHash("44'/148'/0'", hash).then(o => o.signature)
+     * str.signSorobanAuthorization("44'/148'/0'", hashIdPreimage).then(o => o.signature)
      */
-    signHash(path: string, hash: Buffer): Promise<{
+    signSorobanAuthorization(path: string, hashIdPreimage: Buffer): Promise<{
         signature: Buffer;
     }>;
-    signHash_private(path: string, hash: Buffer): Promise<{
+    /**
+     * Sign a hash.
+     *
+     * @param path a path in BIP 32 format
+     * @param hash the hash to sign
+     * @return an object with the signature
+     * @example
+     * str.signHash("44'/148'/0'", hash).then(o => o.signature)
+     */
+    signHash(path: string, hash: Buffer): Promise<{
         signature: Buffer;
     }>;
+    private sendToDevice;
 }
+export * from "./errors";
 //# sourceMappingURL=Str.d.ts.map

package/lib/Str.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Str.d.ts","sourceRoot":"","sources":["../src/Str.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;kFAekF;AAClF,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AA4BpD;;;;;;GAMG;AAEH,MAAM,CAAC,OAAO,OAAO,GAAG;IACtB,SAAS,EAAE,SAAS,CAAC;gBAET,SAAS,EAAE,SAAS,EAAE,WAAW,SAAQ;IASrD,mBAAmB,IAAI,OAAO,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAWF;;;;;;;;;OASG;IACH,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,OAAO,EACtB,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IAuDF;;;;;;;OAOG;IACH,eAAe,CACb,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAkFF;;;;;;;OAOG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAKF,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CA+CH"}
+{"version":3,"file":"Str.d.ts","sourceRoot":"","sources":["../src/Str.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;kFAekF;AAClF,OAAO,KAAK,SAAS,MAAM,wBAAwB,CAAC;AA8BpD;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,GAAG;IACtB,OAAO,CAAC,SAAS,CAAY;gBAEjB,SAAS,EAAE,SAAS,EAAE,WAAW,SAAQ;IAerD;;;;;;;OAOG;IACG,mBAAmB,IAAI,OAAO,CAAC;QACnC,OAAO,EAAE,MAAM,CAAC;QAChB,kBAAkB,EAAE,OAAO,CAAC;QAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAUF;;;;;;;;;OASG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAWpF;;;;;;;;OAQG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAOF;;;;;;;;OAQG;IACG,wBAAwB,CAC5B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IAOF;;;;;;;;OAQG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QACT,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;YAOY,YAAY;CAsB3B;AA8CD,cAAc,UAAU,CAAC"}