-
Notifications
You must be signed in to change notification settings - Fork 6
/
README.md
271 lines (191 loc) · 13.6 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
# FCL Swift
## Overview
This reference documents all the methods available in the SDK, and explains in detail how these methods work.
SDKs are open source, and you can use them according to the licence.
#### Feature list:
- [x] Sign in/up with Wallet provider
- [x] Configure app
- [x] Query cadence script with arguments
- [x] Send transaction with non-custodial mode (Blocto)
- [x] Send transaction with custodial wallet
- [x] Support all access api endpoint such as `GetAccount` and `GetLastestBlock`
- [x] Sign user message
- [x] Verify user signature
- [x] Account Proof
- [x] Verify account proof
- [x] Support custom `authz` func
## Getting Started
### Installing
This is a Swift Package, and can be installed via Xcode with the URL of this repository:
```swift
.package(name: "FCL", url: "https://github.com/outblock/fcl-swift.git", from: "0.1.1")
```
## Config
Values only need to be set once. We recommend doing this once and as early in the life cycle as possible. To set a configuration value, the `put` method on the `config` instance needs to be called, the `put` method returns the `config` instance so they can be chained.
```swift
let accountProof = FCL.Metadata.AccountProofConfig(appIdentifier: "xxxx", nonce: "xxxx")
let walletConnect = FCL.Metadata.WalletConnectConfig(urlScheme: "xxxx", projectID: "xxxx")
let metadata = FCL.Metadata(appName: "xxx",
appDescription: "xxx",
appIcon: URL(string: "xxxx")!,
location: URL(string: "xxx")!,
accountProof: accountProof,
walletConnectConfig: walletConnect)
fcl.config(metadata: metadata,
env: env,
provider: provider)
```
### Common Configuration Keys
| Name | Example | Description |
| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accessNode.api` **(required)** | `https://access-testnet.onflow.org` | API URL for the Flow Blockchain Access Node you want to be communicating with. See all available access node endpoints [here](https://docs.onflow.org/access-api/#flow-access-node-endpoints). |
| `env` | `testnet` | Used in conjunction with stored interactions. Possible values: `local`, `canarynet`, `testnet`, `mainnet` |
| `discovery.wallet` **(required)** | `https://fcl-discovery.onflow.org/testnet/authn` | Points FCL at the Wallet or Wallet Discovery mechanism. |
| `app.detail.title` | `Cryptokitties` | Your applications title, can be requested by wallets and other services. |
| `app.detail.icon` | `https://fcl-discovery.onflow.org/images/blocto.png` | Url for your applications icon, can be requested by wallets and other services. |
| `location` **(required)** | `https://foo.com` | Your application's site URL, can be requested by wallets and other services. |
| `challenge.handshake` | **DEPRECATED** | Use `discovery.wallet` instead. |
### Address replacement in scripts and transactions
Configuration keys that start with `0x` will be used to find-and-replace their values in Cadence scripts and transactions input to FCL. Typically this is used to represent account addresses. Account addresses for the same contract will be different depending on the Flow network you're interacting with (eg. Testnet, Mainnet).
This allows you to write your script or transaction once and not have to update code when you point your application at a different Flow network.
```swift
fcl.config
.put(key: "0xFungibleToken", value: "0xf233dcee88fe0abe")
.put(key: "0xFUSD", value: "0x3c5959b568896393")
fcl.query {
cadence {
"""
import FungibleToken from 0xFungibleToken
import FUSD from 0xFUSD
pub fun main(account: Address): UFix64 {
let receiverRef = getAccount(account).getCapability(/public/fusdBalance)!
.borrow<&FUSD.Vault{FungibleToken.Balance}>()
return receiverRef!.balance
}
"""
}
arguments {
[.address(Flow.Address(hex: address))]
}
}
```
# Wallet Interactions
These methods allows dapps to interact with FCL compatible wallets in order to authenticate the user and authorize transactions on their behalf.
### Methods
## `authenticate`
Calling this method will authenticate the current user via any wallet that supports FCL. Once called, FCL will initiate communication with the configured `authn` endpoint which lets the user select a wallet to authenticate with. Once the wallet provider has authenticated the user, FCL will set the values on the [current user](#currentuserobject) object for future use and authorization.
#### Usage
```swift
let accountProof = FCL.Metadata.AccountProofConfig(appIdentifier: "xxxx", nonce: "xxxx")
let walletConnect = FCL.Metadata.WalletConnectConfig(urlScheme: "xxxx", projectID: "xxxx")
let metadata = FCL.Metadata(appName: "xxx",
appDescription: "xxx",
appIcon: URL(string: "xxxx")!,
location: URL(string: "xxx")!,
accountProof: accountProof,
walletConnectConfig: walletConnect)
let provider: FCL.Provider = .flowWallet
fcl.config(metadata: metadata,
env: env,
provider: provider)
fcl.authenticate()
```
## `authz`
A **convenience method** that produces the needed authorization details for the current user to submit transactions to Flow. It defines a signing function that connects to a user's wallet provider to produce signatures to submit transactions.
#### Usage
**Note:** The default values for `proposer`, `payer`, and `authorizations` are already `fcl.authz` so there is no need to include these parameters, it is shown only for example purposes. See more on [signing roles](https://docs.onflow.org/concepts/accounts-and-keys/#signing-a-transaction).
```swift
try await fcl.mutate(cadence:
"""
transaction(test: String, testInt: Int) {
prepare(signer: AuthAccount) {
log(signer.address)
log(test)
log(testInt)
}
}
""",
args: [.string("Test2"), .int(1)])
```
---
# On-chain Interactions
> 📣 **These methods can be used in browsers and NodeJS.**
These methods allows dapps to interact directly with the Flow blockchain via a set of functions that currently use the [Access Node API](https://docs.onflow.org/access-api/).
### Methods
---
### Query and Mutate Flow with Cadence
If you want to run arbitrary Cadence scripts on the blockchain, these methods offer a convenient way to do so **without having to build, send, and decode interactions**.
## `query`
Allows you to submit scripts to query the blockchain.
#### Options
_Pass in the following as a single object with the following keys.All keys are optional unless otherwise stated._
| Key | Type | Description |
| --------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cadence` | string **(required)** | A valid cadence script. |
| `arguments` | [ArgumentFunction](#argumentfunction) | Any arguments to the script if needed should be supplied via a function that returns an array of arguments. |
| `gasLimit` | number | Compute (Gas) limit for query. Read the [documentation about computation cost](https://docs.onflow.org/flow-go-sdk/building-transactions/#gas-limit) for information about how computation cost is calculated on Flow. |
#### Returns
| Type | Description |
| ---- | -------------------------------------- |
| Flow.ScriptResponse | A model representation of the response. |
#### Usage
```swift
fcl.query {
cadence {
"""
pub fun main(a: Int, b: Int, addr: Address): Int {
log(addr)
return a + b
}
"""
}
arguments {
[.int(7), .int(6), .address(Flow.Address(hex: "0x01"))]
}
}
```
## `mutate`
Allows you to submit transactions to the blockchain to potentially mutate the state.
⚠️When being used in the browser, `fcl.mutate` uses the built-in `fcl.authz` function to produce the authorization (signatures) for the current user. When calling this method from Node.js, you will need to supply your own custom authorization function.
#### Options
_Pass in the following as a single object with the following keys. All keys are optional unless otherwise stated._
| Key | Type | Description |
| ---------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cadence` | string **(required)** | A valid cadence transaction. |
| `arguments` | [ArgumentFunction](#argumentfunction) | Any arguments to the script if needed should be supplied via a function that returns an array of arguments. |
| `gasLimit` | number | Compute (Gas) limit for query. Read the [documentation about computation cost](https://docs.onflow.org/flow-go-sdk/building-transactions/#gas-limit) for information about how computation cost is calculated on Flow. |
#### Returns
| Type | Description |
| ------ | ------------------- |
| string | The transaction ID. |
#### Usage
```swift
try await fcl.mutate(cadence:
"""
transaction(test: String, testInt: Int) {
prepare(signer: AuthAccount) {
log(signer.address)
log(test)
log(testInt)
}
}
""",
args: [.string("Test2"), .int(1)])
```
## `getBlock`
A builder function that returns the interaction to get the latest block.
📣 Use with `fcl.atBlockId()` and `fcl.atBlockHeight()` when building the interaction to get information for older blocks.
⚠️Consider using the pre-built interaction [`fcl.latestBlock(isSealed)`](#latestblock) if you do not need to pair with any other builders.
#### Arguments
| Name | Type | Default | Description |
| ---------- | ------- | ------- | ------------------------------------------------------------------------------ |
| `sealed` | boolean | true | If the latest block should be sealed or not. See [block states](#interaction). |
#### Returns after decoding
| Type | Description |
| ----------------------------- | ----------------------------------------------------- |
| [BlockObject](#blockobject) | The latest block if not used with any other builders. |
#### Usage
```swift
fcl.getLastestBlock()
```
## TODO: Add more example