Latest 0.1.1
Homepage https://github.com/EOSIO/eosio-swift
License MIT Copyright (c) 2017-2019 block.one and its contributors. All rights reserved.
Platforms ios 11.0
Authors , , , , ,

Swift Logo

EOSIO SDK for Swift EOSIO Alpha

Software License
Swift 4.2
EosioSwift

EOSIO SDK for Swift is an API for integrating with EOSIO-based blockchains using the EOSIO RPC API.

To date, EOSIO SDK for Swift has only been tested on iOS. The goal, however, is for the core library to run anywhere Swift runs, adding other targets (macOS, watchOS, tvOS) as the library matures.

All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Contents

Installation

Prerequisites

  • Xcode 10 or higher
  • CocoaPods 1.5.3 or higher
  • For iOS, iOS 11+*

*Note: ABIEOS Serialization Provider requires iOS 12+ at the moment.

Instructions

To use EOSIO SDK for Swift in your app, add the following pods to your Podfile:

use_frameworks!

target "Your Target" do
  pod "EosioSwift", "~> 0.1.1" # pod for this library
  # Providers for EOSIO SDK for Swift
  pod "EosioSwiftAbieosSerializationProvider", "~> 0.1.1" # serialization provider
  pod "EosioSwiftSoftkeySignatureProvider", "~> 0.1.1" # experimental signature provider for development only
end

Then run pod install. And you’re all set for the Basic Usage example!

Basic Usage

Working With Transactions

Transactions are instantiated as an EosioTransaction and must then be configured with a number of providers prior to use. (See Provider Protocol Architecture below for more information about providers.)

import EosioSwift
import EosioSwiftAbieosSerializationProvider
import EosioSwiftSoftkeySignatureProvider

Then, inside a do...catch or throwing function, do the following:

let transaction = EosioTransaction()
transaction.rpcProvider = EosioRpcProvider(endpoint: URL(string: "http://localhost:8888")!)
transaction.serializationProvider = EosioAbieosSerializationProvider()
transaction.signatureProvider = try EosioSoftkeySignatureProvider(privateKeys: ["yourPrivateKey"])

/// Actions can now be added to the transaction, which can, in turn, be signed and broadcast:

let action = try EosioTransaction.Action(
    account: EosioName("eosio.token"),
    name: EosioName("transfer"),
    authorization: [EosioTransaction.Action.Authorization(
        actor: EosioName("useraaaaaaaa"),
        permission: EosioName("active"))
    ],
    data: Transfer(
        from: EosioName("useraaaaaaaa"),
        to: EosioName("useraaaaaaab"),
        quantity: "42.0000 SYS",
        memo: "")
)

transaction.add(action: action)

transaction.signAndBroadcast { (result) in
    switch result {
    case .failure (let error):
        // Handle error.
    case .success:
        // Handle success.
    }
}

The Transaction Factory

Alternatively, to avoid having to set the providers on every transaction, you can use the EosioTransactionFactory convenience class, as follows:

let rpcProvider = EosioRpcProvider(endpoint: URL(string: "http://localhost:8888")!)
let signatureProvider = try EosioSoftkeySignatureProvider(privateKeys: ["yourPrivateKey"])
let serializationProvider = EosioAbieosSerializationProvider()

let myTestnet = EosioTransactionFactory(rpcProvider: rpcProvider, signatureProvider: signatureProvider, serializationProvider: serializationProvider)

let transaction = myTestnet.newTransaction()
// add actions, sign and broadcast!

let anotherTransaction = myTestnet.newTransaction()
// add actions, sign and broadcast!
...

Usage With PromiseKit

Most EosioTransaction and RPC endpoint methods will return Promises if you ask them. Simply call the method with .promise as the first parameter and drop the callback. For example:

firstly {
    transaction.signAndBroadcast(.promise)
}.done { _ in
    // Handle success.
}.catch { error in
    // Handle error.
}

Key Management and Signing Utilities

Utilities for key generation and management and other signing functionality can be found in the EOSIO SDK for Swift: Vault library.

iOS Example App

If you’d like to see EOSIO SDK for Swift in action, check out our open source iOS Example App–a working application that fetches an account’s token balance and pushes a transfer action.

Documentation

Please refer to the generated code documentation at https://eosio.github.io/eosio-swift/ or by cloning this repo and opening the docs/index.html file in your browser.

Provider Protocol Architecture

The core EOSIO SDK for Swift library uses a provider-protocol-driven architecture to provide maximum flexibility in a variety of environments and use cases. EosioTransaction leverages those providers to prepare and process transactions. EOSIO SDK for Swift exposes four protocols. You, the developer, get to choose which conforming implementations to use.

Signature Provider Protocol

The Signature Provider abstraction is arguably the most useful of all of the providers. It is responsible for a) finding out what keys are available for signing and b) requesting and obtaining transaction signatures with a subset of the available keys.

By simply switching out the signature provider on a transaction, signature requests can be routed any number of ways. Need a signature from keys in the platform’s Keychain or Secure Enclave? Configure the EosioTransaction with the EOSIO SDK for Swift: Vault Signature Provider. Need signatures from a wallet on the user’s device? A signature provider can do that too!

EOSIO SDK for Swift does not include a signature provider implementation; one must be installed separately. All signature providers must conform to the EosioSignatureProviderProtocol.

  • Vault Signature Provider – Signature provider implementation for signing transactions using keys stored in Keychain or the device’s Secure Enclave.
  • Softkey Signature Provider – Example signature provider for signing transactions using K1 keys in memory. This signature provider stores keys in memory and is therefore not secure. It should only be used for development purposes. In production, we strongly recommend using a signature provider that interfaces with a secure vault, authenticator or wallet.

RPC Provider Protocol

The RPC Provider is responsible for all RPC calls to nodeos, as well as general network handling (Reachability, retry logic, etc.) While EOSIO SDK for Swift includes an RPC Provider implementation, it must still be set explicitly when creating an EosioTransaction, as it must be instantiated with an endpoint. (The default implementation suffices for most use cases.)

Serialization Provider Protocol

The Serialization Provider is responsible for ABI-driven transaction and action serialization and deserialization between JSON and binary data representations. These implementations often contain platform-sensitive C++ code and larger dependencies. For those reasons, EOSIO SDK for Swift does not include a serialization provider implementation; one must be installed separately.

ABI Provider Protocol

The ABI Provider is responsible for fetching and caching ABIs for use during serialization and deserialization. If none is explicitly set on the EosioTransaction, the default EosioAbiProvider will be used. (The default implementation suffices for most use cases.)

RPC: Using the Default RPC Provider

EOSIO Swift includes a default RPC Provider implementation (EosioRpcProvider) for communicating with EOSIO nodes using the EOSIO RPC API. Alternate RPC providers can be used assuming they conform to the minimal EosioRpcProviderProtocol. The core EOSIO SDK for Swift library depends only on the five RPC endpoints set forth in that Protocol. Other endpoints, however, are exposed in the default EosioRpcProvider.

Calls can be made to any of the available endpoints as follows:

rpcProvider.getInfo { (infoResponse) in
    switch infoResponse {
    case .failure(let error):
        // handle the error
    }
    case .success(let info) {
        // do stuff with the info!
        print(info.chainId)
    }
}

Attempts are made to marshall the responses into convenient Swift structs. More deeply nested response properties may be presented as a dictionary.

Each response struct will also contain a _rawResponse property. In the event the returned struct is missing a property you were expecting from the response, inspect the _rawResponse. You will likely find it there.

Response structs for the alpha release are incomplete. Some responses will only return the _rawResponse. We aim to continue improving response marshalling. And we invite you to help us improve responses too.

Want to help?

Interested in contributing? That’s awesome! Here are some Contribution Guidelines and the Code of Conduct.

We’re always looking for ways to improve EOSIO SDK for Swift. Check out our #enhancement Issues for ways you can pitch in.

License

MIT

Important

See LICENSE for copyright and license terms. Block.one makes its contribution on a voluntary basis as a member of the EOSIO community and is not responsible for ensuring the overall performance of the software or any related applications. We make no representation, warranty, guarantee or undertaking in respect of the software or any related documentation, whether expressed or implied, including but not limited to the warranties or merchantability, fitness for a particular purpose and noninfringement. In no event shall we be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or documentation or the use or other dealings in the software or documentation. Any test results or performance figures are indicative and will not reflect performance under all conditions. Any reference to any third party or third-party product, service or other resource is not an endorsement or recommendation by Block.one. We are not responsible, and disclaim any and all responsibility and liability, for your use of or reliance on any of these resources. Third-party resources may be updated, changed or terminated at any time, so the information here may be out of date or inaccurate.

Wallets and related components are complex software that require the highest levels of security. If incorrectly built or used, they may compromise users’ private keys and digital assets. Wallet applications and related components should undergo thorough security evaluations before being used. Only experienced developers should work with this software.

Latest podspec

{
    "name": "EosioSwift",
    "version": "0.1.1",
    "summary": "EOSIO SDK for Swift - API for integrating with EOSIO-based blockchains.",
    "homepage": "https://github.com/EOSIO/eosio-swift",
    "license": {
        "type": "MIT",
        "text": "                           Copyright (c) 2017-2019 block.one and its contributors.  All rights reserved.n"
    },
    "authors": {
        "Todd Bowden": "[email protected]",
        "Serguei Vinnitskii": "[email protected]",
        "Farid Rahmani": "[email protected]",
        "Brandon Fancher": "[email protected]",
        "Steve McCoole": "[email protected]",
        "Ben Martell": "[email protected]"
    },
    "source": {
        "git": "https://github.com/EOSIO/eosio-swift.git",
        "tag": "v0.1.1"
    },
    "swift_version": "4.2",
    "platforms": {
        "ios": "11.0"
    },
    "source_files": "EosioSwift/**/*.swift",
    "pod_target_xcconfig": {
        "CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES": "YES",
        "CLANG_ENABLE_MODULES": "YES",
        "SWIFT_COMPILATION_MODE": "wholemodule",
        "ENABLE_BITCODE": "YES"
    },
    "ios": {
        "dependencies": {
            "BigInt": [
                "~> 3.1"
            ],
            "PromiseKit": [
                "~> 6.8"
            ]
        }
    }
}

Pin It on Pinterest

Share This