Skip to content

Commit

Permalink
update sep-006 support
Browse files Browse the repository at this point in the history
  • Loading branch information
@christian-rogobete
christian-rogobete committed Feb 28, 2024
1 parent 952762a commit 1ec8234
Show file tree
Hide file tree
Showing 28 changed files with 2,090 additions and 494 deletions.
107 changes: 4 additions & 103 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ To integrate stellar SDK into your Xcode project using CocoaPods, specify it in
use_frameworks!

target '<Your Target Name>' do
pod 'stellar-ios-mac-sdk', '~> 2.5.4'
pod 'stellar-ios-mac-sdk', '~> 2.5.5'
end
```

Expand All @@ -44,15 +44,15 @@ $ brew install carthage
To integrate stellar-ios-mac-sdk into your Xcode project using Carthage, specify it in your `Cartfile`:

```ogdl
github "soneso/stellar-ios-mac-sdk" ~> 2.5.4
github "soneso/stellar-ios-mac-sdk" ~> 2.5.5
```

Run `carthage update` to build the framework and drag the build `stellar-ios-mac-sdk.framework` into your Xcode project.

### Swift Package Manager

```swift
.package(name: "stellarsdk", url: "[email protected]:Soneso/stellar-ios-mac-sdk.git", from: "2.5.4"),
.package(name: "stellarsdk", url: "[email protected]:Soneso/stellar-ios-mac-sdk.git", from: "2.5.5"),
```

### Manual
Expand Down Expand Up @@ -421,106 +421,7 @@ federation.resolve(address: "bob*YOUR_DOMAIN") { (response) -> (Void) in

### 6. Anchor-Client interoperability

The Stellar Ecosystem Proposal [SEP-006](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md) defines the standard way for anchors and wallets to interact on behalf of users. This improves user experience by allowing wallets and other clients to interact with anchors directly without the user needing to leave the wallet to go to the anchor's site.

This protocol requires anchors to implement endpoints on their TRANSFER_SERVER. An anchor must define the location of their transfer server in their stellar.toml. This is how a wallet knows where to find the anchor's server.

Example: TRANSFER_SERVER="https://api.example.com"

#### 6.1 Get the TransferServerService for a domain

Get the TransferServerService for your domain:

```swift
TransferServerService.forDomain(domain: "https://YOUR_DOMAIN") { (response) -> (Void) in
switch response {
case .success(let transferServerService):
// use the transferServerService object to call other operations
case .failure(_):
// something went wrong
}
}
```

#### 6.2 Deposit external assets with an anchor

A deposit is when a user sends an external token (BTC via Bitcoin, USD via bank transfer, etc...) to an address held by an anchor. In turn, the anchor sends an equal amount of tokens on the Stellar network (minus fees) to the user's Stellar account.
The deposit endpoint allows a wallet to get deposit information from an anchor, so a user has all the information needed to initiate a deposit. It also lets the anchor specify additional information (if desired) that the user must submit via the /customer endpoint to be able to deposit.

```swift
let request = DepositRequest(assetCode: "BTC", account: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q")
transferServerService.deposit(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// deposit was sent with success
case .failure(_):
// something went wrong
}
}
```

#### 6.3 Withdraw assets from an anchor

This operation allows a user to redeem an asset currently on the Stellar network for the real asset (BTC, USD, stock, etc...) via the anchor of the Stellar asset.
The withdraw endpoint allows a wallet to get withdrawal information from an anchor, so a user has all the information needed to initiate a withdrawal. It also lets the anchor specify additional information (if desired) that the user must submit via the /customer endpoint to be able to withdraw.

```swift
let request = WithdrawRequest(type: "crypto", assetCode: "BTC", dest: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q")
transferServerService.withdraw(request: request) { (response) -> (Void) in
switch response {
case .success(let info):
// the withdraw operation completed successfully
case .failure(_):
// something went wrong
}
}
```

#### 6.4 Communicate deposit & withdrawal fee structure for an anchor to the user

Allows an anchor to communicate basic info about what their TRANSFER_SERVER supports to wallets and clients.

```swift
transferServerService.info { (response) -> (Void) in
switch response {
case .success(let info):
// info returned successfully
case .failure(_):
// something went wrong
}
}
```

#### 6.5 Using the transaction history endpoint

The transaction history endpoint helps anchors enable a better experience for users using an external wallet. With it, wallets can display the status of deposits and withdrawals while they process and a history of past transactions with the anchor. It's only for transactions that are deposits to or withdrawals from the anchor.

```swift
let request = AnchorTransactionsRequest(assetCode: "BTC", account: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q")
transferServerService.getTransactions(request: request) { (response) -> (Void) in
switch response {
case .success(let transactions):
// the past transactions returned successfully
case .failure(_):
// something went wrong
}
}
```

#### 6.7 Delete all KYC info about customer

Delete all personal information that the anchor has stored about a given customer. [account] is the Stellar account ID (G...) of the customer to delete. This request must be authenticated (via SEP-10) as coming from the owner of the account that will be deleted.

```swift
transferServerService.deleteCustomerInfo(account: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q") { (response) -> (Void) in
switch response {
case .success:
// all information for the given account was deleted successfully
case .failure(_):
// something went wrong
}
}
```
See [SDK's SEP-006 docs](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/docs/SEP-0006.md)

### 7. URI Scheme to facilitate delegated signing

Expand Down
207 changes: 207 additions & 0 deletions docs/SEP-0006.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@

### SEP-0006 - TransferServerService

Helps clients to interact with anchors in a standard way defined by [SEP-0006: Deposit and Withdrawal API](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md).



### Create a TransferServerService instance

**By providing the domain hosting the stellar.toml file**

```swift
TransferServerService.forDomain(domain: "https://YOUR_DOMAIN") { (response) -> (Void) in
switch response {
case .success(let service):
// use the service object to call operations
case .failure(_):
// something went wrong
}
}
```

This will automatically load and parse the stellar.toml file. It will then create the TransferServerService instance by using the transfer server url provided in the stellar.toml file.

**Or by providing the service url**

Alternatively one can create a TransferServerService instance by providing the transfer server url directly via the constructor:

```swift
let service = TransferServerService(
serviceAddress: "http://api.stellar-anchor.org/transfer"
)
```

### Info

This endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#info)) allows an anchor to communicate basic info about what their TRANSFER_SERVER supports to wallets and clients. With the ios sdk you can use the ```info``` method of your ```TransferServerService``` instance to get the info:

```swift
service.info { (response) -> (Void) in
switch response {
case .success(let info):
// success
case .failure(_):
// something went wrong
}
}
```


### Deposit

This endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#deposit)) is used when a user sends an external token (BTC via Bitcoin, USD via bank transfer, etc...) to an address held by an anchor. With the ios sdk you can use the ```deposit``` method of your ```TransferServerService``` instance to get the deposit information:

```swift
let request = DepositRequest(
assetCode: "USD",
account: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q",
jwt: jwtToken
)

service.deposit(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```

### Withdraw

This endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#withdraw)) is used when a user redeems an asset currently on the Stellar network for it's equivalent off-chain asset via the Anchor. For instance, a user redeeming their NGNT in exchange for fiat NGN. With the ios sdk you can use the ```withdraw``` method of your ```TransferServerService``` instance to get the withdrawal information:

```swift
let request = WithdrawRequest(
type: "bank_account",
assetCode: "NGNT",
jwt: jwtToken
)

service.withdraw(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```

### Deposit-Exchange

If the anchor supports SEP-38 quotes, it can provide a deposit that makes a bridge between non-equivalent tokens by receiving, for instance BRL via bank transfer and in return sending the equivalent value (minus fees) as USDC to the user's Stellar account.

The /deposit-exchange endpoint allows a wallet to get deposit information from an anchor when the user intends to make a conversion between non-equivalent tokens. With this endpoint, described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#deposit-exchange), a user has all the information needed to initiate a deposit and it also lets the anchor specify additional information (if desired) that the user must submit via SEP-12.

```swift
let request = DepositExchangeRequest(
destinationAsset: "USDC",
sourceAsset: "iso4217:BRA",
amount: "480",
account: "GDIODQRBHD32QZWTGOHO2MRZQY2TRG5KTI2NNTFYH2JDYZGMU3NJVAUI"
)

service.depositExchange(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```

### Withdraw-Exchange

If the anchor supports SEP-38 quotes, it can provide a withdraw that makes a bridge between non-equivalent tokens by receiving, for instance USDC from the Stellar network and in return sending the equivalent value (minus fees) as NGN to the user's bank account.

The /withdraw-exchange endpoint allows a wallet to get withdraw information from an anchor when the user intends to make a conversion between non-equivalent tokens. With this endpoint, a user has all the information needed to initiate a withdraw and it also lets the anchor specify additional information (if desired) that the user must submit via SEP-12.

```swift
let request = WithdrawExchangeRequest(
sourceAsset: "USDC",
destinationAsset: "iso4217:NGN",
amount: "700",
type: "bank_account"
)

service.withdrawExchange(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```

### Fee

This endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#fee)) allows an anchor to report the fee that would be charged for a given deposit or withdraw operation. With the ios sdk you can use the ```fee``` method of your ```TransferServerService``` instance to get the info if supported by the anchor:

```swift
let request = FeeRequest(
operation: "deposit",
assetCode: "NGN",
amount: 123.09
)

service.fee(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```


### Transaction History

From this endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#transaction-history)) wallets can receive the status of deposits and withdrawals while they process and a history of past transactions with the anchor. With the ios sdk you can use the ```getTransactions``` method of your ```TransferServerService``` instance to get the transactions:

```swift
let request = AnchorTransactionsRequest(
assetCode: "XLM",
account: "GCTTGO5ABSTHABXWL2FMHPZ2XFOZDXJYJN5CKFRKXMPAAWZW3Y3JZ3JK",
jwt: jwtToken)

service.getTransactions(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```


### Single Historical Transaction

This endpoint (described [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#single-historical-transaction)) enables clients to query/validate a specific transaction at an anchor. With the ios sdk you can use the ```getTransaction``` method of your ```TransferServerService``` instance to get the data:

```swift
let request = AnchorTransactionRequest(
id:"82fhs729f63dh0v4",
jwt: jwtToken
)

service.getTransaction(request: request) { (response) -> (Void) in
switch response {
case .success(let response):
// success
case .failure(_):
// something went wrong
}
}
```

### Further readings

For more info, see also the sdk's [SEP-0006 test cases](https://github.com/Soneso/stellar-ios-mac-sdk/blob/master/stellarsdk/stellarsdkTests/transfer_server_protocol/TransferServerTestCase.swift).

Loading

0 comments on commit 1ec8234

Please sign in to comment.