Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
Ybrin committed Oct 1, 2020
1 parent 5262b22 commit a6272fe
Showing 1 changed file with 56 additions and 60 deletions.
116 changes: 56 additions & 60 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,6 @@
<a href="https://travis-ci.org/Boilertalk/Web3.swift">
<img src="http://img.shields.io/travis/Boilertalk/Web3.swift.svg?style=flat" alt="CI Status">
</a>
<a href="http://cocoapods.org/pods/Web3">
<img src="https://img.shields.io/cocoapods/v/Web3.svg?style=flat" alt="Version">
</a>
<a href="http://cocoapods.org/pods/Web3">
<img src="https://img.shields.io/cocoapods/l/Web3.svg?style=flat" alt="License">
</a>
<a href="http://cocoapods.org/pods/Web3">
<img src="https://img.shields.io/cocoapods/p/Web3.svg?style=flat" alt="Platform">
</a>
<a href="https://github.com/Carthage/Carthage">
<img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage compatible">
</a>
<a href="https://codecov.io/gh/Boilertalk/Web3.swift">
<img src="https://codecov.io/gh/Boilertalk/Web3.swift/branch/master/graph/badge.svg" alt="Code Coverage">
</a>
Expand All @@ -34,7 +22,7 @@ It allows you to connect to a [geth](https://github.com/ethereum/go-ethereum) or
Ethereum node (like [Infura](https://infura.io/)) to send transactions and read values from Smart Contracts without the need of
writing your own implementations of the protocols.

Web3.swift supports iOS, macOS, tvOS and watchOS with CocoaPods and Carthage and macOS and Linux with Swift Package Manager.
Web3.swift supports iOS, macOS, tvOS, watchOS and Linux with Swift Package Manager.

## Example

Expand All @@ -51,33 +39,31 @@ they just didn't work.

### :floppy_disk: Modularity

`Web3.swift` was built to be modular. If you install/use the basic `Web3` subspec/SPM product, you get access to the most basic
`Web3.swift` was built to be modular. If you install/use the basic `Web3` SPM product, you get access to the most basic
functions like transaction signing and interacting with an http rpc server.
If you want to add support for IPC rpc or something else, you can simple create a library which depends on `Web3` and implements
this exact functionality. More about that later.
If you want to use [PromiseKit](https://github.com/mxcl/PromiseKit) extensions for the web3 calls, you can either use the
provided PromiseKit subspec/SPM product or create your own.
If you want to conveniently parse JSON ABIs for Ethereum Smart Contracts, you can use the provided ABI Parsing subspec/SPM product.
provided PromiseKit SPM product or create your own.
If you want to conveniently parse JSON ABIs for Ethereum Smart Contracts, you can use the provided ABI Parsing SPM product.

Finally, if you want to add functionality to `Web3.swift` which is not provided yet, you don't have to wait until it gets merged
and released in a version bump. You can simple extend/update functionality within you own app as our APIs are made to be very open
for changes.
For example, if you want to add a web3 method which is not provided yet by `Web3.swift` (we will only support Infura supported methods),
you only have to add [some 3 lines of code](https://github.com/Boilertalk/Web3.swift/blob/master/Web3/Classes/Core/Web3/Web3.swift#L136)
you only have to add [some 3 lines of code](https://github.com/Boilertalk/Web3.swift/blob/master/Sources/Core/Web3/Web3.swift#L132)
(depending on the input and output parameters of the method). Adding IPC rpc support would be only implementing a protocol and answering
requests.

Like you can see, everything is possible with `Web3.swift`.

### :computer: Portability

One of the main reasons we started working on this project is because we wanted to use it with CocoaPods and Swift Package Manager on
One of the main reasons we started working on this project is because we wanted to use it with Swift Package Manager on
different platforms.
Because of that, `Web3.swift` is available through [CocoaPods](https://cocoapods.org/), [Carthage](https://github.com/Carthage/Carthage)
and [Swift Package Manager](https://swift.org/package-manager/) on iOS, macOS, tvOS, watchOS (with CocoaPods and Carthage)
and macOS and Linux (with SPM).
> Note: For SPM we are only testing macOS and officially supported Linux distributions
(currently Ubuntu 14.04 and 16.04) but it should be compatible with all little endian systems
Because of that, `Web3.swift` is available through [Swift Package Manager](https://swift.org/package-manager/) on iOS, macOS, tvOS, watchOS and Linux.
> Note: For SPM we are only testing iOS, macOS and officially supported Linux distributions
(currently Ubuntu 16.04 and 20.04) but it should be compatible with all little endian systems
which are able to compile the Swift Compiler, Foundation and Glibc.

### :zap: Speed and Efficiency
Expand All @@ -89,46 +75,13 @@ All our APIs are thread safe and designed to be used in highly concurrent applic

## Installation

### CocoaPods

Web3 is available through [CocoaPods](http://cocoapods.org). To install
it, simply add the following line to your `Podfile`:

```ruby
pod 'Web3'
```

If you want to use the [PromiseKit](https://github.com/mxcl/PromiseKit) extensions, also add the following line
to your `Podfile`:

```ruby
pod 'Web3/PromiseKit'
```

If you want to use the ContractABI module, which makes it easy to interact with smart contracts by calling
their functions and parsing their outputs automatically, also add the following line to your `Podfile`:

```ruby
pod 'Web3/ContractABI'
```

### Carthage

Web3 is compatible with [Carthage](https://github.com/Carthage/Carthage), a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. To install it, simply add the following line to your `Cartfile`:

```
github "Boilertalk/Web3.swift"
```

You will also have to install the dependencies, which can be found in our [Cartfile](Cartfile).

### Swift Package Manager

Web3 is compatible with Swift Package Manager v4 (Swift 4 and above). Simply add it to the dependencies in your `Package.swift`.
Web3 is compatible with Swift Package Manager v5 (Swift 5 and above). Simply add it to the dependencies in your `Package.swift`.

```Swift
dependencies: [
.package(url: "https://github.com/Boilertalk/Web3.swift.git", from: "0.4.0")
.package(url: "https://github.com/Boilertalk/Web3.swift.git", from: "0.5.0")
]
```

Expand All @@ -138,7 +91,12 @@ And then add it to your target dependencies:
targets: [
.target(
name: "MyProject",
dependencies: ["Web3", "Web3PromiseKit", "Web3ContractABI"]),
dependencies: [
.product(name: "Web3", package: "Web3"),
.product(name: "Web3PromiseKit", package: "Web3"),
.product(name: "Web3ContractABI", package: "Web3"),
]
),
.testTarget(
name: "MyProjectTests",
dependencies: ["MyProject"])
Expand All @@ -154,6 +112,44 @@ After the installation you can import `Web3` in your `.swift` files.
import Web3
```

### CocoaPods and Carthage

Because of an internal decision, we stopped supporting any Package Managers other than SPM starting with version 0.5.0.

To elaborate a little on this decision: With XCode 11 and Swift 5.1 we reached a point with Swift Package Manager where it
slowly started making other package managers irrelevant. You could already load all your dependencies in the XCode project
with Swift Package Manager.
With more updates it became even more prelevant. Cocoapods and Carthage maintainers lost interest into their project and
stopped maintaining it. There are many unresolved issues, many problems especially for library developers with Cocoapods.

So much hassle for no real gain. Users can already put dependencies which support SPM into their XCode project. So why bother?

The answer is simple. Some still use XCode < 11 and some library developers depend on Web3 in their own Pods/Carthages.

The decision was hard and took some time. But after seeing that the last version was very stable and used in many
production apps already, we decided to start with this move now.
XCode 10 is already more than 2 years old. Most projects already upgraded, the ones which didn't have a much bigger
problem than Web3.swift not making Updates for Cocoapods...
Library owners depending on Web3.swift are encouraged to drop Cocoapods and Carthage Support as well.

SPM is the Future. For all Cocoapods and Carthage Users who use it because many libraries did not switch to SPM yet:
You can still add Web3.swift as a SPM product into your `.xcworkspace` or `.xcodeproj` and keep all your other
dependencies inside Cocoapods/Carthage. But still. We encourage you to switch with as many dependencies as possible
to SPM. Better sooner than later. See the next section on how to do this.

### XCode

Using XCode 11 or later (for iOS, macOS or other Apple platforms) you can add SPM packages very easy.

In Xcode, select your project, from the Dropdown select the project, not a single Target, in the Tabs select `Swift Packages`.
Then you can click the + icon and put in the URL to this repository (https://github.com/Boilertalk/Web3.swift).
Now you can select all products and just click Next until the dependency was added.

That's it. If you push your changes even your CI will not make any problems. No hassles with outdated spec repositories,
no problems with some weird linker errors which only occur sometimes/with some dependencies.

If you need further guidance, join our [Telegram group](https://t.me/web3_swift) and we will help you. https://t.me/web3_swift

## Usage

### Interaction with an Ethereum node
Expand Down Expand Up @@ -299,7 +295,7 @@ or [the official Ethereum JSON RPC documentation](https://github.com/ethereum/wi

### Contract ABI interaction

We are providing an optional module for interaction with smart contracts. To use it you have to either add the corresponding subspec to your Podfile (for Cococapods) or you have to add `Web3ContractABI` to your target dependencies in your Podfile (for SPM). Make sure you check out the [installation instructions](#Installation) first.
We are providing an optional module for interaction with smart contracts. To use it you have to add `Web3ContractABI` to your target dependencies in your Podfile (for SPM). Make sure you check out the [installation instructions](#Installation) first.

We are providing two different options to create contract abi interfaces in Swift. Either you define your functions and events manually (or use one of our provided interfaces like [ERC20](Web3/Classes/ContractABI/Contract/ERC20.swift) or [ERC721](Web3/Classes/ContractABI/Contract/ERC721.swift)). Or you parse them from the JSON ABI representation just like in web3.js.

Expand Down

0 comments on commit a6272fe

Please sign in to comment.