* feat: connect tx signing docs
* fix: use codeBody instead of contractSource
* fix: show explicit appDetails
* fix: link to principal docs
* fix: typo in how it works
With Connect, you can interact with the Stacks 2.0 blockchain. You can allow your users to send transactions and interact with smart contracts.
With Connect, you can interact with the Stacks 2.0 blockchain. You can allow your users to send transactions and interact with smart contracts.
* TOC
{:toc}
## How it works
For your app's users to be able to execute a smart contract function, they need to sign and broadcast a transaction. It's important that users remain control of the private keys that sign these transactions. Connect provides an easy-to-use workflow that allows your users to securely sign transactions.
Connect allows you to open the authenticator with parameters indicating the details of the transaction - like the smart contract address, function name, and specific arguments. Your users get the chance to see these details, and then sign and broadcast the transaction in a single click. Their transaction will be securely signed and broadcasted onto the Stacks blockchain. After this is done, a callback is fired to allow you to update your app.
## Usage
<divclass="uk-card uk-card-default uk-card-body">
<divclass="uk-card uk-card-default uk-card-body">
<h5class="uk-card-title">Transaction signing is still in progress</h5>
<h5class="uk-card-title">Transaction signing is still in progress</h5>
<p>
To use these features, make sure you install the <code>testnet</code> tag the <code>@blockstack/connect</code> NPM package. You can do this by running <code>npm install --save @blockstack/connect@testnet</code>, or by specifying <code>testnet</code> as the version in
your package.json file.
</p>
<p>
<p>
The Stacks 2.0 blockchain is still in testnet, and our web app integration is also still in beta. In order to use transaction signing in your application, you need to use the configuration `authOrigin` with `@blockstack/connect`.
The Stacks 2.0 blockchain is still in testnet, and our web app integration is also still in beta. In order to use transaction signing in your application, you need to use the configuration `authOrigin` with `@blockstack/connect`.
</p>
</p>
@ -33,34 +26,81 @@ Connect allows you to open the authenticator with parameters indicating the deta
</pre>
</pre>
</div>
</div>
### `ContractCallOptions`
* TOC
{:toc}
## How it works
For your app's users to be able to execute a smart contract function, they need to sign and broadcast a transaction. It's important that users remain in control of the private keys that sign these transactions. Connect provides an easy-to-use workflow that allows your users to securely sign transactions.
Connect allows you to open the authenticator with parameters indicating the details of the transaction - like the smart contract address, function name, and specific arguments. Your users get the chance to see these details, and then sign and broadcast the transaction in a single click. Their transaction will be securely signed and broadcasted onto the Stacks blockchain. After this is done, a callback is fired to allow you to update your app.
## Calling Clarity Contract Functions
Once you have a Clarity smart contract built and deployed, you'll naturally want to allow your app's users to interact with it.
When signing a transaction, you need to specify a few details. Here is the exact interface that describes what options you have:
To initiate a contract call transaction, use the `openContractCall` function.
```ts
```ts
export interface ContractCallOptions {
import { openContractCall } from '@blockstack/connect';
When calling `openContractCall`, you need to specify a few details. Here is the exact interface that describes what options you have:
```ts
interface ContractCallOptions {
contractAddress: string;
contractAddress: string;
functionName: string;
functionName: string;
contractName: string;
contractName: string;
functionArgs?: any[];
functionArgs?: any[];
authOrigin?: string;
authOrigin?: string;
userSession?: UserSession;
appDetails: {
appDetails?: AuthOptions['appDetails'];
name: string;
finished?: (data: FinishedTxData) => void;
icon: string;
};
finished: (data: FinishedTxData) => void;
}
}
```
```
parameter | type | default | optional | description
parameter | type | optional | description
---|---|---|---|---
---|---|---|---
contractAddress | string | | false | The Stacks address that published this contract
contractAddress | string | false | The Stacks address that published this contract
contractName | string | | false | The name that was used when publishing this contract
contractName | string | false | The name that was used when publishing this contract
functionName | string | | false | The name of the function you're calling. This needs to be a [public function](/core/smart/clarityRef.html#define-public).
functionName | string | false | The name of the function you're calling. This needs to be a [public function](/core/smart/clarityRef.html#define-public).
functionArgs | array | | false | The arguments you're calling the function with. You'll need to provide the Clarity type with each argument. See the below section for details.
functionArgs | array | false | The arguments you're calling the function with. You'll need to provide the Clarity type with each argument. See the below section for details. Defaults to `[]`.
userSession | UserSession | | true | A `UserSession` instance
appDetails | object | false | A dictionary that includes `name` and `icon`
appDetails | object | | false | A dictionary that includes `name` and `icon`
finished | function | false | A callback that is fired when the transaction is signed and broadcasted. Your callback will receive an object back with a `txId` and a `txRaw`, both of which are strings.
finished | function | | false | A callback that is fired when the transaction is signed and broadcasted. Your callback will receive an object back with a `txId` and a `txRaw`, both of which are strings.
authOrigin | string | true | The location of the authenticator. This is only necessary when developing the authenticator locally, or when using beta features. Defaults to `"https://app.blockstack.org"`.
#### Passing Clarity types with function arguments
### Passing Clarity types with function arguments
To be able to serialize your transaction properly, you need to provide the appropriate Clarity type with each argument. These types are named the same as they are in Clarity. The `value` that you pass must be a string. The types you can pass are:
To be able to serialize your transaction properly, you need to provide the appropriate Clarity type with each argument. These types are named the same as they are in Clarity. The `value` that you pass must be a string. The types you can pass are:
@ -68,7 +108,7 @@ To be able to serialize your transaction properly, you need to provide the appro
- `int` - i.e. `"12"`
- `int` - i.e. `"12"`
- `bool` - can be "true", "false", "0" or "1"
- `bool` - can be "true", "false", "0" or "1"
- `buff` - i.e. `"asdf"`
- `buff` - i.e. `"asdf"`
- `principal` - This can be a contract principal, or a standard principal. Examples: `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ"` or `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ.my-contract"`.
- `principal` - This can be a contract principal, or a standard principal. [Read more about principals](/core/smart/principals.html). Examples: `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ"` or `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ.my-contract"`.
Using these types, each argument is an object with the keys `type` and `value`. For example:
Using these types, each argument is an object with the keys `type` and `value`. For example:
@ -87,40 +127,110 @@ const functionArguments = [
If you're using Typescript, these Clarity types can be imported as `ContractCallArgumentType` from `@blockstack/connect`.
If you're using Typescript, these Clarity types can be imported as `ContractCallArgumentType` from `@blockstack/connect`.
### Usage in ES6 (non-React) apps
## Stacks (STX) Token Transfers
STX token transfers can be initiated with the `openSTXTransfer` function.
```ts
```ts
import { openContractCall } from '@blockstack/connect';
import { openSTXTransfer } from '@blockstack/connect';
When calling `openSTXTransfer`, you need to specify a few details. Here are the options you have:
```ts
interface STXTransferOptions {
recipient: string;
amount: string;
memo?: string;
authOrigin?: string;
appDetails: {
name: string;
icon: string;
};
};
finished: (data: FinishedTxData) => void;
}
```
await openContractCall(opts);
parameter | type | optional | description
---|---|---|---
recipient | string | false | The STX Address for the recipient of this STX transfer
amount | string | false | The amount of microstacks (µSTX) to be transferred. This argument is a string to prevent floating point errors. There are 1,000,000 µSTX per STX.
memo | string | true | An optional memo to include in the transaction.
appDetails | object | false | A dictionary that includes `name` and `icon`
finished | function | false | A callback that is fired when the transaction is signed and broadcasted. Your callback will receive an object back with a `txId` and a `txRaw`, both of which are strings.
authOrigin | string | true | The location of the authenticator. This is only necessary when developing the authenticator locally, or when using beta features. Defaults to `"https://app.blockstack.org"`.
## Deploying Clarity Contracts
To allow your app's users to deploy arbitrary Clarity contracts, use the `openContractDeploy` method.
```ts
import { openContractDeploy } from '@blockstack/connect';
Here is the interface for the options you can provide to `openContractDeploy`:
```ts
interface ContractDeployOptions {
codeBody: string;
contractName: string;
authOrigin?: string;
appDetails: {
name: string;
icon: string;
};
finished: (data: FinishedTxData) => void;
}
```
```
### Usage in React Apps
parameter | type | optional | description
---|---|---|---
codeBody | string | false | The Clarity source code for this contract
contractName | string | false | The name for this contract
appDetails | object | false | A dictionary that includes `name` and `icon`
finished | function | false | A callback that is fired when the transaction is signed and broadcasted. Your callback will receive an object back with a `txId` and a `txRaw`, both of which are strings.
authOrigin | string | true | The location of the authenticator. This is only necessary when developing the authenticator locally, or when using beta features. Defaults to `"https://app.blockstack.org"`.
## Usage in React Apps
Make sure you follow the [setup instructions](/develop/connect/get-started.html#in-react-apps) first. When you're using `useConnect`, you don't have to specify `appDetails` - we'll pick that up from your existing configuration.
Make sure you follow the [setup instructions](/develop/connect/get-started.html#in-react-apps) first. When you're using `useConnect`, you don't have to specify `appDetails` - we'll pick that up from your existing configuration.
Each transaction signing method is exposed through the `useConnect` hook, but they're prefixed with `do` instead of `open`, to remain consistent with our React action naming standards.
Hank Stoever
4 years ago
GitHub