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.

import { detectProvider } from 'marina-provider';
try {
const marina = await detectProvider('marina');
initApp(marina); // initialize your app
} catch (err) {
console.log('Please install Marina extension!');
}

Basics#

For 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
  • Detect which network the user is connected to (either liquid or regtest)
  • Get the user's Liquid addresses(s) and blinding keys

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#

Utils#

isEnabled#

marina.isEnabled(): Promise<boolean>

isReady#

marina.isReady(): Promise<boolean>

Returns true if the user has already set up a wallet.

enable#

marina.enable(): Promise<void>

disable#

marina.disable(): Promise<void>

getNetwork#

marina.getNetwork(): Promise<'liquid' | 'regtest'>

getAddresses#

marina.getAddresses(): Promise<AddressInterface[]>

getNextAddress#

marina.getNextAddress(): Promise<AddressInterface>

getNextChangeAddress#

marina.getNextChangeAddress(): Promise<AddressInterface>

sendTransaction#

marina.sendTransaction(recipients: Recipient[], feeAssetHash?: string ): Promise<TransactionHex>

feeAssetHash 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.

blindTransaction#

marina.blindTransaction(pset: PsetBase64): Promise<PsetBase64>;

signTransaction#

marina.signTransaction(pset: PsetBase64): Promise<PsetBase64>;

signMessage#

marina.signMessage(message: string): Promise<SignedMessage>;

getCoins#

marina.getCoins(): Promise<Utxo[]>;

getTransactions#

marina.getTransactions(): Promise<Transaction[]>;

getBalances#

marina.getBalances(): Promise<Balance[]>;

getFeeAssets#

marina.getFeeAssets(): Promise<string[]>;

Returns the list of assets that can be used to pay transaction fees.

on#

marina.on(type: MarinaEventType, callback: (payload: any) => void): EventListenerID;

Returns a string unique ID using to identity the listener.

off#

marina.off(listenerId: EventListenerID): void;

off stops the listener identified by listenerId.

Marina events#

Marina emits events when the wallet state is changing. The user can capture these events using marina.on, and cancel the listeners with marina.off.

The callback's payload type depends on event type

NEW_UTXO#

NEW_UTXO is emitted when Marina fetches a new unspent output from explorer.

Event typePayload type
"NEW_UTXO"Utxo
// print the utxo's txid each time Marina emits NEW_UTXO
marina.on("NEW_UTXO", (payload: any) => console.log((payload as Utxo).txid));

SPENT_UTXO#

SPENT_UTXO is emitted when an unspent output has been spent by any transaction.

Event typePayload type
"SPENT_UTXO"{ txid: string; vout: number; }
marina.on("SPENT_UTXO", (payload: any) => {
const { txid, vout } = payload;
console.log(`output with txid=${txid} and vout=${vout} has been spent`)
}

NEW_TX#

NEW_TX is emitted when Marina fetches a transaction from explorer.

Event typePayload type
"NEW_TX"Transaction
// print the tx's txid each time Marina emits NEW_TX
marina.on("NEW_TX", (u: any) => console.log((u as Transaction).txid));

ENABLED#

ENABLED is emitted when the active hostname is enabled by the user.

Event typePayload type
"ENABLED"undefined
marina.enable(); // this will open the enable popup. the user can accept or reject.
marina.on("ENABLED", () => console.log("the user has accepted"));

DISABLED#

DISABLED is emitted when the active hostname is disabled by the user.

Event typePayload type
"DISABLED"undefined
marina.on("DISABLED", () =>
console.log("the current hostname is now disabled")
);
marina.disable(); // this will emit a "DISABLED" event.

NETWORK#

The NETWORK event is emitted when the Marina's network config has changed.

Event typePayload type
"NETWORK"string (network name)
marina.on("NETWORK", (payload: string) => {
if (payload === "regtest") {
// the user has switched from "liquid" to "regtest".
console.log("regtest is boring");
}
});

Utils#

detectProvider#

The detectProvider function aims to fetch the providers injected by the browser extension.

const myProvider = await detectProvider<ProviderType>('providerName', 10000);
const marina = await detectProvider<MarinaProvider>('marina'); // default timeout = 3000

Under the hood, the function listens the providerName#initialized event emitted by the browser extension script.

TypeScript specification#

MarinaProvider : https://github.com/vulpemventures/marina-provider/blob/master/src/index.ts