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

add TS examples for equivalent SDK methods #177

Merged
merged 9 commits into from
Jul 12, 2023
Merged
Show file tree
Hide file tree
Changes from 2 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
32 changes: 31 additions & 1 deletion docs/building-apps/wallet/intro.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ val wallet = Wallet(StellarConfiguration.Testnet)
```

```ts
const wallet = walletSdk.Wallet.TestNet();
let wallet = walletSdk.Wallet.TestNet();
```

</CodeExample>
Expand All @@ -47,6 +47,12 @@ The wallet instance can be further configured. For example, to connect to the pu
val walletMainnet = Wallet(StellarConfiguration(Network.PUBLIC, "https://horizon.stellar.org"))
```

```typescript
let wallet = new Wallet({
stellarConfiguration: StellarConfiguration.MainNet(),
});
```

</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.
Expand All @@ -60,6 +66,22 @@ val walletCustom = Wallet(
)
```

```typescript
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think all this code belongs to the "Configuring the Client" section

const customClient: AxiosInstance = axios.create({
baseURL: "https://some-url.com/api",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we even need to set baseUrl? I don't think it's good to show it in the example

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't necessarily, it's just an example of the params axios.create takes. I can rm

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Think it's better to remove it, cause in the SDK it doesn't make any sense to do so

timeout: 1000,
headers: { "X-Custom-Header": "foobar" },
});
let appConfig = new ApplicationConfiguration(
DefaultSigner,
customClient
);
let wal = new Wallet({
stellarConfiguration: StellarConfiguration.TestNet(),
applicationConfiguration: appConfig,
});
```

</CodeExample>

### Configuring the Client
Expand Down Expand Up @@ -151,6 +173,10 @@ Primary use of the SDK is to provide an easy way to connect to anchors via sets
val anchor = wallet.anchor("https://testanchor.stellar.org")
```

```typescript
let anchor = wallet.anchor({ homeDomain: "testanchor.stellar.org" });
```

</CodeExample>

And the most basic interaction of fetching a [SEP-1]: Stellar Info File:
Expand All @@ -163,6 +189,10 @@ suspend fun anchorToml(): TomlInfo {
}
```

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

</CodeExample>

The anchor class also supports [SEP-10]: Stellar Authentication and [SEP-24]: Hosted Deposit and Withdrawal features.
Expand Down
62 changes: 62 additions & 0 deletions docs/building-apps/wallet/sep10.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ First, let's create an `anchor` object to work with the anchor you are integrati
val anchor = wallet.anchor("https://testanchor.stellar.org")
```

```typescript
let anchor = wallet.anchor({ homeDomain: "https://testanchor.stellar.org" });
```

</CodeExample>

Next, authenticate with the `authKey` created earlier:
Expand All @@ -57,6 +61,14 @@ suspend fun getAuthToken(): AuthToken {
}
```

```typescript
let authKey = Keypair.fromSecret("my secret key");

const getAuthToken = async () => {
return anchor.auth().authenticate({ authKey });
}
```

</CodeExample>

For non-custodial wallets, you want to use the user's private key as an `authKey`.
Expand Down Expand Up @@ -95,6 +107,33 @@ suspend fun getAuthToken(): AuthToken {
}
```

```typescript
const demoWalletSigner: WalletSigner = {
signWithClientAccount: ({ transaction, accountKp }) => {
transaction.sign(accountKp);
return transaction;
},
signWithDomainAccount: async ({
transactionXDR,
networkPassphrase,
accountKp,
}) => {
return await axios.post("https://demo-wallet-server.stellar.org/sign", {
transactionXDR,
networkPassphrase,
});
},
};

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

</CodeExample>

:::danger
Expand All @@ -111,6 +150,29 @@ Let's add authentication with a bearer token. Simply update the request transfor
val signer = WalletSigner.DomainSigner("https://demo-wallet-server.stellar.org/sign") { bearerAuth("token") }
```

```typescript
const demoWalletSigner: WalletSigner = {
signWithClientAccount: ({ transaction, accountKp }) => {
transaction.sign(accountKp);
return transaction;
},
signWithDomainAccount: async ({
transactionXDR,
networkPassphrase,
accountKp,
}) => {
return await axios.post("https://demo-wallet-server.stellar.org/sign", {
transactionXDR,
networkPassphrase,
},
{
headers: { Authorization: `Bearer ${token}` }
}
);
},
};
```

</CodeExample>

Finally, with the approach above we define the signer and client domain per request. If you want to define it once and use it for every authentication call your application is making, you can do so via changing the configuration:
Expand Down
96 changes: 96 additions & 0 deletions docs/building-apps/wallet/sep24.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ Let's start with getting an instance of `Interactive` class, responsible for all
val sep24 = anchor.sep24()
```

```typescript
let sep24 = await anchor.getInfo();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

anchor.interactive() ?

```

</CodeExample>

First, let's get the information about the anchor's support for [SEP-24]. This request doesn't require authentication, and will return generic info, such as supported currencies, and features supported by the anchor. You can get a full list of returned fields in the [SEP-24 specification](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#info).
Expand All @@ -40,6 +44,12 @@ suspend fun getAnchorServices(): AnchorServiceInfo {
}
```

```typescript
const getAnchorServices = async (): Promise<AnchorServiceInfo> => {
anchor.getServicesInfo();
}
```

</CodeExample>

## Interactive Flows
Expand All @@ -54,6 +64,10 @@ To initiate an operation, we need to know an asset. You may want to hard-code it
val asset = info.currencies.first { it.code == "USDC" }.assetId
```

```typescript
const asset = info.currencies.find(({ code }) => code === "USDC").assetId;
```

</CodeExample>

:::info
Expand All @@ -74,6 +88,14 @@ Let's start with a basic deposit:
val deposit = sep24.deposit(asset, token)
```

```typescript
let deposit = await anchor.interactive().deposit({
accountAddress: accountKp.publicKey(),
assetCode,
authToken,
});
```

</CodeExample>

As a result, you will get an [interactive response](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#deposit-and-withdraw-shared-responses) from the anchor.
Expand All @@ -87,6 +109,11 @@ val url = deposit.url
val id = deposit.id
```

```typescript
let url = deposit.url;
let id = deposit.id;
```

</CodeExample>

Similarly to the deposit flow, a basic withdrawal flow has the same method signature and repose type:
Expand All @@ -99,6 +126,16 @@ val url = withdrawal.url
val id = withdrawal.id
```

```typescript
let withdrawal = await anchor.interactive().withdraw({
accountAddress: accountKp.publicKey(),
assetCode,
authToken,
});
let url = withdrawal.url;
let id = withdrawal.id;
```

</CodeExample>

### Providing KYC Info
Expand All @@ -125,6 +162,15 @@ val sep9 = mapOf("email_address" to "[email protected]")
val deposit = sep24.deposit(asset, token, sep9)
```

```typescript
let deposit = await anchor.interactive().deposit({
accountAddress: accountKp.publicKey(),
assetCode,
authToken,
extraFields: { email_address: "[email protected]" }
});
```

</CodeExample>

### Changing Stellar Transfer Account
Expand All @@ -143,6 +189,18 @@ suspend fun depositDifferentAccount(): InteractiveFlowResponse {
}
```

```typescript
const recipientAccount = "G...";
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add TODO here to modify code when memo is supported?

const depositDifferentAccount = async (): Promise<InteractiveFlowResponse> => {
return anchor.interactive().deposit({
accountAddress: accountKp.publicKey(),
assetCode,
authToken,
fundsAccountAddress: recipientAccount
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe fundsAccountAddress is the equivalent key for destinationAccount above, but lmk if I'm wrong

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think so. It should be optional, is it like this right now? (If not, making it optional is part of WAL-889 IIRC)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fundsAccountAddress is optional. It gets set to accountAddress if it isn't explicitly set and then sent to the /interactive endpoint as account

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. Small thing: for withdrawal it should be originAccount

});
}
```

</CodeExample>

Similarly, for a withdrawal, the origin account of the Stellar transaction could be changed:
Expand All @@ -154,6 +212,16 @@ val originAccount = "G..."
val withdrawal = sep24.withdraw(asset, token, withdrawalAccount = originAccount)
```

```typescript
const originAccount = "G..."
const withdrawal = await anchor.interactive().withdraw({
accountAddress: accountKp.publicKey(),
assetCode,
authToken,
fundsAccountAddress: recipientAccount
});
```

</CodeExample>

## Getting Transaction Info
Expand All @@ -173,6 +241,20 @@ val watcher = sep24.watcher()
val result = watcher.watchOneTransaction(token, "transaction id")
```


```typescript
let watcher = anchor.watcher();

let result = watcher.watchOneTransaction({
authToken,
assetCode,
Ifropc marked this conversation as resolved.
Show resolved Hide resolved
id: successfulTransaction.id,
onMessage,
onSuccess,
onError,
});
```

</CodeExample>

Alternatively, we can track multiple transactions for the same asset.
Expand Down Expand Up @@ -226,6 +308,13 @@ While `Watcher` class offers powerful tracking capabilities, sometimes it's requ
val transaction = sep24.getTransactionBy(token, id = "transaction id")
```

```typescript
const transaction = await anchor.getTransactionBy({
authToken,
id: transactionId,
});
```

</CodeExample>

It's also possible to fetch transaction by the asset
Expand All @@ -236,6 +325,13 @@ It's also possible to fetch transaction by the asset
val transactions = sep24.getTransactionsForAsset(asset, token)
```

```typescript
const transactions = await anchor.getHistory({
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

getHistory should be deprecated... It has some extra filtering logic that shouldn't be there.
getTransactionsForAsset is more flexible than getHistory

authToken,
assetCode,
});
```

</CodeExample>

[sep-9]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-000p.md
Expand Down
Loading