The Soneso open source stellar SDK for iOS & Mac provides APIs to build transactions and connect to Horizon.
.package(name: "stellarsdk", url: "[email protected]:Soneso/stellar-ios-mac-sdk.git", from: "3.0.1"),If not loading (err: cannot use bare repository), then remove:
[safe]
bareRepository = explicitfrom ~/.gitconfig. See also this SourceTree issue.
CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:
$ gem install cocoapodsTo integrate stellar SDK into your Xcode project using CocoaPods, specify it in your Podfile:
use_frameworks!
target '<Your Target Name>' do
pod 'stellar-ios-mac-sdk', '~> 3.0.1'
endThen, run the following command:
$ pod repo update
$ pod installCarthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthageTo integrate stellar-ios-mac-sdk into your Xcode project using Carthage, specify it in your Cartfile:
github "soneso/stellar-ios-mac-sdk" ~> 3.0.1
Run carthage update to build the framework and drag the build stellar-ios-mac-sdk.framework into your Xcode project.
Add the SDK project as a subproject, and having the SDK as a target dependencies. Here is a step by step that we recommend:
- Clone this repo (as a submodule or in a different directory, it's up to you);
- Drag
stellarsdk.xcodeprojas a subproject; - In your main
.xcodeprojfile, select the desired target(s); - Go to Build Phases, expand Target Dependencies, and add
stellarsdkfor iOS andstellarsdk-macOSfor OSX; - In Swift,
import stellarsdkand you are good to go!
// create a completely new and unique pair of keys.
let keyPair = try! KeyPair.generateRandomKeyPair()
print("Account Id: \(keyPair.accountId)")
// GCFXHS4GXL6BVUCXBWXGTITROWLVYXQKQLF4YH5O5JT3YZXCYPAFBJZB
print("Secret Seed: \(keyPair.secretSeed!)")
// SAV76USXIJOBMEQXPANUOQM6F5LIOTLPDIDVRJBFFE2MDJXG24TAPUU7The Stellar Ecosystem Proposal SEP-005 Key Derivation Methods for Stellar Accounts describes methods for key derivation for Stellar. This improves key storage and moving keys between wallets and apps.
Generate mnemonic
let mnemonic = WalletUtils.generate24WordMnemonic()
print("generated 24 words mnemonic: \(mnemonic)")
// bench hurt jump file august wise shallow faculty impulse spring exact slush thunder author capable act festival slice deposit sauce coconut afford frown betterGenerate key pairs
let keyPair0 = try! WalletUtils.createKeyPair(mnemonic: mnemonic, passphrase: nil, index: 0)
let keyPair1 = try! WalletUtils.createKeyPair(mnemonic: mnemonic, passphrase: nil, index: 1)
print("key pair 0 accountId: \(keyPair0.accountId)")
// key pair 0 accountId: GC3MMSXBWHL6CPOAVERSJITX7BH76YU252WGLUOM5CJX3E7UCYZBTPJQ
print("key pair 0 secretSeed: \(keyPair0.secretSeed!)")
// key pair 0 secretSeed: SAEWIVK3VLNEJ3WEJRZXQGDAS5NVG2BYSYDFRSH4GKVTS5RXNVED5AX7Generate key pairs with passphrase
let keyPair0 = try! WalletUtils.createKeyPair(mnemonic: mnemonic, passphrase: "p4ssphr4se", index: 0)
let keyPair1 = try! WalletUtils.createKeyPair(mnemonic: mnemonic, passphrase: "p4ssphr4se", index: 1)BIP and master key generation
let bip39Seed = Mnemonic.createSeed(mnemonic: mnemonic)
let masterPrivateKey = Ed25519Derivation(seed: bip39Seed)
let purpose = masterPrivateKey.derived(at: 44)
let coinType = purpose.derived(at: 148)
let account0 = coinType.derived(at: 0)
let keyPair0 = try! KeyPair.init(seed: Seed(bytes: account0.raw.bytes))
let account1 = coinType.derived(at: 1)
let keyPair1 = try! KeyPair.init(seed: Seed(bytes: account1.raw.bytes))After the key pair generation, you have already got the address, but it is not activated until someone transfers at least 1 lumen into it.
If you want to play in the Stellar test network, the sdk can ask Friendbot to create an account for you as shown below:
// To create a test account, sdk.accounts.createTestAccount will send Friendbot the public key you created
let responseEnum = await sdk.accounts.createTestAccount(accountId: keyPair.accountId)
switch responseEnum {
case .success(let details):
print(details)
case .failure(let error):
StellarSDKLog.printHorizonRequestErrorMessage(tag:"createTestAccount", horizonRequestError: error)
}See also: detailed code example
On the other hand, if you would like to create an account in the public net, you should buy some Stellar Lumens from an exchange. See Stellar's lumen buying guide. When you withdraw the Lumens into your new account, the exchange will automatically create the account for you. However, if you want to create an account from another account of your own, you may run the following code:
// build the operation
let createAccount = try CreateAccountOperation(sourceAccountId: nil,
destinationAccountId: destinationAccountId,
startBalance: 2.0)
// build the transaction
let transaction = try Transaction(sourceAccount: accountResponse,
operations: [createAccount],
memo: Memo.none)
// sign the transaction
try transaction.sign(keyPair: sourceAccountKeyPair, network: Network.testnet)
// submit the transaction
let responseEnum = await sdk.transactions.submitTransaction(transaction: transaction)
switch responseEnum {
case .success(let details):
//...
case .destinationRequiresMemo(destinationAccountId: let destinationAccountId):
print("destination account \(destinationAccountId) requires memo")
case .failure(error: let error):
StellarSDKLog.printHorizonRequestErrorMessage(tag:"submitTransaction", horizonRequestError: error)
}See also: detailed code example
After creating the account, we may check the basic information of the account.
let responseEnum = await sdk.accounts.getAccountDetails(accountId: keyPair.accountId)
switch responseEnum {
case .success(let accountDetails):
// You can check the `balance`, `sequence`, `flags`, `signers`, `data` etc.
for balance in accountDetails.balances {
switch balance.assetType {
case AssetTypeAsString.NATIVE:
print("balance: \(balance.balance) XLM")
default:
print("balance: \(balance.balance) \(balance.assetCode!) issuer: \(balance.assetIssuer!)")
}
}
print("sequence number: \(accountDetails.sequenceNumber)")
for signer in accountDetails.signers {
print("signer public key: \(signer.key)")
}
print("auth required: \(accountDetails.flags.authRequired)")
print("auth revocable: \(accountDetails.flags.authRevocable)")
for (key, value) in accountDetails.data {
print("data key: \(key) value: \(value.base64Decoded() ?? "")")
}
case .failure(let error):
StellarSDKLog.printHorizonRequestErrorMessage(tag:"account details", horizonRequestError: error)
}See also: detailed code example
You can check the most recent payments by:
let responseEnum = await sdk.payments.getPayments(order:Order.descending, limit:10)
switch responseEnum {
case .success(let page):
for payment in page.records {
if let nextPayment = payment as? PaymentOperationResponse {
if (nextPayment.assetType == AssetTypeAsString.NATIVE) {
print("received: \(nextPayment.amount) lumen" )
} else {
print("received: \(nextPayment.amount) \(nextPayment.assetCode!)" )
}
print("from: \(nextPayment.from)" )
}
else if let nextPayment = payment as? AccountCreatedOperationResponse {
//...
}
else if let nextPayment = payment as? PathPaymentStrictSendOperationResponse {
//...
}
// ...
}
case .failure(let error):
// ...
}See also: detailed code example
You can use the parameters:limit, order, and cursor to customize the query. You can also get most recent payments for accounts, ledgers and transactions.
For example get payments for account:
sdk.payments.getPayments(forAccount:keyPair.accountId, order:Order.descending, limit:10)See also: detailed code example
Horizon has SSE support for push data. You can use it like this:
first define your stream item somewhere to be able to hold the reference:
var streamItem:OperationsStreamItem? = nilthen create, assign and use it:
streamItem = sdk.payments.stream(for: .paymentsForAccount(account: destinationAccountId, cursor: nil))
streamItem.onReceive { (response) -> (Void) in
switch response {
case .open:
break
case .response(let id, let operationResponse):
if let paymentResponse = operationResponse as? PaymentOperationResponse {
switch paymentResponse.assetType {
case AssetTypeAsString.NATIVE:
print("Payment of \(paymentResponse.amount) XLM from \(paymentResponse.sourceAccount) received - id \(id)" )
default:
print("Payment of \(paymentResponse.amount) \(paymentResponse.assetCode!) from \(paymentResponse.sourceAccount) received - id \(id)" )
}
}
case .error(let err):
print(err?.localizedDescription ?? "Error")
}
}later you can close the stream item:
streamItem.close()See also: detailed code example
Just like payments, you can check assets, transactions, effects, offers, operations, ledgers etc. by:
sdk.assets.getAssets()
sdk.transactions.getTransactions()
sdk.effects.getEffects()
sdk.offers.getOffers()
sdk.operations.getOperations()
// add so on ...Example "send payment":
// create the payment operation
let paymentOperation = PaymentOperation(sourceAccountId: sourceAccountId,
destinationAccountId: destinationAccountId,
asset: Asset(type: AssetType.ASSET_TYPE_NATIVE)!,
amount: 1.5)
// create the transaction containing the payment operation
let transaction = try Transaction(sourceAccount: accountResponse,
operations: [paymentOperation],
memo: Memo.none)
// sign the transaction
try transaction.sign(keyPair: sourceAccountKeyPair, network: Network.testnet)
// submit the transaction
let responseEnum = await sdk.transactions.submitTransaction(transaction: transaction)
switch responseEnum {
case .success(let result):
// ...
default:
// ...
}See also: detailed code example
Get a transaction envelope from an XDR string:
let xdrString = "AAAAAJ/Ax+axve53/7sXfQY0fI6jzBeHEcPl0Vsg1C2tqyRbAAAAZAAAAAAAAAAAAAAAAQAAAABb2L/OAAAAAFvYwPoAAAAAAAAAAQAAAAEAAAAAo7FW8r8Nj+SMwPPeAoL4aUkLob7QU68+9Y8CAia5k78AAAAKAAAAN0NJcDhiSHdnU2hUR042ZDE3bjg1ZlFGRVBKdmNtNFhnSWhVVFBuUUF4cUtORVd4V3JYIGF1dGgAAAAAAQAAAEDh/7kQjZbcXypISjto5NtGLuaDGrfL/F08apZQYp38JNMNQ9p/e1Fy0z23WOg/Ic+e91+hgbdTude6+1+i0V41AAAAAAAAAAGtqyRbAAAAQNeY1rEwPynWnVXaaE/XWeuRnOHS/479J+Eu7s5OplSlF41xB7E8u9WzEItaOs167xuOVcLZUKBCBF1fnfzMEQg="
do {
let envelope = try TransactionEnvelopeXDR(xdr:xdrString)
let envelopeString = envelope.xdrEncoded
} catch {
print("Invalid xdr string")
}See also: detailed code example
Get a transaction object from an XDR string:
let xdrString = "AAAAAJ/Ax+axve53/7sXfQY0fI6jzBeHEcPl0Vsg1C2tqyRbAAAAZAAAAAAAAAAAAAAAAQAAAABb2L/OAAAAAFvYwPoAAAAAAAAAAQAAAAEAAAAAo7FW8r8Nj+SMwPPeAoL4aUkLob7QU68+9Y8CAia5k78AAAAKAAAAN0NJcDhiSHdnU2hUR042ZDE3bjg1ZlFGRVBKdmNtNFhnSWhVVFBuUUF4cUtORVd4V3JYIGF1dGgAAAAAAQAAAEDh/7kQjZbcXypISjto5NtGLuaDGrfL/F08apZQYp38JNMNQ9p/e1Fy0z23WOg/Ic+e91+hgbdTude6+1+i0V41AAAAAA=="
do {
// Get the transaction object
let transaction = try Transaction(xdr:xdrString)
// Convert your transaction back to xdr
let transactionString = transaction.xdrEncoded
} catch {
print("Invalid xdr string")
}The Stellar federation protocol defined in SEP-002 maps Stellar addresses to more information about a given user. It’s a way for Stellar client software to resolve email-like addresses such as:
name*yourdomain.com
into account IDs like:
GCCVPYFOHY7ZB7557JKENAX62LUAPLMGIWNZJAFV2MITK6T32V37KEJU
Stellar addresses provide an easy way for users to share payment details by using a syntax that interoperates across different domains and providers.
Get the federation of your domain:
let responseEnum = await Federation.forDomain(domain: domain, secure: secure)
switch responseEnum {
case .success(let federation):
//use the federation object to map your infos
case .failure(let error):
//something went wrong
}Resolve your addresses:
let federation = Federation(federationAddress: "https://YOUR_FEDERATION_SERVER")
let responseEnum = await federation.resolve(address: "bob*YOUR_DOMAIN")
switch responseEnum {
case .success(let federationResponse):
if let accountId = federationResponse.accountId {
// use the account id
} else {
// there is no account id corresponding to the given address
}
case .failure(_):
// something went wrong
}The Stellar Ecosystem Proposal SEP-007 introduces a URI Scheme that can be used to generate a URI that will serve as a request to sign a transaction. The URI (request) will typically be signed by the user’s trusted wallet where she stores her secret key(s).
Generate a URI that will serve as a request to sign a transaction. The URI (request) will typically be signed by the user’s trusted wallet where he stores his secret key(s).
// create the payment operation
let paymentOperation = try! PaymentOperation(sourceAccountId: sourceAccountId,
destinationAccountId: destinationAccountId,
asset: Asset(type: AssetType.ASSET_TYPE_NATIVE)!,
amount: 1.5)
// create the transaction containing the payment operation
let transaction = try! Transaction(sourceAccount: accountResponse,
operations: [paymentOperation],
memo: Memo.none)
// create the URIScheme object
let uriSchemeBuilder = URIScheme()
// get the URI with your transactionXDR
// more params can be added to the url, check method definition
let uriScheme = uriSchemeBuilder.getSignTransactionURI(transactionXDR: transaction.transactionXDR, callBack: "your_callback_api.com")
print (uriScheme);See also: detailed code example
Generate a URI that will serve as a request to pay a specific address with a specific asset, regardless of the source asset used by the payer.
let uriSchemeBuilder = URIScheme()
// more params can be added to the url, check method definition
let uriScheme = uriSchemeBuilder.getPayOperationURI(destination: "GAK7I2E6PVBFF27NU5MRY6UXGDWAJT4PF2AH46NUWLFJFFVLOZIEIO4Q", amount: 100, assetCode: "BTC", assetIssuer:"GC2PIUYXSD23UVLR5LZJPUMDREQ3VTM23XVMERNCHBRTRVFKWJUSRON5", callBack: "your_callback_api.com")
print (uriScheme);See also: detailed code example
Signs a transaction from a URI and sends it to the callback url if present or to the stellar network otherwise.
let responseEnum = await uriBuilder.signAndSubmitTransaction(forURL: uri, signerKeyPair: keyPair, transactionConfirmation: { (transaction) -> (Bool) in
// here the transaction from the uri can be checked and confirmed if the signing should continue
return false
})
switch responseEnum {
case .success:
// the transaction was successfully signed and sent
case .failure(error: let error):
// the transaction wasn't valid or it didn't pass the confirmation
}This SEP defines the standard way for clients such as wallets or exchanges to create authenticated web sessions on behalf of a user who holds a Stellar account. A wallet may want to authenticate with any web service which requires a Stellar account ownership verification, for example, to upload KYC information to an anchor in an authenticated way as described in SEP-6. Stellar Web Authentication is described in SEP-0010.
Authenticate with a server and get a JWT token.
let authEndpoint = "https://testanchor.stellar.org/auth"
let serverSigningKey = "GCUZ6YLL5RQBTYLTTQLPCM73C5XAIUGK2TIMWQH7HPSGWVS2KJ2F3CHS"
let serverHomeDomain = "testanchor.stellar.org"
let userAccountId = "GB4L7JUU5DENUXYH3ANTLVYQL66KQLDDJTN5SF7MWEDGWSGUA375V44V"
let userSeed = "SBAYNYLQFXVLVAHW4BXDQYNJLMDQMZ5NQDDOHVJD3PTBAUIJRNRK5LGX"
// Hold a strong reference to this to avoid being deallocated
let webAuth = WebAuthenticator(authEndpoint: authEndpoint, network: .testnet,
serverSigningKey: serverSigningKey, serverHomeDomain: serverHomeDomain)
let signers = [try! KeyPair(secretSeed: self.userSeed)]
let responseEnum = await webAuth.jwtToken(forUserAccount: userAccountId, signers: signers)
switch responseEnum {
case .success(let jwtToken):
print("JWT received: \(jwtToken)")
case .failure(let error):
// ...
}Creates the WebAuthenticator by loading the web auth endpoint and the server signing key from the stellar.toml file of the given domain.
let responseEnum = await WebAuthenticator.from(domain:"yourserverhomedomain.com", network: .testnet)
switch responseEnum {
case .success(let webAuth):
// use the web auth object
case .failure(let error):
//...
}The Web Authenticator can now be used to get the JWT token (see: 8.1)
Txrep: human-readable low-level representation of Stellar transactions is described in SEP-0011.
For more details have a look to our Txrep examples
Helps clients to interact with anchors in a standard way defined by SEP-0024: Hosted Deposit and Withdrawal.
See SEP-0024 SDK documentation
Enables an individual (e.g., a user or wallet) to regain access to a Stellar account as defined by SEP-0030: Account Recovery.
See SEP-0030: Account Recovery
You can find more documentation and examples in the docs folder.
Our SDK is used by the open source LOBSTR Vault. You can find the LOBSTR Vault source code here.
Our SDK is also used by the LOBSTR Wallet.
- SEP-0001 - Stellar Info File (Toml)
- SEP-0002 - Federation protocol
- SEP-0005 - Key Derivation Methods for Stellar Accounts
- SEP-0006 - Anchor/Client interoperability
- SEP-0007 - URI Scheme to facilitate delegated signing
- SEP-0008 - Regulated Assets
- SEP-0009 - Standard KYC / AML fields
- SEP-0010 - Stellar Web Authentication
- SEP-0011 - Txrep
- SEP-0012 - Anchor/Client customer info transfer
- SEP-0024 - Hosted Deposit and Withdrawal
- SEP-0030 - Account Recovery
- SEP-0038 - Anchor RFQ API
This SDK provides support for Soroban.
Please read our Contribution Guide.
Then please sign the Contributor License Agreement.
stellar-ios-mac-sdk is licensed under an Apache-2.0 license. See the LICENSE file for details.
Send lumens to: GANSYJ64BTHYFM6BAJEWXYLVSZVSHYZFPW4DIQDWJL5BOT6O6GUE7JM5