docs: update readme

hirosystems · Jul 24, 2023 · 0855707 · 0855707 · vercel · Jul 24, 2023
1 parent 7fc5a32
commit 0855707
Showing 1 changed file with 65 additions and 46 deletions.
diff --git a/packages/connect/README.md b/packages/connect/README.md
@@ -30,9 +30,9 @@ export const userSession = new UserSession({ appConfig }); // we will use this e
 
 - ["Connect" aka authentication (`showConnect`)](#connect-aka-authentication-showconnect)
 - [Sending STX (`openSTXTransfer`)](#sending-stx-openstxtransfer)
-- [Sending transactions with post-conditions (`openSTXTransfer`)](#sending-transactions-with-post-conditions-openstxtransfer)
-  - [Post-Condition Modes](#post-condition-modes)
 - [Calling Smart-Contracts (`openContractCall`)](#calling-smart-contracts-opencontractcall)
+- [Sending transactions with post-conditions (`openContractCall`)](#sending-transactions-with-post-conditions-opencontractcall)
+  - [Post-Condition Modes](#post-condition-modes)
 
 #### "Connect" aka authentication (`showConnect`)
 
@@ -99,7 +99,43 @@ openSTXTransfer({
 });
 ```
 
-#### Sending transactions with post-conditions (`openSTXTransfer`)
+#### Calling Smart-Contracts (`openContractCall`)
+
+Calling smart-contracts lets users interact with the blockchain through transactions.
+
+The snippet below will open the wallet to _confirm and broadcast_ a smart-contract transaction.
+Here, we are passing our pick `Alice` to an imaginary deployed voting smart-contract.
+
+```js
+import { openContractCall } from '@stacks/connect';
+import { StacksTestnet } from '@stacks/network';
+import { AnchorMode, PostConditionMode, stringUtf8CV } from '@stacks/transactions';
+import { userSession } from './userSession';
+
+const pick = stringUtf8CV('Alice');
+
+openContractCall({
+  network: new StacksTestnet(),
+  anchorMode: AnchorMode.Any, // which type of block the tx should be mined in
+
+  contractAddress: 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK',
+  contractName: 'example-contract',
+  functionName: 'vote',
+  functionArgs: [pick],
+
+  postConditionMode: PostConditionMode.Deny,
+  postConditions: [],
+
+  onFinish: response => {
+    // WHEN user confirms pop-up
+  },
+  onCancel: () => {
+    // WHEN user cancels/closes pop-up
+  },
+});
+```
+
+#### Sending transactions with post-conditions (`openContractCall`)
 
 Consider the example above.
 Using [post-conditions](https://docs.hiro.so/get-started/transactions#post-conditions), a feature of the Stacks blockchain, we can ensure something happened after a transaction.
@@ -112,20 +148,20 @@ import {
   makeStandardSTXPostCondition,
 } from '@stacks/transactions';
 
-// this post-condition ensures that our recipient receives at least 5000 tokens
+// this post-condition ensures that our recipient receives at least 5000 STX tokens
 const myPostCondition = makeStandardSTXPostCondition(
   'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK', // address of recipient
   FungibleConditionCode.GreaterEqual, // comparator
-  5000 // relative amount to previous balance
+  5000000000 // relative amount to previous balance (denoted in micro-STX)
 );
 
-// passing to `openSTXTransfer` options, e.g. modifying our previous example ...
+// passing to `openContractCall` options, e.g. modifying our previous example ...
   postConditionMode: PostConditionMode.Deny, // whether the tx should fail when unexpected assets are transferred
   postConditions: [ myPostCondition ],
 // ...
 ```
 
-> For more examples on constructing different kinds of post-conditions read the [Post-Conditions Guide of Stacks.js](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#post-conditions).
+> For more examples on constructing different kinds of post-conditions read the [Post-Conditions Guide of Stacks.js](https://github.com/hirosystems/stacks.js/tree/main/packages/transactions#post-conditions).
 
 ##### Post-Condition Modes
 
@@ -138,48 +174,29 @@ The _Post-Condition Mode_ only relates to transfers of assets, which were not sp
 - `PostConditionMode.Allow` will allow unspecified assets to be transferred
 - In both cases, all `postConditions` will be checked
 
-#### Calling Smart-Contracts (`openContractCall`)
+### 🛠 Advanced <!-- omit in toc -->
 
-Calling smart-contracts lets users interact with the blockchain through transactions.
+#### Opening a specific wallet <!-- omit in toc -->
 
-The snippet below will open the wallet to _confirm and broadcast_ a smart-contract transaction.
-Here, we are passing our pick `Alice` to an imaginary deployed voting smart-contract.
+By default, `@stacks/connect` will defer to the `window.StacksProvider` object to interact with wallets.
+However, if multiple wallets are installed, they might interfere with each other.
+To avoid this, you can specify which wallet to use in the wallet interaction methods.
 
 ```js
-import { openContractCall } from '@stacks/connect';
-import { StacksTestnet } from '@stacks/network';
-import { AnchorMode, PostConditionMode, stringUtf8CV } from '@stacks/transactions';
-import { userSession } from './userSession';
-
-const pick = stringUtf8CV('Alice');
-
-openContractCall({
-  network: new StacksTestnet(),
-  anchorMode: AnchorMode.Any, // which type of block the tx should be mined in
-
-  contractAddress: 'ST39MJ145BR6S8C315AG2BD61SJ16E208P1FDK3AK',
-  contractName: 'example-contract',
-  functionName: 'vote',
-  functionArgs: [pick],
-
-  postConditionMode: PostConditionMode.Deny,
-  postConditions: [],
-
-  onFinish: response => {
-    // WHEN user confirms pop-up
-  },
-  onCancel: () => {
-    // WHEN user cancels/closes pop-up
-  },
-});
+// This will open only the Hiro Wallet
+authenticate({ ...opts }, HiroWalletProvider);
+openPsbtRequestPopup({ ...opts }, HiroWalletProvider);
+openProfileUpdateRequestPopup({ ...opts }, HiroWalletProvider);
+openSignatureRequestPopup({ ...opts }, HiroWalletProvider);
+openStructuredDataSignatureRequestPopup({ ...opts }, HiroWalletProvider);
 ```
 
 ## 🤔 Pitfalls <!-- omit in toc -->
 
 - Connect can currently not set manual nonces, since this is not supported by wallets.
 - For some projects it might be necessary to also install the `regenerator-runtime` package. `npm install --save-dev regenerator-runtime`. This is a build issue of `@stacks/connect` and we are working on a fix.
 
-## 📚 Option Glossary <!-- omit in toc -->
+## 📚 Method Parameters <!-- omit in toc -->
 
 A glossary of the most common options of `openSTXTransfer` and `openContractCall`
 
@@ -201,11 +218,13 @@ A glossary of the most common options of `openSTXTransfer` and `openContractCall
 
 ### _Optional_ <!-- omit in toc -->
 
-|              | Default             | Description                                                           | Type                                                                        | Example                  |
-| :----------- | :------------------ | :-------------------------------------------------------------------- | :-------------------------------------------------------------------------- | :----------------------- |
-| `network`    | Mainnet             | The network to broadcast the transaction to                           | [StacksNetwork](https://stacks.js.org/classes/network.StacksNetwork.html)   | `new StacksMainnet()`    |
-| `anchorMode` | Any                 | The type of block the transaction should be mined in                  | [AnchorMode Enum](https://stacks.js.org/enums/transactions.AnchorMode.html) | `AnchorMode.OnChainOnly` |
-| `memo`       | _Empty_ `''`        | The memo field (used for additional data)                             | `string`                                                                    | `'a memo'`               |
-| `fee`        | _Handled by Wallet_ | The transaction fee (the wallet will estimate fees as well)           | Integer (e.g. `number`, `bigint`)                                           | `1000`                   |
-| `onFinish`   | _No-op_             | The callback function to run after broadcasting the transaction       | Function (receiving `response`)                                             |                          |
-| `onCancel`   | _No-op_             | The callback function to run after the user cancels/closes the wallet | Function                                                                    |                          |
+|                     | Default             | Description                                                                 | Type                                                                            | Example                   |
+| :------------------ | :------------------ | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------ | :------------------------ |
+| `network`           | Mainnet             | The network to broadcast the transaction to                                 | [StacksNetwork](https://stacks.js.org/classes/network.StacksNetwork.html)       | `new StacksMainnet()`     |
+| `anchorMode`        | Any                 | The type of block the transaction should be mined in                        | [AnchorMode Enum](https://stacks.js.org/enums/transactions.AnchorMode.html)     | `AnchorMode.OnChainOnly`  |
+| `memo`              | _Empty_ `''`        | The memo field (used for additional data)                                   | `string`                                                                        | `'a memo'`                |
+| `fee`               | _Handled by Wallet_ | The transaction fee (the wallet will estimate fees as well)                 | Integer (e.g. `number`, `bigint`)                                               | `1000`                    |
+| `postConditionMode` | Deny                | The post condition mode, _i.e. whether to allow unspecified asset transfer_ | [PostConditionMode](https://stacks.js.org/enums/transactions.PostConditionMode) | `PostConditionMode.Allow` |
+| `postConditions`    | _Empty_ `[]`        | The list of post conditions to check, regardless of postConditionMode       | [PostCondition](https://stacks.js.org/types/transactions.PostCondition)[]       |                           |
+| `onFinish`          | _No-op_             | The callback function to run after broadcasting the transaction             | Function (receiving `response`)                                                 |                           |
+| `onCancel`          | _No-op_             | The callback function to run after the user cancels/closes the wallet       | Function                                                                        |                           |