argentlabs/web3.swift

Installation

Swift Package Manager

Use Xcode to add to the project (File -> Swift Packages) or add this to your Package.swift file:

.package(url: "https://github.com/argentlabs/web3.swift", from: "1.1.0")

CocoaPods

No longer supported. The last published pod is 1.6.0 from March 2023, and it stays installable, but it will not be updated — CocoaPods trunk stops accepting new podspecs in December 2026, and several of the pod's dependencies were frozen years earlier at versions well behind what this package uses. Please migrate to Swift Package Manager.

Usage

Getting Started

Create an instance of EthereumAccount with a EthereumKeyStorage provider. This provides a wrapper around your key for web3.swift to use. NOTE We recommend you implement your own KeyStorage provider, instead of relying on the provided EthereumKeyLocalStorage class. This is provided as an example for conformity to the EthereumSingleKeyStorageProtocol.

import web3

// This is just an example. EthereumKeyLocalStorage should not be used in production code
let keyStorage = EthereumKeyLocalStorage()
let account = try? EthereumAccount.create(replacing: keyStorage, keystorePassword: "MY_PASSWORD")

Create an instance of EthereumHttpClient or EthereumWebSocketClient. This will then provide you access to a set of functions for interacting with the Blockchain.

EthereumHttpClient

guard let clientUrl = URL(string: "https://an-infura-or-similar-url.com/123") else { return }
let client = EthereumHttpClient(url: clientUrl)

OR

EthereumWebSocketClient

guard let clientUrl = URL(string: "wss://sepolia.infura.io/ws/v3//123") else { return }
let client = EthereumWebSocketClient(url: clientUrl)

You can then interact with the client methods, such as to get the current gas price:

client.eth_gasPrice { (error, currentPrice) in
    print("The current gas price is \(currentPrice)")
}

If using async/await you can await on the result

let gasPrice = try await client.eth_gasPrice()

Smart contracts: Static types

Given a smart contract function ABI like ERC20 transfer:

function transfer(address recipient, uint256 amount) public returns (bool)

then you can define an ABIFunction with corresponding encodable Swift types like so:

public struct Transfer: ABIFunction {
    public static let name = "transfer"
    public let gasPrice: BigUInt? = nil
    public let gasLimit: BigUInt? = nil
    public var contract: EthereumAddress
    public let from: EthereumAddress?

    public let to: EthereumAddress
    public let value: BigUInt

    public init(contract: EthereumAddress,
                from: EthereumAddress? = nil,
                to: EthereumAddress,
                value: BigUInt) {
        self.contract = contract
        self.from = from
        self.to = to
        self.value = value
    }

    public func encode(to encoder: ABIFunctionEncoder) throws {
        try encoder.encode(to)
        try encoder.encode(value)
    }
}

This function can be used to generate contract call transactions to send with the client:

let function = transfer(contract: "0xtokenaddress", from: "0xfrom", to: "0xto", value: 100)
let transaction = try function.transaction()

client.eth_sendRawTransaction(transaction, withAccount: account) { (error, txHash) in
    print("TX Hash: \(txHash)")
}

If using async/await you can await on the result

let txHash = try await client.eth_sendRawTransaction(transaction, withAccount: account)

Generating ABI from a smart contract ABI file

Currently we don't support code generation as making it properly is a bigger project, and should possibly live outside of this repository.

You can try this project instead: imanrep/swiftabigen

Data types

The library provides some types and helpers to make interacting with web3 and Ethereum easier.

• EthereumAddress: For representation of addresses, including checksum support.
• BigInt and BigUInt: Using BigInt library
• EthereumBlock: Represents the block, either number of RPC-specific definitions like 'Earliest' or 'Latest'
• EthereumTransaction: Wraps a transaction. Encoders and decoders can work with it to generate proper data fields.

Conversion from and to Foundation types

All extensions are namespaced under ''.web3. So for example, to convert an Int to a hex string:

let gwei = 100
let hexgwei = gwei.web3.hexString

Supported conversions:

• Convert from hex byte string ("0xabc") to Data
• Convert from hex byte string ("0xabc") to Int
• Convert from hex byte string ("0xabc") to BigUInt
• Convert String, Int, BigUInt, Data to a hex byte string ("0xabc")
• Add or remove hex prefixes when working with String

ERC20

We support querying ERC20 token data via the ERC20 struct. Calls allow to:

• Get the token symbol, name, and decimals
• Get a token balance
• Retrieve Transfer events

ERC721

We support querying ERC721 token data via the ERC721 struct. Including:

• Get the token symbol, name, and decimals
• Get a token balance
• Retrieve Transfer events
• Decode standard JSON for NFT metadata. Please be aware some smart contracts are not 100% compliant with standard.

ZKSync Era

We also include additional helpers to interact with ZKSync Era, by importing web3_zksync.

Take a look at ZKSyncTransaction or use directly ZKSyncClient which has similar API as the EthereumClient

Running Tests

swift test works on a fresh clone with no setup. The tests hit public RPC endpoints and sign with a throwaway key that is committed in TestConfig.swift, so nothing has to be configured.

One test spends Ether and needs the funded account, whose key is a repository secret. It skips unless the key is present, which is the normal case locally and on pull requests from forks — GitHub never gives secrets to forks. If you do have the key:

export TESTS_PRIVATEKEY=0x...
swift test

While developing it is usually quicker to run only the tests you need, with swift test --filter.

Dependencies

We built web3.swift to be as lightweight as possible. However, given the cryptographic nature of Ethereum, there's a couple of reliable C libraries you will find packaged with this framework:

• keccac-tiny: An implementation of the FIPS-202-defined SHA-3 and SHAKE functions in 120 cloc (156 lines).
• Tiny AES: A small and portable implementation of the AES ECB, CTR and CBC encryption algorithms.

Package dependencies:

• BigInt
• GenericJSON
• secp256k1
• Vapor Websocket
• Apple Swift-log

Also for Linux build, we can't use Apple crypto APIs, so we embedded a small subset of CryptoSwift (instead of importing the whole library). Credit to Marcin Krzyżanowski

Contributors

The initial project was crafted by the team at Argent. However, we encourage anyone to help implement new features and to keep this library up-to-date. For features and fixes, simply submit a pull request to the develop branch. Please follow the contributing guidelines.

For bug reports and feature requests, please open an issue.

License

Released under the MIT license.