API reference
tip
We recommend that all web developers read from the Getting started section and onward .
Marina injects a global API into websites visited by its users at window.marina. This API allows websites to request users' Liquid addresses and blinding keys, read data about the blockchain the user is connected to, and suggest that the user sign messages and send transactions.
The marina-provider package provides a function detectProvider
to inspect and fetch the window.marina
provider.
#
BasicsFor any non-trivial Liquid-powered web application to work, you will have to:
- Detect if Marina provider is installed
- If the first time for the user, ask permissions to connect using
marina.enable()
- Detect which network the user is connected to (either
liquid
orregtest
) usingmarina.getNetwork()
- Get the user's Liquid addresses(s) and blinding keys using
marina.getNextAddress()
The snippet at the top of this page is sufficient for detecting the provider.
The provider API is all you need to create a full-featured Liquid powered web application.
#
API#
MarinaProvider- isEnabled
- isReady
- getAccountInfo
- useAccount
- createAccount
- enable
- disable
- getNetwork
- getAddresses
- getNextAddress
- getNextChangeAddress
- sendTransaction
- blindTransaction
- signTransaction
- signMessage
- getTransactions
- getCoins
- getBalances
- getFeeAssets
- on
- off
#
Utils#
createAccountOpen a popup, ask the password locking the marina private key. If the user accepts, marina will create a new account.
Account types are:
AccountType.P2WPKH
: native segwit v0 account (default)AccountType.Ionio
: account using Ionio artifacts to generate taproot scripts.
tip
All accounts are confidential and generate blinding keys for each script according to SLIP77.
#
getAccountInfoGet the account info of the account accountID
if it exists. Returns an error otherwise.
#
useAccountSwitch to account with ID = accountID
if it exists. By default, current selected account is always "mainAccount".
#
isEnabledReturns whether the user has already granted permission to the website to access their wallet. If this returns false, some methods will throw an error.
#
isReadyReturns whether the user has already set up a wallet.
#
enableAsk the user to grant permissions to the website to access his wallet. It will open a popup and wait for the user's response.
#
disableDeny the website to access the user's wallet. It does not open any popup and does not need user interaction.
#
getNetworkReturns the network to which the wallet is connected.
#
getAddressesReturns the addresses of the accounts selected by accountIDs
. If undefined, returns the addresses of all accounts.
#
getNextAddressGenerate and persist in Marina a new external address for the current selected account.
ionioData
is expected if the current selected account is an Ionio account.
#
getNextChangeAddressGenerate and persist in Marina a new internal address for the current selected account.
ionioData
is expected if the current selected account is an Ionio account.
#
sendTransactionfeeAssetHash
is an optional parameter. The default value is the network's L-BTC asset hash.
If another asset hash is specified, Marina will use Liquid Taxi to pay fees. getFeeAssets lets to know the assets supported as feeAssetHash
.
#
blindTransactionblindTransaction is not implemented yet.
#
signTransactionMarina will try to sign all the inputs of the transaction if it knows the blinding and signing keys of the spent outpoint.
#
signMessageSign a message using the private key of the current selected account.
#
getCoinsReturns the UTXOs of the accounts selected by accountIDs
. If undefined, returns the UTXOs of all accounts.
Utxo
contains all the data to spend the input (witnessUtxo
, blindingData
and scriptDetails
).
#
getTransactionsReturns the transactions of the accounts selected by accountIDs
. If undefined, returns the transactions of all accounts.
#
getBalancesReturns the balances of the accounts selected by accountIDs
. If undefined, returns the balances of all accounts.
#
getFeeAssetsReturns the list of assets that can be used to pay transaction fees.
#
onReturns a string
unique ID using to identity the listener.
#
offoff
stops the listener identified by listenerId
.
#
Marina eventsMarina emits events when the wallet state changes. The user can capture these events using marina.on
, and cancel the listeners with marina.off
.
The callback's payload 'data' prop depends on event type:
#
NEW_UTXONEW_UTXO
is emitted when Marina fetches a new unspent output from explorer.
Event type | Payload type |
---|---|
"NEW_UTXO" | { accountID: string; data: UnblindedOutput } |
#
SPENT_UTXOSPENT_UTXO
is emitted when an unspent output has been spent by any transaction.
Event type | Payload type |
---|---|
"SPENT_UTXO" | { accountID: string; data: UnblindedOutput } |
#
NEW_TXNEW_TX
is emitted when Marina fetches a transaction from explorer.
Event type | Payload type |
---|---|
"NEW_TX" | {Â accountID: string; data: Transaction } |
#
ENABLEDENABLED
is emitted when the active hostname is enabled by the user.
Event type | Payload type |
---|---|
"ENABLED" | { data: { hostname: string; network: NetworkString } } |
#
DISABLEDDISABLED
is emitted when the active hostname is disabled by the user.
Event type | Payload type |
---|---|
"DISABLED" | { data: { hostname: string; network: NetworkString } } |
#
NETWORKThe NETWORK
event is emitted when the Marina's network config has changed.
Event type | Payload type |
---|---|
"NETWORK" | { data: NetworkString } (network name) |
#
Utils#
detectProviderThe detectProvider
function aims to fetch the providers injected by the browser extension.
Under the hood, the function listens the
providerName#initialized
event emitted by the browser extension script.
#
TypeScript specificationMarinaProvider : https://github.com/vulpemventures/marina-provider/blob/master/src/index.ts