Skip to content
Snippets Groups Projects
Commit 488207f9 authored by Jono Wenger's avatar Jono Wenger
Browse files

Update README.md with xxdk-wasm information

parent 80c87bc2
No related branches found
No related tags found
2 merge requests!510Release,!340Project/channels
Hide whitespace changes
Inline Side-by-side
Showing
with 35 additions and 23 deletions
README.md
+ 35
− 23
View file @ 488207f9
# xx network Client # xx network Client
[Repository](https://git.xx.network/elixxir/client) | [Go Doc](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk) | [Examples](https://git.xx.network/elixxir/xxdk-examples/-/tree/master) [Repository](https://git.xx.network/elixxir/client)
| [Go Doc](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk)
| [Examples](https://git.xx.network/elixxir/xxdk-examples/-/tree/master)
The client is a library and related command-line tool that facilitates making full-featured xx clients for all The client is a library and related command-line tool that facilitates making full-featured xx clients for all
platforms. It interfaces with the cMix system, enabling access to all xx network messaging features, including platforms. It interfaces with the cMix system, enabling access to all xx network messaging features, including
...@@ -11,7 +12,8 @@ This repository contains everything necessary to implement the xx network messag ...@@ -11,7 +12,8 @@ This repository contains everything necessary to implement the xx network messag
contains features to extend the base messaging protocols. contains features to extend the base messaging protocols.
The command-line tool accompanying the client library can be built for any platform supported by Go. The libraries are The command-line tool accompanying the client library can be built for any platform supported by Go. The libraries are
built for iOS and Android using [gomobile](https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile). built for iOS and Android using [gomobile](https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile). The libraries are built
for web assembly using the repository [xxdk-wasm](https://git.xx.network/elixxir/xxdk-wasm).
For library writers, the client requires a writable folder to store data, functions for receiving and approving requests For library writers, the client requires a writable folder to store data, functions for receiving and approving requests
for creating secure end-to-end messaging channels, discovering users, and receiving different types of messages. for creating secure end-to-end messaging channels, discovering users, and receiving different types of messages.
...@@ -48,7 +50,7 @@ $ GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.dar ...@@ -48,7 +50,7 @@ $ GOOS=darwin GOARCH=amd64 CGO_ENABLED=0 go build -ldflags '-w -s' -o client.dar
### Fetching an NDF ### Fetching an NDF
All actions performed with the client require a current All actions performed with the client require a current
[network definition file (NDF)](https://xxdk-dev.xx.network/technical-glossary/#network-definition-file-ndf). The NDF is [network definition file (NDF)](https://xxdk-dev.xx.network/technical-glossary/#network-definition-file-ndf). The NDF is
downloadable from the command line or downloadable from the command line or
[via an access point](https://xxdk-dev.xx.network/quick-reference#func-downloadandverifysignedndfwithurl) in the Client [via an access point](https://xxdk-dev.xx.network/quick-reference#func-downloadandverifysignedndfwithurl) in the Client
...@@ -78,16 +80,17 @@ $ ./client getndf --env mainnet | jq . > ndf.json ...@@ -78,16 +80,17 @@ $ ./client getndf --env mainnet | jq . > ndf.json
``` ```
Sample content of `ndf.json`: Sample content of `ndf.json`:
```json ```json
{ {
"Timestamp": "2021-01-29T01:19:49.227246827Z", "Timestamp": "2021-01-29T01:19:49.227246827Z",
"Gateways": [ "Gateways": [
{ {
"Id": "BRM+Iotl6ujIGhjRddZMBdauapS7Z6jL0FJGq7IkUdYB", "Id": "BRM+IoTl6ujIGhjRddZMBdaUapS7Z6jL0FJGq7IkUdYB",
"Address": ":8440", "Address": ":8440",
"Tls_certificate": "-----BEGIN CERTIFICATE-----\nMIIDbDCCAlSgAwIBAgIJAOUNtZneIYECMA0GCSqGSIb3DQEBBQUAMGgxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRIwEAYDVQQHDAlDbGFyZW1vbnQx\nGzAZBgNVBAoMElByaXZhdGVncml0eSBDb3JwLjETMBEGA1UEAwwKKi5jbWl4LnJp\ncDAeFw0xOTAzMDUxODM1NDNaFw0yOTAzMDIxODM1NDNaMGgxCzAJBgNVBAYTAlVT\nMRMwEQYDVQQIDApDYWxpZm9ybmlhMRIwEAYDVQQHDAlDbGFyZW1vbnQxGzAZBgNV\nBAoMElByaXZhdGVncml0eSBDb3JwLjETMBEGA1UEAwwKKi5jbWl4LnJpcDCCASIw\nDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAPP0WyVkfZA/CEd2DgKpcudn0oDh\nDwsjmx8LBDWsUgQzyLrFiVigfUmUefknUH3dTJjmiJtGqLsayCnWdqWLHPJYvFfs\nWYW0IGF93UG/4N5UAWO4okC3CYgKSi4ekpfw2zgZq0gmbzTnXcHF9gfmQ7jJUKSE\ntJPSNzXq+PZeJTC9zJAb4Lj8QzH18rDM8DaL2y1ns0Y2Hu0edBFn/OqavBJKb/uA\nm3AEjqeOhC7EQUjVamWlTBPt40+B/6aFJX5BYm2JFkRsGBIyBVL46MvC02MgzTT9\nbJIJfwqmBaTruwemNgzGu7Jk03hqqS1TUEvSI6/x8bVoba3orcKkf9HsDjECAwEA\nAaMZMBcwFQYDVR0RBA4wDIIKKi5jbWl4LnJpcDANBgkqhkiG9w0BAQUFAAOCAQEA\nneUocN4AbcQAC1+b3To8u5UGdaGxhcGyZBlAoenRVdjXK3lTjsMdMWb4QctgNfIf\nU/zuUn2mxTmF/ekP0gCCgtleZr9+DYKU5hlXk8K10uKxGD6EvoiXZzlfeUuotgp2\nqvI3ysOm/hvCfyEkqhfHtbxjV7j7v7eQFPbvNaXbLa0yr4C4vMK/Z09Ui9JrZ/Z4\ncyIkxfC6/rOqAirSdIp09EGiw7GM8guHyggE4IiZrDslT8V3xIl985cbCxSxeW1R\ntgH4rdEXuVe9+31oJhmXOE9ux2jCop9tEJMgWg7HStrJ5plPbb+HmjoX3nBO04E5\n6m52PyzMNV+2N21IPppKwA==\n-----END CERTIFICATE-----\n" "Tls_certificate": "-----BEGIN CERTIFICATE-----\nMIIDbDCCAlSgAwIBAgIJA8UNtZneIYE2MA0GCSqGSIb3DQE3BQU8MGgxCzAJBgNV\nBaYTAlVTmRMwEQYDvQQiDApDYWxpZm9ybmLhMRIwEAYfVQqHDAlDbGFyZW1vbnQx\nGzAZBgNVBAoMElByaXZhdGVncml0eSBDb3JwLjETMBeGA1UEAwwKKi5jbWl4LnJp\ncDAeFw0xOTAzMDUxODM1NDNaFw0yOTAzMDIxODM1NDNaMGgxCzAJBgNVBAYTAlVT\nMRMwEQYDVQQIDApDYWxpZm9ybmlhMRIwEAYDVQQHDAlDbGFyZW1vbnQxGzAZBgNV\nBAoMElByaXZhdGVncml0eSBDb3JwLjETMBEGA1UEAwwKKi5jbWl4LnJpcDCCASIw\nDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAPP0WyVkfZA/CEd2DgKpcudn0oDh\nDwsjmx8LBDWsUgQzyLrFiVigfUmUefknUH3dTJjmiJtGqLsayCnWdqWLHPJYvFfs\nWYW0IGF93UG/4N5UAWO4okC3CYgKSi4ekpfw2zgZq0gmbzTnXcHF9gfmQ7jJUKSE\ntJPSNzXq+PZeJTC9zJAb4Lj8QzH18rDM8DaL2y1ns0Y2Hu0edBFn/OqavBJKb/uA\nm3AEjqeOhC7EQUjVamWlTBPt40+B/6aFJX5BYm2JFkRsGBIyBVL46MvC02MgzTT9\nbJIJfwqmBaTruwemNgzGu7Jk03hqqS1TUEvSI6/x8bVoba3orcKkf9HsDjECAwEA\nAaMZMBcwFQYDVR0RBA4wDIIKKi5jbWl4LnJpcDANBgkqhkiG9w0BAQUFAAOCAQEA\nneUocN4AbcQAC1+b3To8u5UGdaGxhcGyZBlAoenRVdjXK3lTjsMdMWb4QctgNfIf\nU/zuUn2mxTmF/ekP0gCCgtleZr9+DYKU5hlXk8K10uKxGD6EvoiXZzlfeUuotgp2\nqvI3ysOm/hvCfyEkqhfHtbxjV7j7v7eQFPbvNaXbLa0yr4C4vMK/Z09Ui9JrZ/Z4\ncyIkxfC6/rOqAirSdIp09EGiw7GM8guHyggE4IiZrDslT8V3xIl985cbCxSxeW1R\ntgH4rdEXuVe9+31oJhmXOE9ux2jCop9tEJMgWg7HStrJ5plPbb+HmjoX3nBO04E5\n6m52PyzMNV+2N21IPppKwA==\n-----END CERTIFICATE-----\n"
} }
] ]
} }
``` ```
...@@ -99,9 +102,9 @@ $ ./client getndf --help ...@@ -99,9 +102,9 @@ $ ./client getndf --help
### Sending Safe Messages Between Two (2) Users ### Sending Safe Messages Between Two (2) Users
> 💡 **Note:** For information on receiving messages and troubleshooting authenticated channel requests, > 💡 **Note:** For information on receiving messages and troubleshooting authenticated channel requests, see
see [Receiving Messages](#receiving-messages) and > [Receiving Messages](#receiving-messages)
> [Confirming authenticated channel requests](#confirming-authenticated-channel-requests). > and [Confirming authenticated channel requests](#confirming-authenticated-channel-requests).
To send messages with end-to-end encryption, you must first establish a connection To send messages with end-to-end encryption, you must first establish a connection
or [authenticated channel](https://xxdk-dev.xx.network/technical-glossary#authenticated-channel) with the other user. or [authenticated channel](https://xxdk-dev.xx.network/technical-glossary#authenticated-channel) with the other user.
...@@ -148,7 +151,7 @@ Received 0 ...@@ -148,7 +151,7 @@ Received 0
* `-s`: The storage directory for client session data. * `-s`: The storage directory for client session data.
* `--writeContact`: Output the user's contact information to this file. * `--writeContact`: Output the user's contact information to this file.
* `--destfile` is used to specify the recipient. You can also use `--destid b64:...` using the user's base64 ID, which * `--destfile` is used to specify the recipient. You can also use `--destid b64:...` using the user's base64 ID, which
is printed in the logs. is printed in the logs.
* `--unsafe`: Send message without encryption (necessary whenever you have not already established an e2e channel). * `--unsafe`: Send message without encryption (necessary whenever you have not already established an e2e channel).
* `--unsafe-channel-creation` Auto-create and auto-accept channel requests. * `--unsafe-channel-creation` Auto-create and auto-accept channel requests.
* `-m`: The message to send. * `-m`: The message to send.
...@@ -158,7 +161,7 @@ This is why we've used the `--unsafe` flag when creating the user contact files. ...@@ -158,7 +161,7 @@ This is why we've used the `--unsafe` flag when creating the user contact files.
However, when sending between users, the flag is dropped in exchange for `--unsafe-channel-creation`. However, when sending between users, the flag is dropped in exchange for `--unsafe-channel-creation`.
For the authenticated channel creation to be considered "safe", the user should be prompted. You can do this by For the authenticated channel creation to be considered "safe", the user should be prompted. You can do this by
explicitly accepting the channel creation when sending a request with `--send-auth-request` (while excluding the explicitly accepting the channel creation when sending a request with `--send-auth-request` (while excluding the
`--unsafe-channel-creation` flag) or explicitly accepting a request with `--accept-channel`: `--unsafe-channel-creation` flag) or explicitly accepting a request with `--accept-channel`:
```shell ```shell
...@@ -189,8 +192,8 @@ See [Sending Safe Messages Between Two (2) Users](#sending-safe-messages-between ...@@ -189,8 +192,8 @@ See [Sending Safe Messages Between Two (2) Users](#sending-safe-messages-between
Setting up an authenticated channel between clients is a back-and-forth process that happens in sequence. One client Setting up an authenticated channel between clients is a back-and-forth process that happens in sequence. One client
sends a request and waits for the other to accept it. sends a request and waits for the other to accept it.
See the previous section, [Sending safe messages between 2 users](#sending-safe-messages-between-two-2-users), for example, See the previous section, [Sending safe messages between 2 users](#sending-safe-messages-between-two-2-users), for
commands showing how to set up an end-to-end connection between clients before sending messages. example, commands showing how to set up an end-to-end connection between clients before sending messages.
As with received messages, there is no command for checking for authenticated channel requests; you'll be notified of As with received messages, there is no command for checking for authenticated channel requests; you'll be notified of
any pending requests whenever the client is run. any pending requests whenever the client is run.
...@@ -226,7 +229,7 @@ request. This means your client has not received the request. If one has been se ...@@ -226,7 +229,7 @@ request. This means your client has not received the request. If one has been se
Full usage of the client can be found with `client --help`: Full usage of the client can be found with `client --help`:
```shell ```text
$ ./client --help $ ./client --help
Runs a client for cMix anonymous communication platform Runs a client for cMix anonymous communication platform
...@@ -296,15 +299,19 @@ Flags: ...@@ -296,15 +299,19 @@ Flags:
Use "client [command] --help" for more information about a command. Use "client [command] --help" for more information about a command.
``` ```
>💡 **Note:** The client cannot be used on the xx network with pre-canned user IDs. > 💡 **Note:** The client cannot be used on the xx network with pre-canned user IDs.
## Library Overview ## Library Overview
The xx client is designed to be a go library (and, by extension, a C library). The xx client is designed to be a Go library (and, by extension, a C library).
Support is also present for Go mobile to build Android and iOS libraries. In addition, we bind all exported symbols from Support is also present for Go mobile to build Android and iOS libraries. In addition, we bind all exported symbols from
the bindings package for use on mobile platforms. the bindings package for use on mobile platforms.
This library is also supported by WebAssembly through the [xxdk-wasm](https://git.xx.network/elixxir/xxdk-wasm)
repository. xxdk-wasm wraps the bindings package in this repository so that they can be used by Javascript when compiled
for WebAssembly.
### Implementation Notes ### Implementation Notes
Clients must perform the same actions *in the same order* as shown in `cmd/root.go`. Specifically, certain handlers need Clients must perform the same actions *in the same order* as shown in `cmd/root.go`. Specifically, certain handlers need
...@@ -323,6 +330,10 @@ and functions exposed by the Client API. ...@@ -323,6 +330,10 @@ and functions exposed by the Client API.
The main entry point for developing with the client is `xxdk/cmix` (or `bindings/cmix`). We recommend using the The main entry point for developing with the client is `xxdk/cmix` (or `bindings/cmix`). We recommend using the
[documentation in the Go package directory](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk). [documentation in the Go package directory](https://pkg.go.dev/gitlab.com/elixxir/client/xxdk).
If you are developing with the client through the browser and Javascript, refer to the
[xxdk-wasm](https://git.xx.network/elixxir/xxdk-wasm) repository, which wraps the `bindings/cmix` package. You may also
want to refer to the [Go documentation](https://pkg.go.dev/gitlab.com/elixxir/xxdk-wasm/wasm).
Looking at the API will, for example, show you there is a `RoundEvents` callback registration function, which lets your Looking at the API will, for example, show you there is a `RoundEvents` callback registration function, which lets your
client see round events. client see round events.
...@@ -373,6 +384,7 @@ gomobile for binding should include a shell script that creates the bindings. Fo ...@@ -373,6 +384,7 @@ gomobile for binding should include a shell script that creates the bindings. Fo
machine with Xcode installed. machine with Xcode installed.
Important reference info: Important reference info:
1. [Setting up gomobile and subcommands](https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile) 1. [Setting up gomobile and subcommands](https://pkg.go.dev/golang.org/x/mobile/cmd/gomobile)
2. [Reference cycles, type restrictions](https://pkg.go.dev/golang.org/x/mobile/cmd/gobind) 2. [Reference cycles, type restrictions](https://pkg.go.dev/golang.org/x/mobile/cmd/gobind)
...@@ -403,4 +415,4 @@ You can verify that all symbols got bound by unzipping `bindings-sources.jar` an ...@@ -403,4 +415,4 @@ You can verify that all symbols got bound by unzipping `bindings-sources.jar` an
Every time you make a change to the client or bindings, you must rebuild the client bindings into a `.aar` or `iOS.zip` Every time you make a change to the client or bindings, you must rebuild the client bindings into a `.aar` or `iOS.zip`
to propagate those changes to the app. There's a script that runs gomobile for you in the `bindings-integration` to propagate those changes to the app. There's a script that runs gomobile for you in the `bindings-integration`
repository. repository.
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment