Adding Features to Indy-VDR

[wadeking98]

Indy-VDR Development for BC Wallet

indy-vdr is used to fetch objects from the configured ledgers such as schemas, cred defs, revocation registries, etc. The library is written in rust and has JS, Python, and Go wrappers.
This will focus on adding functionality to the JS wrappers in Node and React Native.

This tutorial is designed for intel linux systems building for android, it likely won't work for M1 macs.

This tutorial assumes you have cargo up and running and you're familiar with JS and Rust. Also make sure you've cloned the indy-vdr repo: https://github.com/hyperledger/indy-vdr.git

Adding Foreign Function Interfaces (FFIs)

This section will show you how to add new functions to indy-vdr and expose them to the JS wrappers using FFIs. The first thing you're going to need to do is to add your function entry point, go to libindy_vdr > src > ffi > mod.rs and add your wrapper function. Here's an example of the wrapper function created for transaction caching:

#[no_mangle]
pub extern "C" fn indy_vdr_set_ledger_txn_cache(
	capacity: i32,
	expire_offset: i64,
	path_opt: FfiStr,
) -> ErrorCode {
	catch_err! {
		debug!("Setting pool ledger transactions cache: capacity={}, expire_offset={}", capacity, expire_offset);
		let store = match path_opt.as_opt_str().unwrap_or_default() {
			"" => OrderedHashMap::new(new_mem_ordered_store()),
			path => OrderedHashMap::new(new_fs_ordered_store(path.into())?),
		};
	
		*write_lock!(LEDGER_CACHE_STRATEGY)? = Some(Arc::new(CacheStrategyTTL::new(capacity.try_into().ok().unwrap_or_default(), expire_offset.try_into().ok().unwrap_or_default(), Some(store), None)));
		
		Ok(ErrorCode::Success)
	}
}

FFIs don't work so well with unsigned ints so it's best to use signed ints instead. Also use FFiStr instead of normal rust strings. Now that your FFI has been created, it needs to be exposed to the javascript wrappers.
Go to libindy_vdr > include > libindy_vdr.h and add the a your function signature like so:

...
ErrorCode indy_vdr_set_ledger_txn_cache(int32_t capacity, int64_t expiry_offset_ms, FfiStr path);
...

Next go to wrappers > javascript > indy-vdr-nodejs > src > NodeJSIndyVdr.ts and add a signature like the following:

export class NodeJSIndyVdr implements IndyVdr {
...
	public setLedgerTxnCache(options: { capacity: number; expiry_offset_ms: number; path?: string }): void {
		const { capacity, expiry_offset_ms, path } = serializeArguments(options)
		this.handleError(this.nativeIndyVdr.indy_vdr_set_ledger_txn_cache(capacity, expiry_offset_ms, path))
	}
...
}

Next we're going to go to wrappers > javascript > indy-vdr-nodejs > src > library > bindings.ts and add a signature like so:

export const nativeBindings = {
...
indy_vdr_set_ledger_txn_cache: [FFI_ERROR_CODE, [FFI_INT64, FFI_INT64, FFI_STRING]],
...
}

In wrappers > javascript > indy-vdr-nodejs > src > library > NativeBindings.ts add a signature like this:

indy_vdr_set_ledger_txn_cache: (arg0: number, arg1: number, arg2?: string) => number

now we need to add a few mode cpp signatures. Go to wrappers > javascript > indy-vdr-react-native > cpp > indyVdr.cpp and add a section like this:

jsi::Value setLedgerTxnCache(jsi::Runtime &rt, jsi::Object options) {
	auto capacity = jsiToValue<size_t>(rt, options, "capacity");
	auto expiry_offset_ms = jsiToValue<c_ulong>(rt, options, "expiry_offset_ms");
	auto path = jsiToValue<std::string>(rt, options, "path", true);
	
	ErrorCode code = indy_vdr_set_ledger_txn_cache(capacity, expiry_offset_ms, path.length() > 0 ? path.c_str() : nullptr);
	
	return createReturnValue(rt, code, nullptr);
};

You'll also need a section in wrappers > javascript > indy-vdr-react-native > cpp > include > libindy_vdr.h like so:

ErrorCode indy_vdr_set_ledger_txn_cache(int32_t capacity, int64_t expiry_offset_ms, FfiStr path);

Now we need to made our exported function setLedgerTxnCache accessible. Go to wrappers > javascriopt > indy-vdr-react-native > cpp > HostObject.cpp and add a statement like so:

FunctionMap IndyVdrTurboModuleHostObject::functionMapping(jsi::Runtime &rt) {
	...
	fMap.insert(std::make_tuple("setLedgerTxnCache", &indyVdr::setLedgerTxnCache));
	...
}

Then go to wrappers > javascript > indy-vdr-react-native > cpp > indyVdr.h and add the following entry:

namespace indyVdr {
...
jsi::Value setLedgerTxnCache(jsi::Runtime &rt, jsi::Object options);
...
}

Next we need to add it to the React Native bindings, go to wrappers > javascript > indy-vdr-react-native > src > NativeBindings.ts

export interface NativeBindings {
	...
	setLedgerTxnCache(options: { capacity: number; expiry_offset_ms: number; path?: string }): ReturnObject<never>
	...
}

Then we need to go to wrappers > javascript > indy-vdr-react-native > src > ReactNativeIndyVdr.ts and add a function like so:

public setLedgerTxnCache(options: { capacity: number; expiry_offset_ms: number; path?: string }): void {
	const serializedOptions = serializeArguments(options)
	this.indyVdr.setLedgerTxnCache(serializedOptions)
}

Finally for wrappers > javascript > indy-vdr-shared > src > types > IndyVdr.ts add the following section:

export interface IndyVdr {
	setLedgerTxnCache(options: { capacity: number; expiry_offset_ms: number; path?: string }): void
}

now we're done adding FFIs to the JS wrappers, we can build the packages. Go to wrappers > javascript and run yarn install then run yarn build.

To test and apply your changes in BC Wallet you're going to have to run yarn patch @hyperledger/<PACKAGE_NAME> for each of indy-vdr-react-native and indy-vdr-shared paste the folders generated by the yarn build command into corresponding yarn patch folders and commit the patch. Now your function signatures are up to date, you just need to build and compile the binaries. At this point of the process your node_modules folders should look something like this:

Make sure the node modules are copied into the BC Wallet app/ folder as well as the project root.

Building the Binaries

The last part we need to complete is to build the rust binaries for all the android architectures. If you get lost it's a good idea to take a look at the build.yaml file in .github > workflows we're basically copying the android build steps.
Run the following command to install cross:
cargo install --bins --git https://github.com/rust-embedded/cross --locked --tag v0.2.4 cross

Next we're going to build each of the 4 binaries for android. Make sure you have docker installed and the daemon is running.

run the following command for the 4 architectures:

• aarch64-linux-android
• armv7-linux-androideabi
• i686-linux-android
• x86_64-linux-android

cross build --lib --release --target aarch64-linux-android --package indy-vdr

if you get an error like the following: ...bin/ld: cannot find -lunwind then you need to revert to using rust 1.67. Rust the following command to fix it

rustup default 1.67

Note the builds may take a long time.

After the build complete, each binary will be located at the following folders:
indy-vdr/target/<ARCHITECHTURE>/release/libindy_vdr.so
You'll place each of these .so files in the corresponding react-native-indy-vdr node_modules folder under native > mobile > android > <ARCHITECHTURE>

The architecture name used during the build stage is slightly different than the folder it goes into, here's a table that shows which folder each architecture goes into:

• aarch64-linux-android -> arm64-v8a
• armv7-linux-androideabi -> armeabi-v7a
• i686-linux-android -> x86
• x86_64-linux-android -> x86_64

By the end your indy-vdr-react-native node_modules folders should look like this:

Now you should be ready to start BC Wallet with your new rust features available