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_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. :return: GA_OK or an error code. :rtype: 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. :return: GA_OK or an error code. :rtype: 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. :return: GA_OK or an error code. :rtype: 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. :return: GA_OK or an error code. :rtype: 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_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:

Note

When calling from C/C++, the parameter details will be emptied when the call

completes. :return: GA_OK or an error code. :rtype: 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.

Parameters:

Note

When calling from C/C++, the parameters hw_device and details will be emptied when the call

completes. :return: GA_OK or an error code. :rtype: int

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

Authenticate to a user’s wallet.

Parameters:

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

When calling from C/C++, the parameters hw_device and details will be emptied when the call

completes. :return: GA_OK or an error code. :rtype: int

int GA_set_watch_only(struct GA_session *session, const char *username, const char *password)

Set or disable a watch-only login for a logged-in user wallet.

Parameters:

  • session – The session to use.

  • username – The watch-only username to login with, or a blank string to disable.

  • password – The watch-only password to login with, or a blank string to disable.

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. 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. :return: GA_OK or an error code. :rtype: 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. 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

When calling from C/C++, the parameter details will be emptied when the call completes.

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:
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 creation. The call handlers result is Subaccount JSON. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Returns:

GA_OK or an error code.

Return type:

int

int GA_rename_subaccount(struct GA_session *session, uint32_t subaccount, const char *new_name)

Rename a subaccount.

Parameters:

  • session – The session to use.

  • subaccount – The value of "pointer" from Subaccounts list JSON or Subaccount JSON for the subaccount to rename.

  • new_name – New name for the subaccount.

Note

This call is deprecated and will be removed in a future release. Use GA_update_subaccount to rename subaccounts.

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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

When calling from C/C++, the parameter details will be emptied when the call completes.

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

When calling from C/C++, the parameter details will be emptied when the call completes.

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:

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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:

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 complete the action. The call handlers result is the decrypted JSON. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter transaction_details will be emptied when the call completes.

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 complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter transaction_details will be emptied when the call completes.

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

When calling from C/C++, the parameter transaction_details will be emptied when the call completes.

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:
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:
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:

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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

When calling from C/C++, the parameter details will be emptied when the call completes.

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, const char *transaction_hex, char **tx_hash)

Broadcast a fully signed transaction to the P2P network.

Parameters:

  • session – The session to use.

  • transaction_hex – The signed transaction in hex to broadcast.

  • tx_hash – Destination for the resulting transactions hash. Returned string should be freed using GA_destroy_string.

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. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter transaction_details will be emptied when the call completes.

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. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 change the locktime. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter locktime_details will be emptied when the call completes.

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 change the locktime. 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:

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 acknowledge the message. 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. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter settings will be emptied when the call completes.

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 action Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

When calling from C/C++, the parameter twofactor_details will be emptied when the call completes.

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 request the reset. 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 request the reset. 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 cancel the reset. 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:

Note

When calling from C/C++, the parameter limit_details will be emptied when the call completes.

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:

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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 complete the action. The call handlers result is BCUR Decoded data JSON. 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.

Note

When calling from C/C++, the parameter details will be emptied when the call completes.

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