-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Cleanup legacy code and update cordova docs (#219)
* mark ffi delete functions as unsafe * remove wallet rindex module since it's unused and basically obsolete * remove legacy unused utxo functionality * rebuild genesis binary before generating json for cordova * ignore exist status when deleting the plugins before installing Helps in the case the script was interrupted after deleting the plugin but before installing the new version. If there is an error it would most probably show up in the following install. * cordova test: rebuild genesis json info before installing * remove utxo keys from keys.json * use python3 binary in test script * remove utxo keys argument from cordova * remove unused outdated electron/browser cordova platform * remove outdated getting_started.md file * update cordova readme * add updated genesis test vector * add cbindgen to the cordova requirements * join the cordova docs in a single readme * regen wallet.h * do not require jcli in the ci integration test build since the tests don't run, there is not much point in regenerating the assets, and not installing jcli could save some time.
- Loading branch information
1 parent
432a891
commit f1cd62a
Showing
52 changed files
with
334 additions
and
3,349 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,91 +1,119 @@ | ||
| # Usage | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Wallet conversion | ||
|
|
||
| Minimal wallet conversion example in plain javascript | ||
|
|
||
| ``` js | ||
| const mnemonics = 'neck bulb teach illegal soul cry monitor claw amount boring provide village rival draft stone'; | ||
| const BLOCK0 = hexStringToBytes('0052000000000369000000000000000000000000fd8b6f5c9d824dbaffe3c10435db4c3522323a238fcbd17457569e89dd6dfcd4000000000000000000000000000000000000000000000000000000000000000000a60000000e0088000000005e922c7000410100c200010398000000000000000a000000000000000200000000000000640104000000b401411404040000a8c00208000000000000006402440001900001840000006405810104c800005af3107a40000521020000000000000064000000000000000d0000000000000013000000010000000302e0e57ceb3b2832f07e2ef051e772b62a837f7a486c35e38f51bf556bd3abcd8eca016f00010500000000000f4240004c82d818584283581c0992e6e3970dd01055ba919cff5b670a6813f41c588eb701231e3cf0a101581e581c4bff51e6e1bcf245c7bcb610415fad427c2d8b87faca8452215970f6001a660a147700000000000186a0004c82d818584283581c3657ed91ad2f25ad3ebc4faec404779f8dafafc03fa181743c76aa61a101581e581cd7c99cfa13e81ca55d026fe0395124646e39b188c475fb276525975d001ab75977f20000000000002710002b82d818582183581cadff678b11b127aef0c296e88bfb4769c905284716c23e5d63278787a0001a63f679c70000000000000001004c82d818584283581c4baebf60011d051b02143a3417514fed6f25c8c03d2253025aa2ed5fa101581e581c4bff51e6e1bcf245c7bcb5104c7ca9ed201e1b1a6c6dfbe93eadeece001a318972700000000000000064002b82d818582183581cadff678b11b127aef0c296e88bfb4769c905284716c23e5d63278787a0001a63f679c7014e00010500000000000f4240002b82d818582183581c783fd3008d0d8fb4532885481360cb6e97dc7801c8843f300ed69a56a0001a7d83a21d0000000000002710002b82d818582183581cadff678b11b127aef0c296e88bfb4769c905284716c23e5d63278787a0001a63f679c70000000000000001002b82d818582183581c783fd3008d0d8fb4532885481360cb6e97dc7801c8843f300ed69a56a0001a7d83a21d0000000000000064004c82d818584283581cffd85f20cf3f289fd091e0b033285ecad725496bc57035a504b84a10a101581e581c4bff51e6e1bcf245c7bcb4105299a598c50eabacdd0f72815c016da7001a57f9068f00000000000003f2004c82d818584283581c847329097386f263121520fc9c364047b436298b37c9148a15efddb4a101581e581cd7c99cfa13e81ce17f4221e0aed54c08625a0a8c687d9748f462a6b2001af866b8b9'); | ||
|
|
||
| function hexStringToBytes(string) { | ||
| const bytes = []; | ||
| for (let c = 0; c < string.length; c += 2) { | ||
| bytes.push(parseInt(string.substr(c, 2), 16)); | ||
| } | ||
| return Uint8Array.from(bytes); | ||
| } | ||
|
|
||
| document.addEventListener('deviceready', onDeviceReady, false) | ||
|
|
||
| function onDeviceReady() { | ||
| var lib = cordova.require('wallet-cordova-plugin.wallet'); | ||
| // or | ||
| // var wallet = window.wallet; | ||
|
|
||
| function handleError(error) { | ||
| console.error('error: ' + error); | ||
| } | ||
|
|
||
| function getTransactionsFromConversion(conversion) { | ||
| lib.conversionTransactionsSize(conversion, function(size) { | ||
| const transactions = []; | ||
| for (var i = 0; i < size; i++) { | ||
| lib.conversionTransactionsGet(conversion, i, function(tx) { | ||
| transactions.push(tx); | ||
|
|
||
| if (transactions.length == size) { | ||
| // do something with the transactions, for example, POST to jormungandr | ||
| console.log(transactions); | ||
| } | ||
| }, handleError) | ||
| } | ||
| }, handleError) | ||
| } | ||
|
|
||
| lib.walletRestore(mnemonics, function(wallet) { | ||
| lib.walletRetrieveFunds(wallet, BLOCK0, function(settings) { | ||
| lib.walletTotalFunds(wallet, function(retrievedFunds) { | ||
| console.log('retrieved: ' + retrievedFunds + ' funds from block0'); | ||
| lib.walletConvert(wallet, settings, getTransactionsFromConversion, handleError) | ||
| }, handleError); | ||
| }, handleError) | ||
| }, handleError); | ||
| } | ||
| # Getting started | ||
|
|
||
| The javascript documentation for this module can be generated with jsdoc by | ||
| running: | ||
|
|
||
| ```bash | ||
| npm install | ||
| npm run doc | ||
| ``` | ||
|
|
||
| The generated files can be found at the `doc` directory, and can be read by | ||
| opening `index.html` with a web browser. | ||
|
|
||
| At the moment the best source for examples are the javascript | ||
| [tests](tests/src/main.js). | ||
|
|
||
| # Development | ||
|
|
||
| ## Getting started | ||
|
|
||
| The [official cordova | ||
| documentation](https://cordova.apache.org/docs/en/11.x/guide/hybrid/plugins/index.html) | ||
| is the best place to start. | ||
|
|
||
| ## Requirements | ||
|
|
||
| ### General | ||
|
|
||
| As a baseline, Node.js and the cordova cli are required. Since the process of | ||
| running the tests involves creating an application. The documentation at | ||
| [installing-the-cordova-cli](https://cordova.apache.org/docs/en/11.x/guide/cli/index.html#installing-the-cordova-cli) | ||
| can be used as a guide. Check out also the [Android | ||
| documentation](https://cordova.apache.org/docs/en/11.x/guide/platforms/android/index.html) | ||
| and the [iOS | ||
| documentation](https://cordova.apache.org/docs/en/11.x/guide/platforms/ios/plugin.html) | ||
| for requirements specific to the platform you are going to be developing for. | ||
|
|
||
| Additionally, python3 is required to run the helper scripts. | ||
|
|
||
|
|
||
| `jcli` is required to generate the genesis file that it is used in | ||
| the test-vectors, installation instructions can be found in the [jormungandr's | ||
| repository](https://github.com/input-output-hk/jormungandr). It's recommended | ||
| that the `jcli` version is built with the same version of `chain-libs` that is | ||
| used to build the plugin (which can be found in the Cargo.lock file), although | ||
| it's not strictly necessary as long as the genesis binary encoding is | ||
| compatible. | ||
|
|
||
| ### Android | ||
|
|
||
| - [cross](https://github.com/cross-rs/cross) is currently used for building the | ||
| native libraries for Android. | ||
| - [uniffi-bindgen](https://github.com/mozilla/uniffi-rs). The version must be the same one that is used in the `wallet-uniffi` crate. This can be found [here](../wallet-uniffi/Cargo.toml). | ||
|
|
||
|
|
||
| ### iOS | ||
|
|
||
| The ios rust platforms: | ||
|
|
||
| - `rustup target add x86_64-apple-ios` | ||
| - `rustup target add aarch64-apple-ios` | ||
|
|
||
| [cbindgen](https://github.com/eqrion/cbindgen) is necessary for regenerating the | ||
| C header, which is then used from the [Objetive C code](src/ios/WalletPlugin.m) in this package. Since the | ||
| latest version is in source control, this is only needed if the core API | ||
| changes. The [regen_header.sh](../bindings/wallet-c/regen_header.sh) script can | ||
| be used to do this. | ||
|
|
||
| ## Overview | ||
|
|
||
| The core of the plugin is written in rust, and ffi is used to bridge that to | ||
| either Objective-C or Kotlin, depending on the platform. | ||
|
|
||
| The [wallet.js](www/wallet.js) file has the top level Javascript api for the | ||
| plugin users, which is mostly a one-to-one mapping to the API of the | ||
| wallet-core rust crate. | ||
|
|
||
| The iOS part of the plugin is backed by the [wallet-c](../wallet-c/wallet.h) | ||
| package, while the Android support is provided via the | ||
| [wallet-uniffi](../wallet-uniffi/src/lib.udl) package. Both are also thin | ||
| wrappers over **wallet-core**. | ||
|
|
||
| ## Build | ||
|
|
||
| [build_jni.py](scripts/build_jni.py) in the `scripts` directory will compile the | ||
| Android native libraries, generate the Kotlin bindings, and copy those to this | ||
| package in the `src/android` directory. | ||
|
|
||
| [build_ios.py](scripts/build_ios.py) in the `scripts` directory will compile the | ||
| iOS native libraries, and copy those along the C header to this package. | ||
|
|
||
| `npm pack` can be used to make a distributable version of the plugin as an npm | ||
| package. | ||
|
|
||
| ## Running the tests | ||
|
|
||
| The *tests* directory contains a Cordova plugin with [js | ||
| tests](tests/src/main.js), we use | ||
| [cordova-plugin-test-framework](https://github.com/apache/cordova-plugin-test-framework) | ||
| as a test harness. | ||
|
|
||
| The [test.py](scripts/test.py) script can be used to build | ||
| the plugin and setup the test harness. For example, the following command will | ||
|
|
||
| - create a cordova application at the `~/cdvtest/hello` directory. The cdvtest directory must not exist, as the script will not overwrite it. | ||
| - install the cordova-plugin-test-framework. | ||
| - build the native libraries for the android platform, and copy those to | ||
| src/android/libs. | ||
| - build the wallet-uniffi kotlin bindings for the native library. | ||
| - install the plugin at this directory. | ||
| - install the plugin in the tests directory. | ||
| - run the test application if there is an emulator or device available. | ||
|
|
||
| ```bash | ||
| python3 test.py --platform android -d ~/cdvtest --cargo-build --run android full | ||
| ``` | ||
|
|
||
| ## Electron quirks | ||
|
|
||
| At the moment, the plugin requires that node integrations are enabled in the app. | ||
|
|
||
|
|
||
| # Implemented API's per platform | ||
|
|
||
| | | Android | Ios | Electron/browser | | ||
| | ---------------------------- | ------- | --- | ---------------- | | ||
| | CONVERSION_DELETE | ✓ | ✓ | ✓ | | ||
| | CONVERSION_IGNORED | ✓ | ✓ | ✓ | | ||
| | CONVERSION_TRANSACTIONS_GET | ✓ | ✓ | ✓ | | ||
| | CONVERSION_TRANSACTIONS_SIZE | ✓ | ✓ | ✓ | | ||
| | PENDING_TRANSACTIONS_DELETE | ✓ | | ✓ | | ||
| | PENDING_TRANSACTIONS_GET | ✓ | | ✓ | | ||
| | PENDING_TRANSACTIONS_SIZE | ✓ | | ✓ | | ||
| | PROPOSAL_DELETE | ✓ | ✓ | ✓ | | ||
| | PROPOSAL_NEW | ✓ | ✓ | ✓ | | ||
| | PROPOSAL_NEW_PRIVATE | ✓ | ✓ | ✓ | | ||
| | PROPOSAL_NEW_PUBLIC | ✓ | ✓ | ✓ | | ||
| | SETTINGS_DELETE | ✓ | ✓ | ✓ | | ||
| | SYMMETRIC_CIPHER_DECRYPT | ✓ | ✓ | ✓ | | ||
| | WALLET_CONFIRM_TRANSACTION | ✓ | | ✓ | | ||
| | WALLET_CONVERT | ✓ | ✓ | ✓ | | ||
| | WALLET_DELETE | ✓ | ✓ | ✓ | | ||
| | WALLET_ID | ✓ | ✓ | ✓ | | ||
| | WALLET_IMPORT_KEYS | ✓ | ✓ | ✓ | | ||
| | WALLET_PENDING_TRANSACTIONS | ✓ | | ✓ | | ||
| | WALLET_RESTORE | ✓ | ✓ | ✓ | | ||
| | WALLET_RETRIEVE_FUNDS | ✓ | ✓ | ✓ | | ||
| | WALLET_SET_STATE | ✓ | ✓ | ✓ | | ||
| | WALLET_TOTAL_FUNDS | ✓ | ✓ | ✓ | | ||
| | WALLET_VOTE | ✓ | ✓ | ✓ | | ||
| The `reload-plugin` and `reload-tests` commands can be used if only one of | ||
| those was modified, to avoid having to redo the whole process. |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.