@yoroi/links

Overview

This package provides type-safe way to create and parse cryptocurrency-related links based on its URI definition (ABNF). It is designed to support different types of operations. It supports Cardano operations such as claims and legacy transfers within its blockchain ecosystem. It also allows to interpret and build crypto links.

Features

• Custom URI Scheme Handling: Supports the 'web+cardano' URI scheme, tailored for Cardano blockchain interactions.
• Type-Safe Link Creation and Parsing: Utilizes TypeScript for ensuring the integrity and correctness of link structures.
• Configurable for Different Operations/Chains: Includes configurations for claim operations (configCardanoClaimV1) and legacy transfers (configCardanoLegacyTransfer), it can be extended.
• Yoroi Deep Links: Supports the 'yoroi' URI scheme, tailored for interation with Yoroi.

Installation

How to install the package, e.g., via npm or yarn:

npm install @yoroi/links
# or
yarn add @yoroi/links

Cardano Usage

Importing the Module

import {linksCardanoModuleMaker, configCardanoClaimV1} from '@yoroi/links'

How to create a link

const {create} = linksCardanoModuleMaker()

const cardanoLink = create({
  config: configCardanoClaimV1,
  params: {
    faucet_url: 'https://someendpoint/airdrop',
    code: 'CardanoSummit2024',
    other: 'other param',
  },
})

console.log(cardanoLink.link)

How to parse a link

const {parse} = linksCardanoModuleMaker()

const parsedLink = parse(
  'web+cardano://claim/v1?code=123&faucet_url=http://example.com',
)
console.log(parsedLink)

API reference

Interface

• create: Creates a crypto link based on the provided configuration and parameters.
• parse: Parses a given string into a Link object if supported, otherwise will throw.

Built-in configurations

• configCardanoClaimV1: Configuration for Cardano claim operations. CIP99
• configCardanoLegacyTransfer: Configuration for Cardano legacy transfers. CIP13

Supported Schemes and Authorities

| Scheme | Authority | Description | | ------------- | --------- | --------------------------------------- | | web+cardano | claim | Used for proof of onboarding / airdrops | | web+cardano | | Used for legacy payment requests |

Yoroi Usage

Important Yoroi uses in query string arrays as name[index], e.g whateverArray[0]=1&whateverArray[1]=

Importing the Module

import {
  linksYoroiModuleMaker,
  linksCardanoModuleMaker,
  configCardanoLegacyTransfer,
} from '@yoroi/links'

How to create a link

const {create} = linksCardanoModuleMaker()
const {transfer} = linksYoroiModuleMaker('yoroi')

const cardanoLink = create({
  config: configCardanoLegacyTransfer,
  params: {
    amount: 1,
    address: '$stackchain',
  },
})

const yoroiPaymentRequestWithAdaLink = transfer.request.adaWithLink({
  link: cardanoLink.link,
  business: 'exchange',
  partnerId: 'encryptus',
  authorization: 'uuid-v4',
  redirectTo: 'https://my.amazing.web/?amountRequested=1&session=03bf4dd213d',
})

console.log(yoroiPaymentRequestWithAdaLink)

Supported Schemes and Authorities

| Scheme | Authority | Path | Description | | --------------- | ------------------ | ---------- | ---------------------------------- | | yoroi https | yoroi-wallet.com | transfer | Used for requesting payments | | yoroi https | yoroi-wallet.com | exchange | Used for iteracting with exchanges | | yoroi https | yoroi-wallet.com | dapp | soon |

Testing the deep & universal links developing

# iOS
xcrun simctl openurl booted "https://yoroi-wallet.com/w1/transfer/request/ada?target[0]=%24stackchain"

# Android
adb shell am start -W -a android.intent.action.VIEW -d "yoroi://yoroi-wallet.com/w1/transfer/request/ada?amount=1&address=%24$stackchain"

Schemas

Yoroi validates deeplinks and univeral links in a stricted way, missing params is fine, will warn users, adding extra params will make Yoroi to ignore your request completely.

PartnerInfoSchema

This schema is designed for adding information about how Yoroi should behave, even though all are flagged as optional, it will change how Yoroi respondes to it, and for some funnels it might block the user, or trigger some red alerts about dangerous actions. It includes the following fields:

• isSandbox: A boolean indicating the environment, when true deeplinks only work on non-production builds.
• isTestnet: A boolean that restrics whether it should list only mainnet wallets or testnets wallets.
• appId: A string with a maximum length of 40 characters that identifies that app.
• redirectTo: Yoroi may present a link button or automatic redirect the user based on funnel.
• authorization: All actions initiated within Yoroi will provide an authorization, that works along with the wallet used.
• message: Yoroi may present this message for some actions, be descriptive and concise around the action needed from Yoroi, otherwise users might reject your request.
• walletId: As the authorization, when provided, is expected back. Otherwise just set isProduction so Yoroi will know how to ask users to open their right wallet.
• signature: Partner signature, it changes many behaviours inside Yoroi, specially regarding warning and dangerous messages.

ExchangeShowCreateResultSchema

This schema validates data for the creation result of a order to exchange coins, the link includes the following fields:

• coinAmount: The amount in the coin main denomination ie. Cardano ADA.
• coin: The coin ticker, Cardano ADA.
• fiatAmount: The amount of fiat currency.
• fiat: The fiat ticker, ie. USD.
• status: 'success' | 'failed' | 'pending' Indicates to Yoroi the message to display, if you need to include an explanation use the message param.
• It also merges all fields from PartnerInfoSchema.
• orderType: 'buy' | 'sell' The order type.

TransferRequestAdaSchema

This schema is for validating transfer requests of ADA and includes the following fields:

• targets: An array of objects (with a minimum of 1 and maximum of 5 elements) where each object contains:
  • receiver: A string with a maximum length of 256 characters, it can be a wallet address or any domain name for your wallet address.
  • datum (optional) A CBOR string with a maximum length of 1024 characters.
  • amounts: An array of objects (with a minimum of 1 and maximum of 10 elements) where each object contains:
    • tokenId: A string with a maximum length of 256 characters, represented by policyId and assetName in hex, separated by a ., for ADA both are valid . or empty string.
    • quantity: A string with a maximum length of 80 characters, atomic, Cardano Lovelaces.
• memo (optional): A string with a maximum length of 256 characters, stored in the wallet local storage wallet, it is not included in the transaction.
• It also merges all fields from PartnerInfoSchema.

TransferRequestAdaWithLinkSchema

This schema validates transfer requests that include a URL and has the following fields:

• link: A URL string with a maximum length of 2048 characters, it supports the CIP13 for Cardano legacy transfer, that can also be created by this module.

For more

• BIP-21
• EIP-681
• URI
• ABNF
• RFC-2234