DEV Community: Juan Sagasti

How to build a native iOS dApp that uses the Flow blockchain as the backend

Juan Sagasti — Thu, 07 Jul 2022 22:59:11 +0000

Introduction

This is the second and final part of a web3 tutorial about the Flow blockchain. Understanding the first part is essential and a pre-requisite because I explain there how to create and test Smart Contracts, the one we developed to create notes, its API, and how to write transactions and scripts to mutate and read data in the blockchain. Please take your time and make sure you understand it before continuing :)

First part: A notepad in the Flow blockchain

So, in this final part, you will learn:

How to deploy smart contracts in a Flow blockchain network: testnet.
How to build an iOS dApp that communicates with that contract in Flow's testnet. For user authentication, the app will use the Blocto Wallet, a cross-chain crypto wallet compatible with Flow. I assume you have a basic understanding of iOS programming. We will be using SwiftUI + Combine.

Deploying the Smart Contract

Note that the NotepadManager contract we will be using in the iOS dApp is already deployed in a flow account of my own. Remember that you can use any public smart contract in the blockchain, so you don't need to deploy the contract again in every account that wants to use it, as we learned in the previous article. This step is only for learning purposes in case you are interested in how to deploy contracts. You can skip this section and go directly to the dApp implementation part.

We are going to deploy the NotepadManager contract to the testnet, which is nearly identical to the mainnet, but we can operate without paying real gas. This is ideal for learning and testing our projects before deploying them to the production network (mainnet).

Install the Flow CLI
Generate the account keys. Remember to safely store the private key and don't share it with anyone.
Create a Testnet flow account here with your public key.
Create a folder for your contracts project, open it in the terminal, and do flow init. This will create a flow.json file with a default configuration.
Open your project folder in an editor. I'm using Visual Studio Code, which has an excellent Cadence plugin you can install from the Extensions Marketplace.
Add a new file to your project called NotepadManager.cdc. Paste the contract code we developed in the previous article. You can find it in the Playground, too.
Edit the flow.json file so it looks like this:

{
    "emulators": {},
    "contracts": {
        "NotepadManagerV1": "NotepadManagerV1.cdc"
    },
    "networks": {
        "emulator": "127.0.0.1:3569",
        "mainnet": "access.mainnet.nodes.onflow.org:9000",
        "testnet": "access.devnet.nodes.onflow.org:9000"
    },
    "accounts": {
        "my-testnet-account": {
            "address": "YOUR ACCOUNT ADDRESS (without the '0x' prefix)",
            "key": "YOUR PRIVATE KEY"
        }
    },
    "deployments": {
        "testnet": {
            "my-testnet-account": ["NotepadManagerV1"]
        }
    }
}

Note that we emptied the "emulators" field because we won't be using the local emulator but a real network. We also added the "contracts" and "deployments" fields to point to our contract and account.

Remember to fill the "address" and "key" fields, as specified. You obtained your account address in step #3 and the private key in step #2. Be careful with that key, and don't commit it to a public repository.

Now that everything is set up, it's time to deploy the contract! In the terminal, in your project folder, do:

flow project deploy

You'll see something like this:

  Deploying 1 contracts for accounts: my-testnet-account
  NotepadManagerV1 -> 0x9bde7238c9c39e97 (09d8818a9d41ae2fc92f9dd6d7355772e7d97e28fb9e20b2f66f473420a16b31)

Which can be read as:

NotepadManagerV1 -> the address containing it (the transaction ID)

You can see the transaction status or the account details through blockchain explorers like Tesnet Flowscan or Flow View Source. For example, if I introduce my account address 0x9bde7238c9c39e97 in Flowscan:

You can see the account balance, transaction history, and contracts deployed to the account. If you click the NotepadManagerV1 link, you can see the contract's code! This is powerful for public audits of the contracts in the blockchain.

Implementation

Our iOS dApp will have a pretty straightforward architecture:

All the elements in that picture are .swift files. You can start by creating an Xcode project (iOS 15.5 for the time being) and all those files. Files with the ...View suffix are SwiftUI views.

For communicating with the Flow blockchain, we will be using the iOS SDK that Outblock is building. A big update containing breaking changes is planned to be released soon, so we are going to lock now the SDK version to a particular commit (latest as of today) to be sure our code keeps working overtime. To do that, just add the dependency of the Swift Package Manager tied to the b4a9cfaaa0003f3f250490e6ccdf8b75065199a3 commit:

Now we can start adding code to our Swift files!

`FlowNotesApp.swift`

This is the entry point of our app. It's in charge of initializing the fcl-swift framework with the needed endpoints to communicate with the Flow blockchain and Blocto Wallet and showing the LoginView or the MyNotesView depending on the user's authorization state.

import Combine
import FCL
import SwiftUI

enum UI {
    static let flowGreen = Color(red: 0, green: 1, blue: 130/255)
}

@main
struct FlowNotesApp: App {
    @State private var currentUser: User?

    init() {
        // FCL configuration with the Tesnet Nodes URLs needed 
        // to stablish the connection with the blockchain and 
        // the Blocto Wallet:
        fcl.config(appName: "FlowNotes",
                   appIcon: "https://placekitten.com/g/200/200",
                   location: "https://foo.com",
                   walletNode: "https://fcl-discovery.onflow.org/testnet/authn",
                   accessNode: "https://access-testnet.onflow.org",
                   env: "testnet",
                   scope: "email",
                   authn: "https://flow-wallet-testnet.blocto.app/api/flow/authn")

        let flowGreenColor = UIColor(cgColor: UI.flowGreen.cgColor ?? UIColor.green.cgColor) // Color to UIColor conversion
        UINavigationBar.appearance().largeTitleTextAttributes = [.foregroundColor: flowGreenColor]
        UINavigationBar.appearance().titleTextAttributes = [.foregroundColor: flowGreenColor]
    }

    var body: some Scene {
        WindowGroup {
            VStack {
                if currentUser != nil {
                    MyNotesView(vm: MyNotesVM())
                } else {
                    LoginView()
                }
            }
            .preferredColorScheme(.dark)
            .onReceive(fcl.$currentUser) { user in
                currentUser = user
            }
        }
    }
}

`LoginView.swift`

Simple screen with a big login button that invokes the authenticate() method on the LoginVM ViewModel.

`LoginVM.swift`

The authenticate() method will invoke the FCL's authentication method, which will present us with the Blocto Wallet webView for the user to log in. After successful authentication, the FCL's currentUser property will be populated, triggering an update in our FlowNotesApp class, which is listening to that property. The MyNotesView will be shown then.

import Combine
import FCL
import Foundation

final class LoginVM: ObservableObject {

    private var cancellables = Set<AnyCancellable>()

    func authenticate() {
        fcl
            .authenticate()
            .receive(on: DispatchQueue.main)
            .sink { result in
                print(result)
            } receiveValue: { response in
                print(response)
            }
            .store(in: &cancellables)
    }
}

`MyNotesView.swift`

This view is in charge of showing the list of notes retrieved by MyNotesVM. The users can also:

Delete notes with the swipe-to-left gesture.
Present the NoteEditorView from the "+" button to create new notes.
Show the action menu from the "..." button. Here, users can manually refresh the list, delete the entire Notepad or sign out.

You will note that the transactions are pretty slow compared to a regular backend. This is because mutations of the blockchain need to be accepted and mined, which could take several seconds to happen. For simplicity, we present a full-screen loading screen while the VM's state is loading, until the transaction is sealed and a script can safely retrieve the final result. Read-only operations (scripts) like the notes fetch are blazing fast. If the transaction fails with an error, we present it to the user with an AlertView.

As you see, the transactions and script code used here are nearly identical to the ones in the first article (I omitted the comments in these to avoid repetition):

import SwiftUI

struct MyNotesView: View {

    @StateObject private var vm: MyNotesVM

    @State private var isLoading = false
    @State private var isShowingNoteEditor = false
    @State private var isShowingErrorAlert = false

    init(vm: MyNotesVM) {
        _vm = .init(wrappedValue: vm)
    }

    private var signOutButton: some View {
        Button {
            vm.signOut()
        } label: {
            Label("Sign Out", systemImage: "person.crop.circle.badge.xmark")
        }
    }

    private var refreshNotepadButton: some View {
        Button {
            vm.queryNotes()
        } label: {
            Label("Refresh notepad", systemImage: "arrow.clockwise")
        }
    }

    private var deleteNotepadButton: some View {
        Button {
            vm.deleteNotepad()
        } label: {
            Label("Delete notepad", systemImage: "trash")
        }
        .opacity(vm.notes != nil ? 1 : 0)
        .disabled(vm.notes == nil)
    }

    private var moreOptionsButton: some View {
        Menu {
            refreshNotepadButton
            Divider()
            deleteNotepadButton
            Divider()
            signOutButton
        } label: {
            Image(systemName: "ellipsis")
        }
    }

    private var addNoteButton: some View {
        Button {
            isShowingNoteEditor = true
        } label: {
            Image(systemName: "plus")
        }
    }

    var body: some View {
        ZStack {
            NavigationView {
                Group {
                    if let notes = vm.notes {
                        List {
                            ForEach(notes, id: \.id) { note in
                                NoteRow(note: note)
                                    .listRowBackground(Color.black)
                            }
                            .onDelete { index in
                                vm.deleteNote(atIndex: index.first)
                            }
                        }

                    } else if vm.state == .loading {
                        EmptyView()
                    } else {
                        Text("Your notepad is empty 🤓\nAdd a new note from\nthe'＋'button")
                            .multilineTextAlignment(.center)
                            .font(.headline)
                            .foregroundColor(.gray)
                    }
                }
                .navigationBarItems(leading: moreOptionsButton, trailing: addNoteButton)
                .navigationTitle("Flow Notes")
            }
            .tint(UI.flowGreen)

            ZStack {
                Color.black
                    .edgesIgnoringSafeArea(.all)
                    .opacity(isLoading ? 0.7 : 0)

                ProgressView {
                    Text("On it! 🚀 \nPlease wait...")
                        .multilineTextAlignment(.center)
                        .foregroundColor(.white)
                }
                .progressViewStyle(CircularProgressViewStyle(tint: .white))
                .opacity(isLoading ? 1 : 0)
            }
        }
        .onChange(of: vm.state) { newValue in
            isLoading = newValue == .loading
            isShowingErrorAlert = newValue.isFailed
        }
        .alert(isPresented: $isShowingErrorAlert, content: {
            Alert(title: Text("Error!"),
                  message: Text(vm.state.errorMessage ?? "Unknown"),
                  dismissButton: .default(Text("OK"), action: {
                vm.currentErrorDidDismiss()
            }))
        })
        .sheet(isPresented: $isShowingNoteEditor) {
            isShowingNoteEditor = false
        } content: {
            NoteEditorView().environmentObject(vm)
        }
    }
}

struct NoteRow: View {
    let note: Note

    var body: some View {
        HStack {
            VStack(alignment: .leading, spacing: 5) {
                Text(note.title)
                    .foregroundColor(.black)
                    .font(.body.weight(.bold))

                Text(note.body)
                    .foregroundColor(.black)
                    .font(.caption)
            }

            Spacer()
        }
        .padding()
        .background(UI.flowGreen)
        .cornerRadius(10)
    }
}

private struct PreviewWrapper: View {

    var vm = MyNotesVM()

    init() {
        vm.notes = [Note(id: 0, title: "This is a great note", body: "This is the body of a great note."),
                    Note(id: 1, title: "Another note", body: "The best body that was ever written.")]
    }

    var body: some View {
        MyNotesView(vm: vm).preferredColorScheme(.dark)
    }
}

struct MyNotesView_Previews: PreviewProvider {
    static var previews: some View {
        PreviewWrapper()
    }
}

`MyNotesVM`

This is the VM that defines the set of operations available to mutate the notepad through transactions or fetch the notes through a script.

Every time you send a transaction, the SDK will present a transaction confirmation screen (webView) from the Blocto Wallet, so you can review the transaction's code and approve it:


import Combine
import FCL
import Flow
import Foundation

enum LoadingState: Equatable {
    case idle
    case loading
    case didFail(error: String)

    var isFailed: Bool {
        guard case .didFail = self else { return false }
        return true
    }

    var errorMessage: String? {
        guard case let .didFail(error) = self else { return nil }
        return error
    }
}

final class MyNotesVM: ObservableObject {

    @Published private(set) var state = LoadingState.idle
    @Published var notes: [Note]?

    private let notepadManagerAddress = "0x9bde7238c9c39e97"
    private var cancellables = Set<AnyCancellable>()

    init() {
        defer {
            queryNotes()
        }
    }

    // MARK: - Public API

    func createNote(title: String, body: String) {
        guard fcl.currentUser?.addr != nil else { return }

        state = .loading

        fcl.mutate {
            cadence {
                // Transaction that checks if the Notepad 
                // exists (and creates it if needed) before 
                // creating and adding the note to it:
                 """
                 import NotepadManagerV1 from \(notepadManagerAddress)

                 transaction {
                     prepare(acct: AuthAccount) {
                         var notepad = acct.borrow<&NotepadManagerV1.Notepad>(from: /storage/NotepadV1)

                         if notepad == nil { 
                             // Create it and make it public
                             acct.save(<- NotepadManagerV1.createNotepad(), to: /storage/NotepadV1)
                             acct.link<&NotepadManagerV1.Notepad>(/public/PublicNotepadV1, target: /storage/NotepadV1)
                         }

                         var theNotepad = acct.borrow<&NotepadManagerV1.Notepad>(from: /storage/NotepadV1)
                         theNotepad?.addNote(title: "\(title)", body: "\(body)")
                     }
                 }
                 """
            }

            gasLimit {
                1000
            }
        }
        .receive(on: DispatchQueue.main)
        .sink { completion in
            if case let .failure(error) = completion {
                self.state = .didFail(error: error.localizedDescription)
            }
        } receiveValue: { [weak self] transactionId in
            guard let self = self else { return }

            self.waitForSealedTransaction(transactionId) {
                self.queryNotes()
            }
        }
        .store(in: &cancellables)
    }

    func deleteNote(atIndex index: Int?) {
        guard fcl.currentUser?.addr != nil, let index = index, let idToDelete = notes?[index].id else { return }

        state = .loading

        fcl.mutate {
            cadence {
                // Transaction that tries to delete the note 
                // if the Notepad exists:
                 """
                 import NotepadManagerV1 from \(notepadManagerAddress)

                 transaction {
                     prepare(acct: AuthAccount) {
                            let notepad = acct.borrow<&NotepadManagerV1.Notepad>(from: /storage/NotepadV1)
                            notepad?.deleteNote(noteID: \(idToDelete))
                     }
                 }
                 """
            }

            gasLimit {
                1000
            }
        }
        .receive(on: DispatchQueue.main)
        .sink { completion in
            if case let .failure(error) = completion {
                self.state = .didFail(error: error.localizedDescription)
            }
        } receiveValue: { [weak self] transactionId in
            guard let self = self else { return }

            self.waitForSealedTransaction(transactionId) {
                self.queryNotes()
            }
        }
        .store(in: &cancellables)
    }

    func deleteNotepad() {
        guard fcl.currentUser?.addr != nil else { return }

        state = .loading

        fcl.mutate {
            cadence {
                // Transaction that deletes the Notepad:
                 """
                 import NotepadManagerV1 from \(notepadManagerAddress)

                 transaction {
                     prepare(acct: AuthAccount) {
                         var notepad <- acct.load<@NotepadManagerV1.Notepad>(from: /storage/NotepadV1)!
                         NotepadManagerV1.deleteNotepad(notepad: <- notepad)
                     }
                 }
                 """
            }

            gasLimit {
                1000
            }
        }
        .receive(on: DispatchQueue.main)
        .sink { completion in
            if case let .failure(error) = completion {
                self.state = .didFail(error: error.localizedDescription)
            }
        } receiveValue: { [weak self] transactionId in
            guard let self = self else { return }

            self.waitForSealedTransaction(transactionId) {
                self.notes = nil
                self.state = .idle
            }
        }
        .store(in: &cancellables)
    }

    func queryNotes() {
        guard let currentUserAddress = fcl.currentUser?.addr else { return }

        state = .loading

        fcl.query {
            cadence {
                // Script that tries to get all notes from the 
                // current Notepad. It returns nil in case the 
                // Notepad doesn't exist yet publicly:
                """
                import NotepadManagerV1 from \(notepadManagerAddress)

                pub fun main(): [NotepadManagerV1.NoteDTO]? {
                    let notepadAccount = getAccount(0x\(currentUserAddress))

                    let notepadCapability = notepadAccount.getCapability<&NotepadManagerV1.Notepad>(/public/PublicNotepadV1)
                    let notepadReference = notepadCapability.borrow()

                    return notepadReference == nil ? nil : notepadReference?.allNotes()
                }
                """
            }
        }
        .receive(on: DispatchQueue.main)
        .sink { [weak self] completion in
            guard let self = self else { return }

            if case let .failure(error) = completion {
                self.state = .didFail(error: error.localizedDescription)
            }
        } receiveValue: { [weak self] result in
            print(result)

            guard let self = self else { return }
            guard let valuesArray = result.fields?.value.toOptional()?.value.toArray() else {
                self.notes = nil
                self.state = .idle
                return
            }

            let notes: [Note] = valuesArray.compactMap {
                guard let noteData = $0.value.toStruct()?.fields else { return nil }
                // It's not the best decoding code, but enough 
                // for what we are illustrating. The SDK 
                // maintainer is working on a better data 
                // decoder for future versions.
                let id = noteData[0].value.value.toUInt64()
                let title = noteData[1].value.value.toString()
                let body = noteData[2].value.value.toString()

                guard let id = id, let title = title, let body = body else { return nil }
                return Note(id: id, title: title, body: body)
            }

            self.notes = notes
            self.state = .idle
        }.store(in: &cancellables)
    }

    func currentErrorDidDismiss() {
        state = .idle
    }

    func signOut() {
        fcl.currentUser = nil
    }

    // MARK: - Private

    private func waitForSealedTransaction(_ transactionId: String, onSuccess: @escaping () -> Void) {
        // We are using a background thread because we don't 
        // want the .wait() to block the main event loop:
        DispatchQueue.global(qos: .userInitiated).async {
            do {
                // We want to wait for the transaction to be 
                // sealed (last transaction state) because we 
                // need the final result to be available in 
                // the blockchain. It's slower, but we don't 
                // want intermediate transaction states where 
                // you can still get empty errors or data when 
                // querying the blockchain with a Script.
                let result = try Flow.ID(hex: transactionId).onceSealed().wait()

                // And we update the state again in the main thread:
                DispatchQueue.main.async {
                    print(result)

                    if !result.errorMessage.isEmpty {
                        self.state = .didFail(error: result.errorMessage)
                    } else {
                        onSuccess()
                    }
                }
            } catch {
                DispatchQueue.main.async {
                    self.state = .didFail(error: error.localizedDescription)
                }
            }
        }
    }
}

`NoteEditorView.swift`

The NoteEditorView is just a form to compose and send a new note.

import SwiftUI

struct NoteEditorView: View {

    @EnvironmentObject private var vm: MyNotesVM
    @Environment(\.dismiss) private var dismiss

    @State private var noteTitle = ""
    @State private var noteBody = ""

    private var canSaveNote: Bool { !noteTitle.isEmpty && !noteBody.isEmpty}

    private var saveButton: some View {
        Button("Save") {
            vm.createNote(title: noteTitle, body: noteBody)
            dismiss()
        }
        .opacity(canSaveNote ? 1 : 0.5)
        .disabled(!canSaveNote)
    }

    var body: some View {
        NavigationView {
            VStack {
                VStack {
                    TextField("Title", text: $noteTitle)
                        .foregroundColor(.black)
                        .font(.body.weight(.bold))
                        .accentColor(.black)
                        .padding(.vertical, 7)

                    TextField("Body", text: $noteBody)
                        .foregroundColor(.black)
                        .accentColor(.black)
                        .padding(.vertical, 7)
                }
                .padding(.horizontal)
                .background(UI.flowGreen.opacity(0.5))
                .cornerRadius(10)

                Spacer()
            }
            .padding()
            .navigationTitle("New note")
            .navigationBarTitleDisplayMode(.inline)
            .navigationBarItems(trailing: saveButton)
        }
        .tint(UI.flowGreen)
    }
}

struct NoteEditor_Previews: PreviewProvider {
    static var previews: some View {
        NoteEditorView()
            .preferredColorScheme(.dark)
            .environmentObject(MyNotesVM())
    }
}

`Note.swift`

Just the Note model:

import Flow
import Foundation

struct Note {
    let id: UInt64
    let title: String
    let body: String
}

And that's it! I hope you find this helpful and that it inspires you to find more cool use cases. If you want to see a full demo video in action and check this project's source code, please refer to the FlowNotes repository.

There's an edit transaction use case in the NotepadManager contract that I haven't used in the app. I leave it to you as an exercise if you are motivated enough :)

Thank you for reading!

Web3 tutorial: A notepad in the Flow blockchain

Juan Sagasti — Tue, 28 Jun 2022 16:04:00 +0000

Introduction

While learning about web3 and blockchain technologies at The Agile Monkeys, we found out Flow. According to them, "Flow was designed for exceptional consumer and developer UX". And after playing with it for some time, I agree with that. Their developer UX is among the best, if not the best, we've tried. Some things that make Flow different are:

A greener web3 network. Flow starts with HotStuff, a proven Proof of Stake consensus mechanism, and adds a unique multi-node architecture to drive dramatic improvements in speed, throughput, and environmental friendliness without sharding or "layer two". This means Flow is the greenest web3 network among leading platforms.

Resource-oriented programming with Cadence, their own programming language. If you are familiar with Swift, Rust, or TypeScript, you will love Cadence and will be writing Smart Contracts in no time.
Playgrounds. An online editor to write and test your Smart Contracts without needing to deploy them to the main or test networks. You can focus first on the business logic. This is what we will be using in this tutorial.
Upgradeable Smart Contracts. Securely and transparently patch bugs and upgrade pre-specified parts of a smart contract.
No Sharding. On Flow, every application can be a platform. Smart contracts and user accounts on Flow can always interact with each other in one atomic, consistent, isolated, and durable (ACID) transaction. In other words: all applications on Flow can run in the same shared execution state. This ensures Flow apps benefit from great user experience and full composability, letting developers easily build on each other’s work. Sharding and layer 2 solutions break composability and reduce network effects for dApps and smart contracts by removing ACID guarantees from the execution environment.
Client libraries to help you build your dApps, Smart User Accounts, and more!

Implementation

First of all, why will we build a notepad on the blockchain? That makes no sense! I know paying gas fees for creating notes wouldn't be an ideal use case. But the Internet is already crowded with NFTs tutorials, and I wanted a more classic approach for non-web3 devs that illustrates how Smart Contracts + the user account in Flow can act as the API and the backend of our hypothetical dApp. And hopefully, this will give you more ideas about other possible dApps!

Cadence is a resource-oriented programming language. This means it makes it easy to work with digital assets (resources) as if they were physical assets. A resource can only be in one place at a time. So, for example, if you assign (this is, move with the <- operator) a resource to a new variable, the resource won't be available in the original variable anymore, and that variable will be invalid:

let movedResource <- originalResource

This makes the experience of working with digital assets pretty natural. A resource can't be left forgotten in a variable. It must live in your user account or should be destroyed at the end of the function you are currently executing. Otherwise, the compiler will complain about the resource loss. It's pretty safe in this regard.

I encourage you to read the quick Introduction to Cadence and the Cadence Language Reference before continuing this tutorial if you want to understand things better. Much of the language's syntax is inspired by Swift, Kotlin, and TypeScript, so you could feel at home if you are used to them.

Open a Flow Playground; you will see something like this:

You'll find the test accounts, the transactions, and the script folders in the left sidebar. Transactions are mutations of the blockchain and require gas fees. Scripts are read-only, blazing-fast operations that allow you to perform queries without paying gas fees. Anyway, we don't need to worry about transaction fees in this tutorial.

The user's account filesystem domain structure can be seen as this:

According to Flow docs:

The storage domain is where all objects (such as structs and resource objects representing tokens or NFTs) are stored. It is only directly accessible by the owner of the account.

The `private domain is like a private API. You can optionally create links to any of your stored assets here. Only the owner and anyone they give access to can use these interfaces to call functions defined in their stored assets.

The public domain is your account's public API. It is like the private domain in that the owner can link capabilities here that point to stored assets. The difference is that anyone in the network can access the public domain's functionality. A Transaction in Flow is defined as an arbitrary-sized block of Cadence code that is signed by one or more accounts.

Transactions have access to the /storage/ and /private/ domains of the accounts that signed the transaction. Transactions can also read and call functions in public contracts and access public domains in other users' accounts.

I wanted to deploy a public contract in one user address and let the other users use it without needing to deploy the contract to every account that wants to use it. So let's start by selecting the 0x01 user account in the sidebar, removing the example code, and pasting our contract code. The code includes comments so you can understand the reasoning behind every part as part of this tutorial:
`

// There are different access levels, as defined in 
// https://docs.onflow.org/cadence/language/access-control/#gatsby-focus-wrapper, 
// but we want our contract to be accessible from outside this 
// account, so we defined it as public (pub). 
pub contract NotepadManagerV1 {
    // This var is just for fun, to know how many Notepads 
    // this contract created.
    pub var numberOfNotepadsCreated: UInt64

    // The Notepad resource. It contains the notes as nested 
    // resources in the 'notes' dictionary. 
    // It also defines the Notepad API.
    pub resource Notepad {

        // Dictionary of notes. We will use the note.uuid 
        // (UInt64) as the indexing key:
        pub var notes: @{UInt64 : Note}

        init() {
            // When a Notepad is created, we initialize the 
            // 'notes' property with an empty dictionary:
            self.notes <- {}
        }

        // Every Resource needs a 'destroy' method.
        destroy() {
            // As we have nested resources, we need to destroy 
            // them here too:
            destroy self.notes
        }

        // Public method to add a note to the user's Notepad.
        pub fun addNote(title: String, body: String) {
            // Create a new note Resource and move it to the 
            // constant:
            let note <- create Note(title: title, body: body)

            // As we are using a dictionary of resources and 
            // we are adding a new note with the note.uuid as 
            // the indexing key, Cadence requires you to 
            // handle the note that could already be in that 
            // dictionary's position to avoid a Resource loss.
            // So we move what could already be in that 
            // position to the 'oldNote' constant and destroy 
            // it. In this case, that won't do anything
            // because 'oldNote' will be nil (we are adding a 
            // new note to that position with a new UUID). 
            // And we move the new note to the new position. 
            // This chained move (<-) operators instruction 
            // could be read as: "We move the new note to that 
            // position, and what was previously in that 
            // position to a constant, so we don't lose it":
            let oldNote <- self.notes[note.uuid] <- note
            destroy oldNote
        }

        // Public method to edit a note in the Notepad.
        pub fun editNote(noteID: UInt64, newTitle: String, newBody: String) {
            // We create and move a new note to the previous 
            // note position, and the old note to the 
            // 'oldNote' constant (and then destroy it):
            let oldNote <- self.notes.insert(key: noteID, <- create Note(title: newTitle, body: newBody))
            destroy oldNote
        }

        // Public method to delete a note from the Notepad.
        pub fun deleteNote(noteID: UInt64) {
            // Move the desired note out from the dictionary 
            // (to a constant) and destroy it: 
            let note <- self.notes.remove(key: noteID)
            destroy note
        }

        // Public function that, given a note resource id in 
        // the Notepad, returns a NoteDTO from it (see this 
        // DTO definition below). 
        // This will be useful for client queries (Scripts), 
        // which are read-only, and we cannot just return a 
        // Resource there. 
        pub fun note(noteID: UInt64): NoteDTO {
            // We take the note out of the notes dictionary, 
            // create a NoteDTO from it, put the note Resource 
            // back into the dictionary, and return the NoteDTO:
            var note <- self.notes.remove(key: noteID)!
            let noteDTO = NoteDTO(id: noteID, title: note.title, body: note.body)

            let oldNote <- self.notes[noteID] <- note
            destroy oldNote
            return noteDTO
        }

        // Public function that returns an array of NoteDTO 
        // (see this DTO definition below). This will be 
        // useful for client queries (Scripts), which are 
        // read-only, and we cannot just return a Resource. 
        pub fun allNotes(): [NoteDTO] {
            // We get a NoteDTO array from the note Resources 
            // in the Notepad. 
            var allNotes: [NoteDTO] = []
            for key in self.notes.keys {
                allNotes.append(self.note(noteID: key))
            }

            return allNotes
        }
    }

    // Note Resource definition. This is a nested Resource inside the Notepad Resource.
    pub resource Note {
        pub(set) var title: String
        pub(set) var body: String

        init(title: String, body: String) {
            self.title = title 
            self.body = body
        }
    }

    // Helper DTO (Data Transfer Object) that will be used 
    // when returning notes data to the clients from queries 
    // (Scripts). We cannot just return Resources there.
    pub struct NoteDTO {
        pub let id: UInt64
        pub let title: String
        pub let body: String

        init(id: UInt64, title: String, body: String) {
            self.id = id
            self.title = title 
            self.body = body
        }
    }

    init() {
        // Right after the contract is deployed, we initialize 
        // this var to keep the count of the Notepads that 
        // were created using this contract: 
        self.numberOfNotepadsCreated = 0
    }

    // Public method to create and return a Notepad Resource.
    pub fun createNotepad(): @Notepad {
        self.numberOfNotepadsCreated = self.numberOfNotepadsCreated + 1
        return <- create Notepad()
    }

    // Public method to destroy a Notepad resource from the 
    // user's Account.
    pub fun deleteNotepad(notepad: @Notepad) {
        self.numberOfNotepadsCreated = self.numberOfNotepadsCreated > 0 ? self.numberOfNotepadsCreated - 1 : 0
        destroy notepad
    }
}

Next, let's deploy the contract by tapping on the Deploy or Redeploy button at the top-right corner of the Playground:

Once the contract is deployed to the 0x01 account, you will see it in the sidebar:

Now it's time to test our contract using Transactions and Scripts. Let's start by adding a new transaction to the sidebar. This transaction will create the needed notepad and test the API by adding, editing, and deleting notes:

// Import the Smart Contract from the user account it was deployed to:
import NotepadManagerV1 from 0x01

transaction {

 // In the prepare function, we have access to the private 
 // space of the user's account who's signing the transaction:
    prepare(acct: AuthAccount) {
        // We try to borrow the notepad from the storage place 
        // where it is stored. Borrowing here means that we 
        // are creating a reference to the notepad without 
        // actually moving it to a var from its location:
        var notepad = acct.borrow<&NotepadManagerV1.Notepad>(from: /storage/Notepad)

        // If the result of that borrow is nil, that means we 
        // didn't store a notepad yet there, so we do it:
        if notepad == nil {
            // Create a notepad using our contract and move 
            // the returned resource to the /storage/Notepad 
            // path:
            acct.save(<- NotepadManagerV1.createNotepad(), to: /storage/Notepad)

            // Make the notepad public by creating a public 
            // link stored in /public/PublicNotepad. We are 
            // making it public because we need to expose it 
            // if we want to query and return that info from a 
            // Script later. These 'link' and 'borrow' 
            // functions are related to Capability-based 
            // Access Control, which is a pretty powerful 
            // feature that lets you expose a public API over 
            // the fields and functions of your stored assets 
            // to other users. If you want to dig down deeper 
            // on the topic, please refer to
            // https://docs.onflow.org/cadence/language/capability-based-access-control/:
            acct.link<&NotepadManagerV1.Notepad>(/public/PublicNotepad, target: /storage/Notepad)
            log("Notepad created!")
        }

        // We borrow the notepad (in this case we are sure we 
        // have created it because of the previous code):
        let theNotepad = acct.borrow<&NotepadManagerV1.Notepad>(from: /storage/Notepad)

        // Test note creation:
        theNotepad?.addNote(title: "First note title", body: "This is the body of the first note.")
        log("The first note was created and added to the notepad!")

        // Test another note creation:
        theNotepad?.addNote(title: "Second note title", body: "This is the body of the second note.")
        log("The second note was created and added to the notepad!")

        // Test note edition by editing the second note:
        theNotepad?.editNote(noteID: 2, newTitle: "Edited second note title", newBody: "EDITED: This is the body of the second note.")
        log("The second note was edited!")

        // Test note deletion by deleting the first note:
        theNotepad?.deleteNote(noteID: 1)
        log("The first note was deleted!")
    }

    execute {
        // We don't need to execute anything else for our 
        // testing. You can even delete this method. 
        log("Transaction executed!")
    }
}

To execute this transaction, tap on the Send button in the top-right corner of the Playground, but make sure you add the 0x02 account as the signer, so you test the transaction from a different account from where the contract is located (0x01):

After sending it, it will be executed, and you will see the logs in the Transaction Results console:

If you enable the Resources Explorer by tapping on the database icon next to the 0x02 account in the sidebar, you will see an empty storage panel above the Transaction Result console:

The notepad containing the notes should appear there. This is a recent bug in the Playground they haven't fixed yet. It was working in previous versions. But don't worry, we can check the content with a script.

So let's create a new script in the sidebar and paste this code:

import NotepadManagerV1 from 0x01

// A script is a special type of Cadence transaction
// that does not have access to any account's storage
// and cannot modify state. Any state changes that it would
// do are reverted after execution.
//
// Scripts must have the following signature: pub fun main()
// We can specify a return type, in this case we are returning 
// an array of NoteDTO:
pub fun main(): [NotepadManagerV1.NoteDTO]? {

    // Cadence code can get an account's public account object
    // by using the getAccount() built-in function.
    let notepadAccount = getAccount(0x02)

    // Get the public capability from the public path of the 
    // owner's account.
    // Remember that we made this public in the test 
    // transaction. 
    let notepadCapability = notepadAccount.getCapability<&NotepadManagerV1.Notepad>(/public/PublicNotepad)

    // Borrow a reference for the capability
    let notepadReference = notepadCapability.borrow()

    // If the notepad doesn't exist yet publicly, we return nil. 
    // Otherwise, we return all the notes in the form of an array of NoteDTO
    return notepadReference == nil ? nil : notepadReference?.allNotes()
}

Execute the script by tapping on the Execute button on the top-right side of the Playground, and you will see the result printed in the console. The notepad containing the edited note:

20:57:37 
Query notes 
Result
{"type":"Optional","value":{"type":"Array","value":[{"type":"Struct","value":{"id":"A.0000000000000001.NotepadManager.NoteDTO","fields":[{"name":"id","value":{"type":"UInt64","value":"2"}},{"name":"title","value":{"type":"String","value":"Edited second note title"}},{"name":"body","value":{"type":"String","value":"EDITED: This is the body of the second note."}}]}}]}}

Finally, if you want to easily reset all data stored in the Playground accounts, you can do it by redeploying the contract.

Link to the full Playground

That is enough for now! I hope you have enjoyed playing with Flow. In the next article, we'll learn to deploy the contract to the actual testnet, create a native iOS dApp that leverages all of this, and communicates directly with the Flow's network. Link to the second part:

How to build a native iOS dApp that uses the Flow Blockchain as the backend

Thanks for reading!

Continuous Integration and Deployment of an iOS app with Bitrise

Juan Sagasti — Fri, 05 Jun 2020 18:00:55 +0000

We are using Bitrise in our mobile projects at The Agile Monkeys to automate basic processes like validating that a Pull Request builds properly and the tests are passing (Continuous Integration) and to upload the .ipa to the App Store Connect so it can be be reviewed by Apple or by our testers through TestFlight (Continuous Deployment).

Continuous Integration & Deployment

If you haven't added an app to Bitrise yet, do it first. Remember to check the shared scheme toggle in your target scheme and push the change to your repo before adding the app to Bitrise:

Connect your Apple Developer account with Bitrise:

If you added your app to Bitrise with App Store configuration (you are asked about this when adding an app), you will have a default workflow like this one:

Remove the script step if you don't need it and rename the primary workflow to a more descriptive name, like Production.

Add steps to auto-increment the build number of your targets (2 in my case) and to deploy to iTunes Connect. I've also added a testing step:

Configure the Deploy to iTunes Connect step with your data:

Be sure you activate the app-store configuration in the Xcode Archive & Export for iOS step:

I wasn't able to make the code-signing step work in Bitrise when the Automatically manage signing toggle in the Xcode target settings was enabled. Uncheck it, create all your needed provisioning certificates manually (it's not the scope of this article) and configure your target with them. Remember to push your Xcode changes.

Go to the Code Signing tab in Bitrise (next to the Workflow one). Paste the script displayed there into your terminal and follow the instructions. Accept Bitrise to upload your certificates at the last step:

Next, create another Bitrise workflow for development. We don't need the build number or archiving phases here:

In Github, create branch protection rules for your development and master branches. This is the configuration I'm using:

As you can see, PRs can only be merged if they are up to date, approved by at least one team member, and Bitrise checks pass.

In the workflows editor, go to the triggers tab and add a Push trigger to the master branch pointing to the Production workflow:

This way, whenever a PR is merged into the master branch, the Production workflow will be triggered, building the app with the app-store configuration and uploading it to the App Store Connect. Remember that you need to increase your target versions and the new app version record must exist too in the portal before merging the PR:

Now add Pull Request triggers to the development and master branches with the development workflow configuration, so when a PR is created in Github, the development workflow will be triggered, blocking the merge if it encounters problems along the way:

And that's it!

I must say that this is the first time I use Bitrise for CI/CD, and I'm pretty satisfied with the result. Feel free to leave a comment if any part is misleading or you think that more details are needed.

Thanks for reading!

How to have Debug and Release Firebase environments in an iOS project

Juan Sagasti — Thu, 14 May 2020 16:18:36 +0000

We should be using a debug environment when developing unreleased features to the public so we don't affect the environment where your real users are (avoids risks), plus we don't clutter it with testing data.

This is kind of obvious nowadays. But let's see how to do it with a Firebase project in Xcode.

Create your Development and Production projects in Firebase and download both GoogleService-info.plist.
Add a Firebase directory in your project, with Development and Release subfolders. Add the plist of each environment to its respective folder, but unchecking the add to the target option because we are going to add the correct file to it during the build phase.
Add a new build script phase. If you have a Crashlytics script, add it before it. I've called it Firebase script selection:
Add this code to the script you have added:

INFO_PLIST=GoogleService-Info.plist

DEVELOPMENT_INFO_PLIST=${PROJECT_DIR}/${TARGET_NAME}/Firebase/Development/${INFO_PLIST}
RELEASE_INFO_PLIST=${PROJECT_DIR}/${TARGET_NAME}/Firebase/Release/${INFO_PLIST}

echo "Checking ${INFO_PLIST} in ${DEVELOPMENT_INFO_PLIST}"
if [ ! -f $DEVELOPMENT_INFO_PLIST ] ; then
    echo "Development GoogleService-Info.plist not found."
    exit 1
fi

echo "Checking ${INFO_PLIST} in ${RELEASE_INFO_PLIST}"
if [ ! -f $RELEASE_INFO_PLIST ] ; then
    echo "Release GoogleService-Info.plist not found."
    exit 1
fi

PLIST_DESTINATION=${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app
echo "Copying ${INFO_PLIST} to final destination: ${PLIST_DESTINATION}"

if [ "${CONFIGURATION}" == "Release" ] ; then
    echo "Copied ${RELEASE_INFO_PLIST}."
    cp "${RELEASE_INFO_PLIST}" "${PLIST_DESTINATION}"
else
    echo "Copied ${DEVELOPMENT_INFO_PLIST}."
    cp "${DEVELOPMENT_INFO_PLIST}" "${PLIST_DESTINATION}"
fi

And that's it! Now you will be using the development environment when developing/testing your app and the release one when archiving the project.

If you want to test your release environment when developing too, you can just create a new compilation scheme for that:

Don't stick to the (initial) plan

Juan Sagasti — Mon, 13 Apr 2020 13:23:48 +0000

The perfect set of initial ideas doesn’t exist. Everything needs to evolve and adapt to the environment. It’s always been that way: the only sure thing is that there’s no sure thing. In the same sense that a slow adaptation to the environment significantly reduces an organism's survival rate, an initial set of ideas mortgages the potential and the future of a project.

When we work on a new project, we start from an initial set of ideas that are, by default, prejudiced. Our prejudices model a system without taking enough variables into account. We start from a reductionist vision, far from reality, that lacks environment adaptation (t0).

In projects where the main objective is to add value (which is most of them), it’s the feedback that gives us the information needed to trigger adaptations to the environment. Cognitive empathy (being able to take the perspective of all types of users in our target audience) and being able to test rapidly are the engines that drive the feedback. They serve to model a new and more precise (and merciless) environment where the initial sets of ideas will fight to survive. Ideas will try to naturally evolve to keep up with the new environment. Sometimes, they will even mutate to unrecognizable forms. Don't try to stop it—enjoy the process. Ideas will come back to you, changed. And they will appear while you’re taking a shower; doing the dishes; in the middle of the night; when you are trying to explain them to others; while reading a book that’s totally unrelated...

That is the clearest indication that your project is alive and healthy, in the sense that it is resilient to environmental updates. And that means that everything will be fine even when it won't, because you had the best possible ideas given the situation you were working in. You might even find that your project doesn't make sense anymore, which is fine too.

In essence, don't just stick to the initial plan.

Bonus:
I found a perfect example of what I've tried to transmit here while reading the book "Zelda: Detrás de la Leyenda". Those who know me are aware without a doubt that I’m fascinated by Nintendo and its company philosophy. They are responsible for the oldest and most iconic videogame sagas in history, like "The Legend of Zelda" and "Super Mario." They achieved what no one else in the industry did: creating two sagas with more than 30 years of history, which are still examples of the highest quality in each console’s generation. They reinvent themselves with each title and seem to be immune to signs of wear and the conventions of the industry. This is because, in spite of the general objective being very well defined from the start (prioritize playability over everything else), the way they get there is based on experimentation and the constant search for what fun means.

It is fascinating to see the evolution of Nintendo in this respect through their games. This book describes how the directors of "Zelda II: The Adventure of Link” (1987), assessing the reasons for the title’s poor reception compared to its predecessor, admitted that the main reason is that the initial set of ideas barely evolved from the time of their conception. This is something they don't usually allow to happen. But this time, they stuck to the initial ideas just for the sake of doing it, which caused forced situations and a loss in quality that directly affected how the title was received by users.

Another fascinating company on this topic is Apple. One of their core values is to subjugate every idea to the most merciless environments and a holistic pressure on every aspect of a product (even those not perceived by users). The result is the creation of technological diamonds in every generation, which guide the innovation of the whole industry. Steve Jobs's official biography is full of history and good examples of this way of thinking and acting. A totally recommended read or listen.

How to add or renew an Apple Push Notification Certificate

Juan Sagasti — Thu, 12 Mar 2020 13:25:08 +0000

Apple Certificates are a necessary evil, we know that. Although Apple has simplified the process of dealing with them over the years, it's still a bit of a pain. And, since it's something we do from year to year when they expire and not on a daily basis, it's something really easy to forget.

I've written this guide for myself and The Agile Monkeys 🐒 but I'm sure you will benefit from it, too!

You will probably need a .p12 file to configure your Push Notification Server or third-party service. Let's see how to do it:

Go to https://developer.apple.com/, under Certificates, add a new one selecting a new service certificate of type Apple Push Notification service SSL (Sandbox & Production):

Continue and select the Bundle Identifier of your app or the identifier of the Push Extension of your app in case you have it:

Next, you need a Certificate Signing Request. You can get it from your Keychain Access app following these steps.
Upload the Certificate Signing Request you just saved to your disk:

Continue and download the Apple Certificate.
Double click on it to install it in your Keychain Access. You will see it with a little arrow at the left side (this will contain the private key):

Select it in your Keychain Access app, right-click on it and Export. A prompt will appear. Select .p12 as the format if that wasn't selected by default already.
Et voilá! Upload that file to your server or third-party service.

Setting up a code formatter in an iOS project

Juan Sagasti — Tue, 10 Mar 2020 18:36:38 +0000

People come and go, but projects stay. Having a uniform and idiomatic codebase is nicer, eases the onboarding of new developers and lets them to entirely focus on what matters the most while writing code or reviewing others.

There are really good Swift code formatters out there, like SwiftFormat and swift-format. We are using SwiftFormat at The Agile Monkeys. This is how we configure it for an iOS project as a pre-commit hook.

Wait! But why adding it as a pre-commit hook?

Because we don't want this to run entirely on every local build (if the formatter was added as a build phase), but once we are going to commit new code. Besides, we want the formatter to interfere with our editor undo history the less as possible. The downside of the pre-commit approach is that every developer on the project would need to add the pre-commit hook file manually (once).

The ideal thing is to have this integrated into the CI process with Danger and let it commit the formatted changes for you in each Pull Request. This is how you can do it, for example, with Bitrise + Danger: https://blog.bitrise.io/danger-danger-uh-that-is-using-danger-with-bitrise

But if you don't want to pay for any extra seats in your Github account or you don't want anything else in the pipeline to be changing files on behalf of the developers, the pre-commit hook is nice too.

Let's see how to do it!

First, you need to install the command-line tool:

brew install swiftformat
brew upgrade swiftformat

Next, add the pre-commit hook:

Edit or create a .git/hooks/pre-commit file in your project folder. The .git folder is hidden but should already exist if you are using Git in your project. Open it with the terminal or the Finder's Go > Go to Folder... menu.
Add the following code in the pre-commit file:

git diff --diff-filter=d --staged --name-only | grep -e '\(.*\).swift$' | while read line; do
  swiftformat "${line}";
  git add "$line";
done

Enable the hook:

chmod +x .git/hooks/pre-commit

The pre-commit hook will now run whenever you run git commit. Running git commit --no-verify will skip it.

Note: GUI git clients do not know your environment/shell. I'm using Tower as my GUI git client so I needed to add this line at the top of the pre-commit file:

PATH="$PATH:/usr/local/bin"

To get default set of formatting rules (which are pretty good and idiomatic) you don't need to do anything else. In case you want to adapt it to your needs, you can create and add rules to a .swiftformat file in your project path. You can find the rules reference in: https://github.com/nicklockwood/SwiftFormat/blob/master/Rules.md

Finally, perform the first full project formatting:

swiftformat .

Enjoy the homogeneity!