Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

changes to ts-wallet-sdk docs #196

Merged
merged 4 commits into from
Aug 1, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/building-apps/wallet/component/kt/configClient.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
import { CodeExample } from "@site/src/components/CodeExample";

### Configuring the Client

The Kotlin wallet SDK uses the [ktor client](https://ktor.io/docs/getting-started-ktor-client.html) for all network requests (excluding Horizon, where the Stellar SDK's HTTP client is used). Currently, the okhttp engine is configured to be used with the client. You can read more about how to configure the ktor client [here](https://ktor.io/docs/create-client.html#configure-client).

For example, the client can be globally configured:

<CodeExample>

```kotlin
val walletCustomClient =
Wallet(
StellarConfiguration.Testnet,
ApplicationConfiguration(
defaultClientConfig = {
engine { this.config { this.connectTimeout(Duration.ofSeconds(10)) } }
install(HttpRequestRetry) {
retryOnServerErrors(maxRetries = 5)
exponentialDelay()
}
}
)
)
```

</CodeExample>

This Kotlin code will set the connect timeout to ten seconds via the [okhttp configuration](https://ktor.io/docs/http-client-engines.html#okhttp) and also installs the [retry plugin](https://ktor.io/docs/client-retry.html). You can also specify client configuration for specific wallet SDK classes.

For example, to change connect timeout when connecting to some anchor server:

<CodeExample>

```kotlin
val anchorCustomClient =
walletCustomClient.anchor("example.com") {
engine { this.config { this.connectTimeout(Duration.ofSeconds(30)) } }
}
```

</CodeExample>

### Closing Resources

After the wallet class is no longer used, it's necessary to close all clients used by it. While in some applications it may not be required (e.g. the wallet lives for the whole lifetime of the application), in other cases it can be required. If your wallet class is short-lived, it's recommended to close client resources using a close function:

<CodeExample>

```kotlin
fun closeWallet() {
wallet.close()
}
```

</CodeExample>
14 changes: 14 additions & 0 deletions docs/building-apps/wallet/component/kt/httpConfig.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
import { CodeExample } from "@site/src/components/CodeExample";

There is one more available configuration for a wallet that allows it to configure internal logic of the SDK. For example, to test with local servers on an HTTP protocol, HTTP can be manually enabled.

<CodeExample>

```kotlin
val walletCustom = Wallet(
StellarConfiguration.Testnet,
ApplicationConfiguration { defaultRequest { url { protocol = URLProtocol.HTTP } } }
)
```

</CodeExample>
31 changes: 31 additions & 0 deletions docs/building-apps/wallet/component/kt/watcher.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
import { CodeExample } from "@site/src/components/CodeExample";

Next, let's get the channel provided by `WatcherResult` to receive events.

<CodeExample>

```kt
do {
val event = result.channel.receive()
when (event) {
is StatusChange ->
println("Status changed to ${event.status}. Transaction: ${event.transaction}")
is ExceptionHandlerExit -> println("Exception handler exited the job")
is ChannelClosed -> println("Channel closed. Job is done")
}
} while (event !is ChannelClosed)
```

</CodeExample>

This code example will consume all events coming from the channel until it's closed. There are three types of events:

- `StatusChange`: indicates that transaction status has changed.
- `ExceptionHandlerExit`: indicates that the exception handler exited the processing loop. With default retry handler it happens when retries are exhausted.
- `ChannelClosed`: indicates that the channel is closed and no more events will be emitted. This event will always fire. If `ExceptionHandlerExit` happened, channel will close right after. Otherwise, (under normal circumstances) it will stop when all transactions reach terminal statuses.

:::info

Events are stored in the channel until they are received, and calling the `receive()` method will block the channel until a message is received. You can read more about how channels work in the [channel documentation](https://kotlinlang.org/docs/coroutines-and-channels.html#channels).

:::
24 changes: 24 additions & 0 deletions docs/building-apps/wallet/component/ts/configClient.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import { CodeExample } from "@site/src/components/CodeExample";

### Configuring the Client

The Typescript wallet SDK uses the [axios client](https://axios-http.com/docs/intro) for all network requests. You can read more about how to configure the axios client [here](https://axios-http.com/docs/instance).

For example, we can configure our axios client to be globally configured with a timeout:

<CodeExample>

```typescript
const customClient: AxiosInstance = axios.create({
timeout: 1000,
});
let appConfig = new ApplicationConfiguration(DefaultSigner, customClient);
let wal = new Wallet({
stellarConfiguration: StellarConfiguration.TestNet(),
applicationConfiguration: appConfig,
});
```

</CodeExample>

You can find more [configure options here.](https://axios-http.com/docs/req_config)
105 changes: 11 additions & 94 deletions docs/building-apps/wallet/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,11 @@ import { WalletCodeExample as CodeExample } from "@site/src/components/WalletCod
import Header from "./component/header.mdx";
import KtInstall from "./component/kt/install.mdx";
import TsInstall from "./component/ts/install.mdx";
import KtHttpConfig from "./component/kt/httpConfig.mdx";
import KtConfigClient from "./component/kt/configClient.mdx";
import TsConfigClient from "./component/ts/configClient.mdx";

<Header WIPLangs={["ts", "dart"]} />
<Header WIPLangs={["dart"]} />

## Installation

Expand Down Expand Up @@ -53,99 +56,9 @@ let wallet = new Wallet({

</CodeExample>

There is one more available configuration for a wallet that allows it to configure internal logic of the SDK. For example, to test with local servers on an HTTP protocol, HTTP can be manually enabled.
<LanguageSpecific kt={<KtHttpConfig />} />

<CodeExample>

```kotlin
val walletCustom = Wallet(
StellarConfiguration.Testnet,
ApplicationConfiguration { defaultRequest { url { protocol = URLProtocol.HTTP } } }
)
```

</CodeExample>

### Configuring the Client

The Kotlin wallet SDK uses the [ktor client](https://ktor.io/docs/getting-started-ktor-client.html) for all network requests (excluding Horizon, where the Stellar SDK's HTTP client is used). Currently, the okhttp engine is configured to be used with the client. You can read more about how to configure the ktor client [here](https://ktor.io/docs/create-client.html#configure-client).

The Typescript wallet SDK uses the [axios client](https://axios-http.com/docs/intro) for all network requests. You can read more about how to configure the axios client [here](https://axios-http.com/docs/instance).

For example, the client can be globally configured:

<CodeExample>

```kotlin
val walletCustomClient =
Wallet(
StellarConfiguration.Testnet,
ApplicationConfiguration(
defaultClientConfig = {
engine { this.config { this.connectTimeout(Duration.ofSeconds(10)) } }
install(HttpRequestRetry) {
retryOnServerErrors(maxRetries = 5)
exponentialDelay()
}
}
)
)
```

```typescript
const customClient: AxiosInstance = axios.create({
timeout: 1000,
});
let appConfig = new ApplicationConfiguration(DefaultSigner, customClient);
let wal = new Wallet({
stellarConfiguration: StellarConfiguration.TestNet(),
applicationConfiguration: appConfig,
});
```

</CodeExample>

This Kotlin code will set the connect timeout to ten seconds via the [okhttp configuration](https://ktor.io/docs/http-client-engines.html#okhttp) and also installs the [retry plugin](https://ktor.io/docs/client-retry.html). You can also specify client configuration for specific wallet SDK classes.

In Typescript, we can use axios to [configure](https://axios-http.com/docs/req_config) the timeout in milliseconds.

For example, to change connect timeout when connecting to some anchor server:

<CodeExample>

```kotlin
val anchorCustomClient =
walletCustomClient.anchor("example.com") {
engine { this.config { this.connectTimeout(Duration.ofSeconds(30)) } }
}
```

```typescript
const customClient: AxiosInstance = axios.create({
timeout: 10000,
});
let appConfig = new ApplicationConfiguration(DefaultSigner, customClient);
let wal = new Wallet({
stellarConfiguration: StellarConfiguration.TestNet(),
applicationConfiguration: appConfig,
});
```

</CodeExample>

### Closing Resources

After the wallet class is no longer used, it's necessary to close all clients used by it. While in some applications it may not be required (e.g. the wallet lives for the whole lifetime of the application), in other cases it can be required. If your wallet class is short-lived, it's recommended to close client resources using a close function:

<CodeExample>

```kotlin
fun closeWallet() {
wallet.close()
}
```

</CodeExample>
<LanguageSpecific kt={<KtConfigClient />} ts={<TsConfigClient />} />

## Stellar Basics

Expand All @@ -159,6 +72,10 @@ To interact with the Horizon instance configured in the previous steps, simply d
val stellar = wallet.stellar()
```

```typescript
const stellar = wallet.stellar();
```

</CodeExample>

This example will create a Stellar class that manages the connection to Horizon service.
Expand Down Expand Up @@ -198,7 +115,7 @@ suspend fun anchorToml(): TomlInfo {
```

```typescript
let resp = await anchor.getInfo();
let resp = await anchor.sep1();
```

</CodeExample>
Expand Down
4 changes: 2 additions & 2 deletions docs/building-apps/wallet/sep10.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ suspend fun getAuthToken(): AuthToken {
let authKey = Keypair.fromSecret("my secret key");

const getAuthToken = async (): Promise<AuthToken> => {
return anchor.auth().authenticate({ authKey });
return anchor.sep10().authenticate({ authKey });
};
```

Expand Down Expand Up @@ -122,7 +122,7 @@ const demoWalletSigner: WalletSigner = {
};

const getAuthToken = async () => {
return anchor.auth().authenticate({
return anchor.sep10().authenticate({
accountKp,
walletSigner: demoWalletSigner,
clientDomain: "https://demo-wallet-server.stellar.org/sign",
Expand Down
Loading