lnd/mobile/README.md

Building mobile libraries

Prerequisites

To build for iOS, you need to run macOS with either Command Line Tools or Xcode installed.

To build for Android, you need either Android Studio or Command Line Tools installed, which in turn must be used to install Android NDK.

Go and Go mobile

First, follow the instructions to install Go.

Then, install Go mobile and initialize it:

go install golang.org/x/mobile/cmd/gomobile@latest
go mod download golang.org/x/mobile
gomobile init

Docker

Install and run Docker.

Make

Check that make is available by running the following command without errors:

make --version

Building the libraries

Note that gomobile only supports building projects from $GOPATH at this point. However, with the introduction of Go modules, the source code files are no longer installed there by default.

To be able to do so, we must turn off module and using the now deprecated go get command before turning modules back on again.

go env -w GO111MODULE="off"
go get github.com/lightningnetwork/lnd
go get golang.org/x/mobile/bind
go env -w GO111MODULE="on"

Finally, let’s change directory to the newly created lnd folder inside $GOPATH:

cd $GOPATH/src/github.com/lightningnetwork/lnd

It is not recommended building from the master branch for mainnet. To checkout the latest tagged release of lnd, run

git checkout $(git describe --match "v[0-9]*" --abbrev=0)

iOS

make ios

The Xcode framework file will be found in mobile/build/ios/Lndmobile.xcframework.

Android

make android

The AAR library file will be found in mobile/build/android/Lndmobile.aar.

---

Tip: make mobile will build both iOS and Android libraries.

---

Generating proto definitions

In order to call the methods in the generated library, the serialized proto for the given RPC call must be provided. Similarly, the response will be a serialized proto.

iOS

In order to generate protobuf definitions for iOS, add --swift_out=. to the first protoc invocation found in gen_protos.sh .

Then, some changes to Dockerfile need to be done in order to use the Swift protobuf plugin with protoc:

1. Replace the base image with FROM swift:focal so that Swift can be used.
2. clang-format='1:7.0*' is unavailable in Ubuntu Focal. Change that to clang-format='1:10.0*'.
3. On the next line, install Go and set the environment variables by adding the following commands:

RUN apt-get install -y wget \
    && wget -c https://golang.org/dl/go1.17.6.linux-amd64.tar.gz -O - \
    | tar -xz -C /usr/local
ENV GOPATH=/go
ENV PATH=$PATH:/usr/local/go/bin:/go/bin

4. At the end of the file, just above CMD, add the following RUN command. This will download and compile the latest tagged release of Swift protobuf.

RUN git clone https://github.com/apple/swift-protobuf.git \
&& cd swift-protobuf \ 
&& git checkout $(git describe --tags --abbrev=0) \
&& swift build -c release \
&& mv .build/release/protoc-gen-swift /bin

Finally, run make rpc.

Tip: The generated Swift files will be found in various folders. If you’d like to move them to the same folder as the framework file, run

find . -name "*.swift" -print0 | xargs -0 -I {} mv {} mobile/build/ios

Lndmobile.xcframework and all Swift files should now be added to your Xcode project. You will also need to add Swift Protobuf to your project to support the generated code.

Android

First option:

In order to generate protobuf definitions for Android, add --java_out=.

to the first protoc invocation found in gen_protos.sh . Then, run make rpc.

Second option (preferable):

• You have to install the profobuf plugin to your Android application. Please, follow this link https://github.com/google/protobuf-gradle-plugin.
• Add this line to your app build.gradle file.

classpath "com.google.protobuf:protobuf-gradle-plugin:0.8.17"

• Create a proto folder under the main folder.

• Add aar file to libs folder.

• After that add these lines to your module's build.gradle file:

plugins {
    id "com.google.protobuf"
}

android {
    sourceSets {
        main {
            proto {

            }
        }
    }
}

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar"])
    implementation "com.google.protobuf:protobuf-javalite:${rootProject.ext.javalite_version}"
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:${rootProject.ext.protoc_version}"
    }
    generateProtoTasks {
        all().each { task ->
            task.builtins {
                java {
                    option "lite"
                }
            }
        }
    }
}

• Then, copy all the proto files from lnd/lnrpc to your proto folder, saving the structure.
• Build the project and wait until you see the generated Java proto files in the build folder.

---

Note:

If Android Studio tells you that the aar file cannot be included into the app-bundle, this is a workaround:

1. Create a separate gradle module
2. Remove everything from there and leave only aar and build.gradle.

3. Gradle file should contain only these lines:

configurations.maybeCreate("default")
artifacts.add("default", file('Lndmobile.aar'))

4. In dependencies add this line instead of depending on libs folder:

implementation project(":lndmobile", { "default" })

---

Calling the API

In LND v0.15+ all API methods have prefixed the generated methods with the subserver name. This is required to support subservers with name conflicts.

eg. QueryScores is now AutopilotQueryScores. GetBlockHeader is now NeutrinoKitGetBlockHeader.

API docs

• LND gRPC API Reference
• LND Builder’s Guide