GDK Functions

int GA_init(const GA_json *config)

Perform one-time initialization of the library. This call must be made once only before calling any other GDK functions, including any functions called from other threads.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_shutdown(void)

Completely shut down the library, releasing all resources.

No further GDK calls should be made after this call.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_thread_error_details(GA_json **output)

Get any error details associated with the last error on the current thread.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_create_session(struct GA_session **session)

Create a new session.

Parameters:

  • session – Destination for the resulting session. The returned session should be freed using GA_destroy_session.

Once created, the caller should set a handler for notifications using GA_set_notification_handler, before calling GA_connect to connect the session to the network for use.

Returns:

GA_OK or an error code.

Return type:

int

int GA_set_notification_handler(struct GA_session *session, GA_notification_handler handler, void *context)

Set a handler to be called when notifications arrive for a session.

Parameters:

  • session – The session to receive notifications for.

  • handler – The handler to receive notifications.

  • context – A context pointer to be passed to the handler.

This call must be initially made on a session before GA_connect. GDK Notifications may arrive on different threads, so the caller must ensure that shared data is correctly locked within the handler. The GA_json object passed to the caller must be destroyed by the caller using GA_destroy_json. Failing to do so will result in memory leaks.

Once a session has been connected, this call can be made only with null values for handler and context. Once this returns, no further notifications will be delivered for the lifetime of the session.

The caller should not call session functions from within the callback handler as this may block the application.

Returns:

GA_OK or an error code.

Return type:

int

int GA_destroy_session(struct GA_session *session)

Free a session allocated by GA_create_session.

Parameters:

  • session – The session to free.

If the session was connected using GA_connect then this call will disconnect it it before destroying it.

Returns:

GA_OK or an error code.

Return type:

int

int GA_connect(struct GA_session *session, const GA_json *net_params)

Connect the session to the specified network.

Parameters:

This call connects to the remote network services that the session requires, for example the Green servers or Electrum servers. GA_connect must be called only once per session lifetime, after GA_create_session and before GA_destroy_session respectively. Once connected, the underlying network connection of the session can be controlled using GA_reconnect_hint.

Once the session is connected, use GA_register_user to create a new wallet for the session, or GA_login_user to open an existing wallet.

Returns:

GA_OK or an error code.

Return type:

int

int GA_reconnect_hint(struct GA_session *session, const GA_json *hint)

Connect or disconnect a sessions underlying network connection.

Parameters:

  • session – The session to use.

  • hint – the Reconnect JSON describing the desired reconnection behaviour.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_proxy_settings(struct GA_session *session, GA_json **output)

Get the current proxy settings for the given session.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_wallet_identifier(const GA_json *net_params, const GA_json *params, GA_json **output)

Compute a hashed wallet identifier from a BIP32 xpub or mnemonic.

The identifier returned is computed from the network combined with the master chain code and public key of the xpub/mnemonic. It can be used as a unique wallet identifier to mitigate privacy risks associated with storing the wallet’s xpub.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_cache_control(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Operate on cached session data.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_http_request(struct GA_session *session, const GA_json *params, GA_json **output)

Make a request to an http server.

Parameters:

  • session – The session to use.

  • params – the HTTP parameters JSON of the server to connect to.

  • output – Destination for the output JSON. Returned GA_json should be freed using GA_destroy_json.

Returns:

GA_OK or an error code.

Return type:

int

int GA_refresh_assets(struct GA_session *session, const GA_json *params)

Refresh the sessions internal cache of Liquid asset information.

Each release of GDK comes with a partial list of Liquid assets built-in. This call is used to update it to include all the registered Liquid assets or any new assets that have been registered since the last update.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_assets(struct GA_session *session, const GA_json *params, GA_json **output)

Query the Liquid asset registry.

This call is used to retrieve informations about a set of Liquid assets specified by their asset id.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_validate_asset_domain_name(struct GA_session *session, const GA_json *params, GA_json **output)

Validate asset domain name. (This is a interface stub)

Returns:

GA_OK or an error code.

Return type:

int

int GA_validate(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Validate a gdk format JSON document.

Parameters:

  • session – The session to use.

  • details – The Validate JSON to validate.

  • call – Destination for the resulting GA_auth_handler to perform the validation. The call handlers result is Validate Result JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_register_user(struct GA_session *session, GA_json *hw_device, GA_json *details, struct GA_auth_handler **call)

Create a new user wallet or watch only session.

Parameters:

  • session – The session to use.

  • hw_device – HW device JSON or empty JSON for software wallet/watch only creation.

  • details – The Login credentials JSON for software wallet/watch only creation.

  • call – Destination for the resulting GA_auth_handler to perform the creation. The call handlers result is Register/Login result JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When creation a watch only session, the calling session must be logged in.

Note

hw_device and details are emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_login_user(struct GA_session *session, GA_json *hw_device, GA_json *details, struct GA_auth_handler **call)

Login to a user’s wallet.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

If a sessions underlying network connection has disconnected and reconnected, the user will need to login again using this function. In this case, the caller can pass empty JSON for both hw_device and details to login using the previously passed credentials and device.

Note

hw_device and details are emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_watch_only_username(struct GA_session *session, char **username)

Get the current watch-only login for a logged-in user wallet, if any.

Parameters:

  • session – The session to use.

  • username – Destination for the watch-only username. Empty string if not set. Returned string should be freed using GA_destroy_string.

Returns:

GA_OK or an error code.

Return type:

int

int GA_remove_account(struct GA_session *session, struct GA_auth_handler **call)

Remove and delete the server history of a wallet.

Parameters:

  • session – The session to use.

  • call – Destination for the resulting GA_auth_handler to perform the removal.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

For multisig Green sessions, removing a wallet removes all history and data associated with the wallet on the server. This operation cannot be undone, and re-registering the wallet will not bring back the wallet’s history. For this reason, only empty wallets can be deleted.

For singlesig sessions, removing a wallet removes the locally persisted cache. The actual removal will happen after GA_destroy_session is called.

Returns:

GA_OK or an error code.

Return type:

int

int GA_create_subaccount(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Create a subaccount.

Parameters:

  • session – The session to use.

  • details – The subaccount "name" (which must not be already used in the wallet) and "type" (either "2of2", "2of2_no_recovery" or "2of3") must be populated. Type "2of2_no_recovery" is available only for Liquid networks and always requires both keys for spending. For type "2of3" the caller may provide either "recovery_mnemonic" or "recovery_xpub" if they do not wish to have a mnemonic passphrase generated automatically. All other fields are ignored.

  • call – Destination for the resulting GA_auth_handler to perform the creation.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler. Details of the created subaccount are returned in the "result" element of the GA_auth_handler. For 2of3 subaccounts the field "recovery_xpub" will be populated, and "recovery_mnemonic" will contain the recovery mnemonic passphrase if one was generated. These values must be stored safely by the caller as they will not be returned again by any call such as GA_get_subaccounts.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_subaccounts(struct GA_session *session, const GA_json *details, struct GA_auth_handler **call)

Get the user’s subaccount details.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_subaccount(struct GA_session *session, uint32_t subaccount, struct GA_auth_handler **call)

Get subaccount details.

Parameters:

  • session – The session to use.

  • subaccount – The value of "pointer" from Subaccounts list JSON for the subaccount.

  • call – Destination for the resulting GA_auth_handler to perform the fetch. The call handlers result is Subaccount JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_update_subaccount(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Update subaccount information.

Parameters:

  • session – The session to use.

  • details – Subaccount update JSON giving the details to update.

  • call – Destination for the resulting GA_auth_handler to perform the update.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_transactions(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get a page of the user’s transaction history.

Parameters:

  • session – The session to use.

  • details – Transactions details JSON giving the details to get the transactions for.

  • call – Destination for the resulting GA_auth_handler to perform the fetch.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Note

Transactions are returned as Transaction list JSON from newest to oldest with up to 30 transactions per page.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_receive_address(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get a new address to receive coins to.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_previous_addresses(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get a page of addresses previously generated for a subaccount.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Note

Iteration of all addresses is complete when ‘last_pointer’ is not present in the results.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_unspent_outputs(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get the user’s unspent transaction outputs.

Parameters:

  • session – The session to use.

  • details – Unspent outputs request JSON detailing the unspent transaction outputs to fetch.

  • call – Destination for the resulting GA_auth_handler to perform the fetch. The call handlers result is Unspent outputs JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_unspent_outputs_for_private_key(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get the unspent transaction outputs associated with a non-wallet private key.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

Neither the private key or its derived public key are sent to any third party for this call.

Returns:

GA_OK or an error code.

Return type:

int

int GA_set_unspent_outputs_status(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Change the status of a user’s unspent transaction outputs.

Parameters:

  • session – The session to use.

  • details – Unspent outputs set status JSON detailing the unspent transaction outputs status to set.

  • call – Destination for the resulting GA_auth_handler to perform the change.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_transaction_details(struct GA_session *session, const char *txhash_hex, GA_json **transaction)

Get a transaction’s details.

Parameters:

  • session – The session to use.

  • txhash_hex – The transaction hash of the transaction to fetch.

  • transaction – Destination for the Transaction details JSON. Returned GA_json should be freed using GA_destroy_json.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_balance(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get the sum of unspent outputs paying to a subaccount.

Parameters:

  • session – The session to use.

  • details – Unspent outputs request JSON detailing the unspent transaction outputs to compute the balance from.

  • call – Destination for the resulting GA_auth_handler to perform the fetch.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_available_currencies(struct GA_session *session, GA_json **currencies)

Get the list of allowed currencies for all available pricing sources.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_convert_amount(struct GA_session *session, const GA_json *value_details, GA_json **output)

Convert Fiat to BTC and vice-versa.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_encrypt_with_pin(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Encrypt JSON with a server provided key protected by a PIN.

Parameters:

  • session – The session to use.

  • details – The Encrypt with PIN JSON to encrypt.

  • call – Destination for the resulting GA_auth_handler to perform the encryption. The call handlers result is Encrypt with PIN Result JSON which the caller should persist.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_decrypt_with_pin(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Decrypt JSON with a server provided key protected by a PIN.

Parameters:

  • session – The session to use.

  • details – The Decrypt with PIN JSON to decrypt.

  • call – Destination for the resulting GA_auth_handler to perform the decryption. The call handlers result is the decrypted JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_disable_all_pin_logins(struct GA_session *session)

Disable all PIN logins previously set.

After calling this method, the user will not be able to login with PIN from any device that was previously enabled using GA_encrypt_with_pin.

Parameters:

  • session – The session to use.

Returns:

GA_OK or an error code.

Return type:

int

int GA_create_transaction(struct GA_session *session, GA_json *transaction_details, struct GA_auth_handler **call)

Construct a transaction.

Parameters:

  • session – The session to use.

  • transaction_details – The GDK Create Transaction JSON for constructing.

  • call – Destination for the resulting GA_auth_handler to perform the construction.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

transaction_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_blind_transaction(struct GA_session *session, GA_json *transaction_details, struct GA_auth_handler **call)

Blind a transaction.

Parameters:

  • session – The session to use.

  • transaction_details – The GDK Create Transaction JSON for blinding.

  • call – Destination for the resulting GA_auth_handler to perform the blinding.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

transaction_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_sign_transaction(struct GA_session *session, GA_json *transaction_details, struct GA_auth_handler **call)

Sign the user’s inputs to a transaction.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

transaction_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_create_swap_transaction(struct GA_session *session, const GA_json *swap_details, struct GA_auth_handler **call)

Construct the initiators side of a swap transaction.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_complete_swap_transaction(struct GA_session *session, const GA_json *swap_details, struct GA_auth_handler **call)

Complete construction of the callers side of a swap transaction.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_create_redeposit_transaction(struct GA_session *session, const GA_json *details, struct GA_auth_handler **call)

Construct a transaction re-depositing expiring UTXOs. Used to extend two factor protection for multisig UTXOs.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_psbt_sign(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Sign one or more of a user’s inputs in a PSBT or PSET.

Parameters:

  • session – The session to use.

  • details – The Sign PSBT JSON for signing.

  • call – Destination for the resulting GA_auth_handler to perform the signing. The call handlers result is Sign PSBT Result JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Note

EXPERIMENTAL warning: this call may be changed in future releases.

Returns:

GA_OK or an error code.

Return type:

int

int GA_psbt_get_details(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get wallet details of a PSBT or PSET.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Note

EXPERIMENTAL warning: this call may be changed in future releases.

Returns:

GA_OK or an error code.

Return type:

int

int GA_broadcast_transaction(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Broadcast a fully signed transaction, PSBT or PSET to the network.

Parameters:

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_send_transaction(struct GA_session *session, GA_json *transaction_details, struct GA_auth_handler **call)

Send a transaction created by GA_create_transaction and signed by GA_sign_transaction.

Parameters:

  • session – The session to use.

  • transaction_details – The Send transaction JSON for sending.

  • call – Destination for the resulting GA_auth_handler to perform the send.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

transaction_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_sign_message(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Sign a message with the private key of an address.

Parameters:

  • session – The session to use.

  • details – The Sign Message JSON detailing the message to sign and how to sign it.

  • call – Destination for the resulting GA_auth_handler to perform the signing. The call handlers result is Sign Message Result JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_send_nlocktimes(struct GA_session *session)

Request an email containing the user’s nLockTime transactions.

Parameters:

  • session – The session to use.

Returns:

GA_OK or an error code.

Return type:

int

int GA_set_csvtime(struct GA_session *session, GA_json *locktime_details, struct GA_auth_handler **call)

Set the number of blocks after which CSV transactions become spendable without two factor authentication.

Parameters:

  • session – The session to use.

  • locktime_details – The Locktime details JSON for setting the block value.

  • call – Destination for the resulting GA_auth_handler to perform the change.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

locktime_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_set_nlocktime(struct GA_session *session, const GA_json *locktime_details, struct GA_auth_handler **call)

Set the number of blocks after which nLockTime transactions become spendable without two factor authentication. When this call succeeds, if the user has an email address associated with the wallet, an updated nlocktimes.zip file will be sent via email.

Parameters:

  • session – The session to use.

  • locktime_details – The Locktime details JSON for setting the block value.

  • call – Destination for the resulting GA_auth_handler to perform the change.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_set_transaction_memo(struct GA_session *session, const char *txhash_hex, const char *memo, uint32_t memo_type)

Add a transaction memo to a user’s GreenAddress transaction.

Parameters:

  • session – The session to use.

  • txhash_hex – The transaction hash to associate the memo with.

  • memo – The memo to set.

  • memo_type – Unused, pass 0.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_fee_estimates(struct GA_session *session, GA_json **estimates)

Get the current network’s fee estimates.

Parameters:

The estimates are returned as an array of 25 elements. Each element is an integer representing the fee estimate expressed as satoshi per 1000 bytes. The first element is the minimum relay fee as returned by the network, while the remaining elements are the current estimates to use for a transaction to confirm from 1 to 24 blocks.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_credentials(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Get the user’s credentials.

Parameters:

  • session – The session to use.

  • details – The Get credentials JSON to get the credentials.

  • call – Destination for the resulting GA_auth_handler to perform the fetch. The call handlers result is Login credentials JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_system_message(struct GA_session *session, char **message_text)

Get the latest un-acknowledged system message.

Parameters:

  • session – The session to use.

  • message_text – The returned UTF-8 encoded message text. Returned string should be freed using GA_destroy_string.

Note

If all current messages are acknowledged, an empty string is returned.

Returns:

GA_OK or an error code.

Return type:

int

int GA_ack_system_message(struct GA_session *session, const char *message_text, struct GA_auth_handler **call)

Sign and acknowledge a system message.

The message text will be signed with a key derived from the wallet master key and the signature sent to the server.

Parameters:

  • session – The session to use.

  • message_text – UTF-8 encoded message text being acknowledged.

  • call – Destination for the resulting GA_auth_handler to perform the acknowledgement.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_twofactor_config(struct GA_session *session, GA_json **config)

Get the two factor configuration for the current user.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_change_settings(struct GA_session *session, GA_json *settings, struct GA_auth_handler **call)

Change wallet settings.

Parameters:

  • session – The session to use.

  • settings – The new Settings JSON values.

  • call – Destination for the resulting GA_auth_handler to perform the change.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

settings is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_settings(struct GA_session *session, GA_json **settings)

Get current wallet settings.

Parameters:

  • session – The session to use.

  • settings – Destination for the current Settings JSON. Returned GA_json should be freed using GA_destroy_json.

Returns:

GA_OK or an error code.

Return type:

int

int GA_destroy_json(GA_json *json)

Free a GA_json object.

Parameters:

  • json – GA_json object to free.

Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_get_status(struct GA_auth_handler *call, GA_json **output)

Get the status/result of an action requiring authorization.

Parameters:

Methods in the api that may require two factor or hardware authentication to complete return a GA_auth_handler object. This object encapsulates the process of determining whether authentication is required and handling conditions such as re-prompting and re-trying after an incorrect two factor code is entered.

The object acts as a state machine which is stepped through by the caller until the desired action is completed. At each step, the current state can be determined and used to perform the next action required.

Some actions require a sequence of codes and decisions; these are hidden behind the state machine interface so that callers do not need to handle special cases or program their own logic to handle any lower level API differences.

The state machine has the following states, which are returned in the "status" element from GA_auth_handler_get_status:

  • "done": The action has been completed successfully. Any data returned from the action is present in the "result" element of the status JSON. The auth_handler object should be destroyed using GA_destroy_auth_handler after receiving this status.

  • "error": A non-recoverable error occurred performing the action. The associated error message is given in the status element "error". The auth_handler object should be destroyed using GA_destroy_auth_handler and the action restarted from scratch if this state is returned.

  • "request_code": Two factor authorization is required. The caller should prompt the user to choose a two factor method from the "methods" element and call GA_auth_handler_request_code with the selected method.

  • "resolve_code": A twofactor code from the "request_code" step, or data from a hardware device is required. If the status JSON contains Required Data JSON, then see GDK Hardware Wallet Interface for details. Otherwise, to resolve a twofactor code, the caller should prompt the user to enter the code from the twofactor method chosen in the "request_code" step, and pass this code to GA_auth_handler_resolve_code.

  • "call": Twofactor or hardware authorization is complete and the caller should call GA_auth_handler_call to perform the action.

Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_request_code(struct GA_auth_handler *call, const char *method)

Request a two factor authentication code to authorize an action.

Parameters:

  • call – The auth_handler representing the action to perform.

  • method – The selected two factor method to use

Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_resolve_code(struct GA_auth_handler *call, const char *code)

Authorize an action by providing its previously requested two factor authentication code.

Parameters:

  • call – The auth_handler representing the action to perform.

  • code – The two factor authentication code received by the user, or the serialised JSON response for hardware interaction (see GDK Hardware Wallet Interface).

Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_call(struct GA_auth_handler *call)

Perform an action following the completion of authorization.

Parameters:

  • call – The auth_handler representing the action to perform.

Returns:

GA_OK or an error code.

Return type:

int

int GA_destroy_auth_handler(struct GA_auth_handler *call)

Free an auth_handler after use.

Parameters:

  • call – The auth_handler to free.

Returns:

GA_OK or an error code.

Return type:

int

int GA_change_settings_twofactor(struct GA_session *session, const char *method, GA_json *twofactor_details, struct GA_auth_handler **call)

Enable or disable a two factor authentication method.

Parameters:

  • session – The session to use

  • method – The two factor method to enable/disable, e.g. "email", "sms", "phone", "gauth"

  • twofactor_details – Two Factor Detail JSON giving the two factor method and associated data.

  • call – Destination for the resulting GA_auth_handler to perform the enablement/disablement.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

twofactor_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_reset(struct GA_session *session, const char *email, uint32_t is_dispute, struct GA_auth_handler **call)

Request to begin the two factor authentication reset process.

Returns the "twofactor_reset" portion of Two Factor Config JSON in the GA_auth_handler result.

Parameters:

  • session – The session to use.

  • email – The new email address to enable once the reset waiting period expires.

  • is_dispute – GA_TRUE if the reset request is disputed, GA_FALSE otherwise.

  • call – Destination for the resulting GA_auth_handler to perform the request.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_undo_reset(struct GA_session *session, const char *email, struct GA_auth_handler **call)

Undo a request to begin the two factor authentication reset process.

Returns the "twofactor_reset" portion of Two Factor Config JSON in the GA_auth_handler result.

Parameters:

  • session – The session to use.

  • email – The email address to cancel the reset request for. Must be the email previously passed to GA_twofactor_reset.

  • call – Destination for the resulting GA_auth_handler to perform the undo.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

Unlike GA_twofactor_cancel_reset, this call only removes the reset request associated with the given email. If other emails have requested a reset, the wallet will still remain locked following this call.

Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_cancel_reset(struct GA_session *session, struct GA_auth_handler **call)

Cancel all two factor reset requests and unlock the wallet for normal operation.

This call requires authentication using an existing wallet twofactor method.

Returns the "twofactor_reset" portion of Two Factor Config JSON in the GA_auth_handler result.

Parameters:

  • session – The session to use.

  • call – Destination for the resulting GA_auth_handler to perform the cancel.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_change_limits(struct GA_session *session, GA_json *limit_details, struct GA_auth_handler **call)

Change twofactor limits settings.

Parameters:

  • session – The session to use.

  • limit_details – Transaction limits JSON containing the new limits to set.

  • call – Destination for the resulting GA_auth_handler to perform the change. The call handlers result is Transaction limits JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

limit_details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_bcur_encode(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Encode CBOR into (potentially multi-part) UR-encoding.

Parameters:

  • session – The session to use.

  • details – BCUR Encode JSON containing the CBOR data to encode.

  • call – Destination for the resulting GA_auth_handler to perform the encoding. The call handlers result is BCUR Encoded fragments JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_bcur_decode(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Decode (potentially multi-part) UR-encoded data to CBOR.

Parameters:

  • session – The session to use.

  • details – BCUR Decode JSON containing the the first URI to decode.

  • call – Destination for the resulting GA_auth_handler to perform the decoding. The call handlers result is BCUR Decoded data JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

For multi-part data, the call hander will request further parts using "request_code" with a method of "data". see: Auth handler status JSON for details on the general mechanism and BCUR Decoding Auth Handler JSON for details on the data passed to and expected from the auth handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

int GA_rsa_verify(struct GA_session *session, GA_json *details, struct GA_auth_handler **call)

Verify an RSA challenge.

Parameters:

  • session – The session to use.

  • details – RSA Verify JSON containing the the details to verify.

  • call – Destination for the resulting GA_auth_handler to perform the verification. The call handlers result is RSA Verify Result JSON.

Note

The returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

details is emptied when called directly from C or C++.

Returns:

GA_OK or an error code.

Return type:

int

void GA_destroy_string(char *str)

Free a string returned by the api.

Parameters:

  • str – The string to free.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_random_bytes(size_t num_bytes, unsigned char *output_bytes, size_t len)

Get up to 32 random bytes.

Generate up to 32 random bytes using the same strategy as Bitcoin Core code.

Parameters:

  • output_bytes – bytes output buffer

  • siz – Number of bytes to return (max. 32)

Returns:

GA_OK or an error code.

Return type:

int

int GA_generate_mnemonic(char **output)

Generate a new random BIP 39 mnemonic.

Parameters:

  • output – The generated mnemonic phrase. Returned string should be freed using GA_destroy_string.

Returns:

GA_OK or an error code.

Return type:

int

int GA_generate_mnemonic_12(char **output)

Generate a new random 12 word BIP 39 mnemonic.

Parameters:

  • output – The generated mnemonic phrase. Returned string should be freed using GA_destroy_string.

Returns:

GA_OK or an error code.

Return type:

int

int GA_validate_mnemonic(const char *mnemonic, uint32_t *valid)

Validate a BIP 39 mnemonic.

Parameters:

  • mnemonic – The mnemonic phrase

  • valid – Destination for the result: GA_TRUE if the mnemonic is valid else GA_FALSE

Returns:

GA_OK or an error code.

Return type:

int

int GA_register_network(const char *name, const GA_json *network_details)

Register a network configuration

Parameters:

  • name – The name of the network to register

  • network_details – The Network JSON configuration to register

Any existing configuration with the same name is overwritten. If the provided JSON is empty, any existing configuration for the network is removed.

Returns:

GA_OK or an error code.

Return type:

int

int GA_get_networks(GA_json **output)

Get the available network configurations

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_uniform_uint32_t(uint32_t upper_bound, uint32_t *output)

Get a uint32_t in the range 0 to (upper_bound - 1) without bias

Parameters:

  • output – Destination for the generated uint32_t.

Returns:

GA_OK or an error code.

Return type:

int