@albedo-link/intent

Intent interface module for Albedo

This library is a lightweight browser wrapper for Albedo API that provides a promise-based interface for all supported intents.

Installation

npm i -S @albedo-link/intent

Usage

Setup

import albedo from '@albedo-link/intent'

Intents

Intent public_key

Requests account public key. It's a simple way of authentication for Stellar-based applications. The response ensures that a user owns the corresponding secret key.

Parameters

• token - (optional) Verification token generated by the application (should be unique or random).

Returns

• pubkey
• signed_message
• signature

Example

albedo.publicKey({
    token: 'r9gbUuThXLr/wOrg2dxWHOO4DQsvQsTpkv1OtfETB3c='
})
    .then(res => console.log(res))

Intent sign_message

Requests arbitrary message signing. Can be used to implement identity/ownership verification.

Parameters

• message - (required) Text message to sign.
• pubkey - (optional) Specific public key requested by the application.

Returns

• pubkey
• message
• original_message
• message_signature

Example

albedo.signMessage({
    message: 'Alice doesn\'t trust Bob'
})
    .then(res => console.log(res))

Intent tx

Requests a signature for the transaction. Returns signed transaction envelope that can be submitted to the network or used for multi-sig coordination.

Parameters

• xdr - (required) XDR-encoded transaction envelope to sign.
• pubkey - (optional) Specific public key requested by the application.
• network - (optional) Stellar network identifier or private network passphrase.
• horizon - (optional) The URL of the Horizon server.
• callback - (optional) Optional URL callback where signer will POST signed transaction XDR instead of submitting it to Horizon.
• submit - (optional) If set, the signed transaction will be submitted to the Horizon server instead of returning it to the application.

Returns

• xdr
• signed_envelope_xdr
• pubkey
• tx_signature
• network
• submit

Example

albedo.tx({
    xdr: 'AAAAALPZeTF.......B0dpb99l'
})
    .then(res => console.log(res))

Intent pay

Requests a payment from a user. Works with any Stellar asset, supports transaction memo.

Parameters

• amount - (required) Requested payment amount.
• destination - (required) Payment destination.
• asset_code - (optional) Asset code (skip for XLM).
• asset_issuer - (optional) Asset issuer (skip for XLM).
• memo - (optional) Transaction memo (required for exchanges and some anchors).
• memo_type - (optional) Transaction memo type.
• pubkey - (optional) Specific public key requested by the application.
• network - (optional) Stellar network identifier or private network passphrase.
• horizon - (optional) The URL of the Horizon server.
• callback - (optional) Optional URL callback where signer will POST signed transaction XDR instead of submitting it to Horizon.
• submit - (optional) If set, the signed transaction will be submitted to the Horizon server instead of returning it to the application.

Returns

• amount
• destination
• asset_code
• asset_issuer
• memo
• memo_type
• signed_envelope_xdr
• pubkey
• tx_signature
• network
• horizon

Example

albedo.pay({
    amount: '5',
    asset_code: 'EURT',
    asset_issuer: 'GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S'
})
    .then(res => console.log(res))

Intent trust

Requests permission to create a trustline to a given Stellar asset. Gradually simplifies the process of creating trustlines for anchors, ICOs, and airdrops.

Parameters

• asset_code - (required) Trustline asset code.
• asset_issuer - (required) Trustline asset issuer address.
• limit - (optional) Trust limit.
• memo - (optional) Transaction memo (required for exchanges and some anchors).
• memo_type - (optional) Transaction memo type.
• pubkey - (optional) Specific public key requested by the application.
• network - (optional) Stellar network identifier or private network passphrase.
• horizon - (optional) The URL of the Horizon server.
• callback - (optional) Optional URL callback where signer will POST signed transaction XDR instead of submitting it to Horizon.
• submit - (optional) If set, the signed transaction will be submitted to the Horizon server instead of returning it to the application.

Returns

• asset_code
• asset_issuer
• limit
• memo
• memo_type
• signed_envelope_xdr
• pubkey
• tx_signature
• network
• horizon

Example

albedo.trust({
    asset_code: 'EURT',
    asset_issuer: 'GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S'
})
    .then(res => console.log(res))

Intent exchange

Requests permission to buy tokens on Stellar DEX at market price.

Parameters

• sell_asset_code - (optional) Asset code of the asset to sell.
• sell_asset_issuer - (optional) Issuer account of the asset to sell.
• buy_asset_code - (optional) Asset code of the asset to buy.
• buy_asset_issuer - (optional) Issuer account of the asset to buy.
• amount - (required) The amount of asset to buy.
• max_price - (required) Maximum price the user willing to pay.
• memo - (optional) Transaction memo (required for exchanges and some anchors).
• memo_type - (optional) Transaction memo type.
• pubkey - (optional) Specific public key requested by the application.
• network - (optional) Stellar network identifier or private network passphrase.
• horizon - (optional) The URL of the Horizon server.
• callback - (optional) Optional URL callback where signer will POST signed transaction XDR instead of submitting it to Horizon.
• submit - (optional) If set, the signed transaction will be submitted to the Horizon server instead of returning it to the application.

Returns

• amount
• max_price
• sell_asset_code
• sell_asset_issuer
• buy_asset_code
• buy_asset_issuer
• memo
• memo_type
• signed_envelope_xdr
• pubkey
• tx_signature
• network
• horizon

Example

albedo.exchange({
    sell_asset_code: 'USD',
    sell_asset_issuer: 'GDUKMGUGDZQK6YHYA5Z6AY2G4XDSZPSZ3SW5UN3ARVMO6QSRDWP5YLEX',
    buy_asset_code: 'EURT',
    buy_asset_issuer: 'GAP5LETOV6YIE62YAM56STDANPRDO7ZFDBGSNHJQIYGGKSMOZAHOOS2S',
    amount: '5',
    max_price: '3.5'
})
    .then(res => console.log(res))

Intent implicit_flow

Requests temporary access token for one or more intents that can be used to execute actions without explicit confirmation from the user. In order to be executed implicitly, an implicit flow permissions for a given intent should be granted and "pubkey" parameter set.

Parameters

• intents - (required) Requested intents for the implicit flow.
• network - (optional) Stellar network identifier or private network passphrase.

Returns

• granted
• intents
• grants
• session
• pubkey
• network
• valid_until

Example

albedo.implicitFlow({
    intents: 'tx,pay,trust,sign_message'
})
    .then(res => console.log(res))

Implicit session utils

Collection of helpers to simplify various operations in the implicit mode.

isImplicitSessionAllowed(intent, pubkey)

Checks whether an implicit session has been granted earlier for an intent + pubkey pair.

Parameters

• intent - (required) Intent to check.
• pubkey - (required) Public key of the account which granted access.

Returns

• true/false

Example

const isAllowed = albedo.isImplicitSessionAllowed(
    'tx', 
    'GBQW4KLMRXIMSDWBEWX4AWQKWYW7R3E7SFPSHTUDTFFT22NNUC6COL72'
)

listImplicitSessions()

Enumerates all currently active implicit sessions.

Returns

• An array of active session descriptors.

Example

for (let session of albedo.listImplicitSessions()){
    console.log(session.pubkey, session.valid_until, session.grants)
}

forgetImplicitSession(pubkey)

Revokes session permission granted for an account.

Parameters

• pubkey - (required) Public key of the account which granted access.

Example

const pubkey = 'GBQW4KLMRXIMSDWBEWX4AWQKWYW7R3E7SFPSHTUDTFFT22NNUC6COL72'
albedo.forgetImplicitSession(pubkey)
console.log(albedo.listImplicitSessions().some(s => s.pubkey === pubkey))

Development

To create UMD library bundle run the following NPM script:

npm run build-app

It will also automatically update examples and parameters definitions for all available intents.