@shapeshiftoss/utils 1.1.1 → 1.2.0

package/dist/esm/index.d.ts

@@ -15,6 +15,8 @@ export * from './getChainShortName.js';
 export * from './getNativeFeeAssetReference.js';
 export * from './historyTimeframe.js';
 export * from './makeAsset/makeAsset.js';
+export * from './paymentUri/constants.js';
+export * from './paymentUri/paymentUri.js';
 export * from './promises.js';
 export * from './sha256.js';
 export * from './timeout.js';

package/dist/esm/index.js

@@ -15,6 +15,8 @@ export * from './getChainShortName.js';
 export * from './getNativeFeeAssetReference.js';
 export * from './historyTimeframe.js';
 export * from './makeAsset/makeAsset.js';
+export * from './paymentUri/constants.js';
+export * from './paymentUri/paymentUri.js';
 export * from './promises.js';
 export * from './sha256.js';
 export * from './timeout.js';

package/dist/esm/paymentUri/constants.d.ts

@@ -0,0 +1,3 @@
+import type { ChainId } from '@shapeshiftoss/caip';
+export declare const CHAIN_ID_TO_URN_SCHEME: Partial<Record<ChainId, string>>;
+export declare const URN_SCHEME_TO_CHAIN_ID: Partial<Record<string, ChainId>>;

package/dist/esm/paymentUri/constants.js

@@ -0,0 +1,26 @@
+import { arbitrumChainId, avalancheChainId, baseChainId, bchChainId, bscChainId, btcChainId, cosmosChainId, dogeChainId, ethChainId, gnosisChainId, ltcChainId, mayachainChainId, optimismChainId, polygonChainId, solanaChainId, thorchainChainId, tronChainId, zecChainId, } from '@shapeshiftoss/caip';
+export const CHAIN_ID_TO_URN_SCHEME = {
+    [ethChainId]: 'ethereum',
+    [arbitrumChainId]: 'arbitrum',
+    [optimismChainId]: 'optimism',
+    [polygonChainId]: 'polygon',
+    [bscChainId]: 'smartchain',
+    [avalancheChainId]: 'avalanchec',
+    [baseChainId]: 'base',
+    [gnosisChainId]: 'xdai',
+    [btcChainId]: 'bitcoin',
+    [bchChainId]: 'bitcoincash',
+    [dogeChainId]: 'dogecoin',
+    [ltcChainId]: 'litecoin',
+    [zecChainId]: 'zcash',
+    [thorchainChainId]: 'thorchain',
+    [cosmosChainId]: 'cosmos',
+    [mayachainChainId]: 'mayachain',
+    [solanaChainId]: 'solana',
+    [tronChainId]: 'tron',
+};
+export const URN_SCHEME_TO_CHAIN_ID = {
+    ...Object.fromEntries(Object.entries(CHAIN_ID_TO_URN_SCHEME).map(([chainId, scheme]) => [scheme, chainId])),
+    // The app emitted doge: QR codes for a year before adopting Dogecoin Core's scheme
+    doge: dogeChainId,
+};

package/dist/esm/paymentUri/paymentUri.d.ts

@@ -0,0 +1,7 @@
+import type { Asset } from '@shapeshiftoss/types';
+export type BuildPaymentUriArgs = {
+    address: string;
+    asset: Pick<Asset, 'assetId' | 'chainId' | 'precision'>;
+    amountCryptoPrecision?: string;
+};
+export declare const buildPaymentUri: (args: BuildPaymentUriArgs) => string;

package/dist/esm/paymentUri/paymentUri.js

@@ -0,0 +1,92 @@
+import { ASSET_NAMESPACE, CHAIN_NAMESPACE, fromAssetId, fromChainId } from '@shapeshiftoss/caip';
+import { BigAmount } from '../bigAmount/bigAmount.js';
+import { bn } from '../bignumber/bignumber.js';
+import { CHAIN_ID_TO_URN_SCHEME } from './constants.js';
+const toBaseUnit = (asset, amountCryptoPrecision) => BigAmount.fromPrecision({ value: amountCryptoPrecision, precision: asset.precision }).toBaseUnit();
+// EIP-681 encourages scientific notation, and writes it without the exponent's plus sign
+const toEip681Amount = (amountCryptoBaseUnit) => bn(amountCryptoBaseUnit).toExponential().replace('+', '').replace('e0', '');
+const buildEvmUri = ({ address, asset, amountCryptoPrecision }) => {
+    const target = `@${Number(fromChainId(asset.chainId).chainReference)}`;
+    const { assetNamespace, assetReference } = fromAssetId(asset.assetId);
+    // transfer(address,uint256) is erc20's alone, so erc721 and erc1155 get no amount
+    const takesAmount = assetNamespace === ASSET_NAMESPACE.slip44 || assetNamespace === ASSET_NAMESPACE.erc20;
+    if (!amountCryptoPrecision || !takesAmount)
+        return `ethereum:${address}${target}`;
+    const amount = toEip681Amount(toBaseUnit(asset, amountCryptoPrecision));
+    return assetNamespace === ASSET_NAMESPACE.erc20
+        ? `ethereum:${assetReference}${target}/transfer?address=${address}&uint256=${amount}`
+        : `ethereum:${address}${target}?value=${amount}`;
+};
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+// The same check as web3.js's PublicKey: base58 that decodes to exactly 32 bytes
+const isSolanaPublicKey = (address) => {
+    let value = 0n;
+    for (const char of address) {
+        const digit = BASE58_ALPHABET.indexOf(char);
+        if (digit === -1)
+            return false;
+        value = value * 58n + BigInt(digit);
+    }
+    const leadingZeroBytes = address.length - address.replace(/^1+/, '').length;
+    const significantBytes = value === 0n ? 0 : Math.ceil(value.toString(16).length / 2);
+    return leadingZeroBytes + significantBytes === 32;
+};
+const buildSolanaUri = ({ address, asset, amountCryptoPrecision }) => {
+    if (!amountCryptoPrecision)
+        return address;
+    if (!isSolanaPublicKey(address))
+        throw new Error(`Invalid Solana address: ${address}`);
+    // Solana Pay normalises the amount rather than passing it through verbatim
+    const amount = bn(amountCryptoPrecision).toFixed();
+    const { assetNamespace, assetReference } = fromAssetId(asset.assetId);
+    if (assetNamespace === ASSET_NAMESPACE.splToken) {
+        // Solana Pay takes decimal ui units, and the recipient is the native account, not its ATA
+        return `solana:${address}?amount=${amount}&spl-token=${assetReference}`;
+    }
+    return `solana:${address}?amount=${amount}`;
+};
+const buildTonUri = ({ address, asset, amountCryptoPrecision }) => {
+    if (!amountCryptoPrecision)
+        return address;
+    const { assetNamespace, assetReference } = fromAssetId(asset.assetId);
+    const amount = toBaseUnit(asset, amountCryptoPrecision);
+    // A jetton transfer names its master contract, and its amount is in the jetton's own units
+    if (assetNamespace === ASSET_NAMESPACE.jetton) {
+        return `ton://transfer/${address}?jetton=${assetReference}&amount=${amount}`;
+    }
+    return `ton://transfer/${address}?amount=${amount}`;
+};
+// BIP-21 takes decimal coin units
+const buildBip21Uri = ({ address, asset, amountCryptoPrecision }) => {
+    const scheme = CHAIN_ID_TO_URN_SCHEME[asset.chainId];
+    if (!amountCryptoPrecision || !scheme)
+        return address;
+    // CashAddr already carries its scheme
+    const target = address.startsWith(`${scheme}:`) ? address.slice(scheme.length + 1) : address;
+    return `${scheme}:${target}?amount=${bn(amountCryptoPrecision).toFixed()}`;
+};
+export const buildPaymentUri = (args) => {
+    const { asset, amountCryptoPrecision } = args;
+    if (amountCryptoPrecision) {
+        const amount = bn(amountCryptoPrecision);
+        if (!amount.isFinite() || amount.isNegative()) {
+            throw new Error(`Invalid payment amount: ${amountCryptoPrecision}`);
+        }
+        if ((amount.decimalPlaces() ?? 0) > asset.precision) {
+            throw new Error(`Payment amount ${amountCryptoPrecision} exceeds ${asset.precision} decimals`);
+        }
+    }
+    switch (fromChainId(args.asset.chainId).chainNamespace) {
+        case CHAIN_NAMESPACE.Utxo:
+        case CHAIN_NAMESPACE.CosmosSdk:
+            return buildBip21Uri(args);
+        case CHAIN_NAMESPACE.Evm:
+            return buildEvmUri(args);
+        case CHAIN_NAMESPACE.Solana:
+            return buildSolanaUri(args);
+        case CHAIN_NAMESPACE.Ton:
+            return buildTonUri(args);
+        default:
+            return args.address;
+    }
+};

package/dist/esm/paymentUri/paymentUri.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/paymentUri/paymentUri.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { buildPaymentUri } from './paymentUri.js';
+const asset = (assetId, chainId, precision) => ({
+    assetId,
+    chainId,
+    precision,
+});
+const BTC = asset('bip122:000000000019d6689c085ae165831e93/slip44:0', 'bip122:000000000019d6689c085ae165831e93', 8);
+const BCH = asset('bip122:000000000000000000651ef99cb9fcbe/slip44:145', 'bip122:000000000000000000651ef99cb9fcbe', 8);
+const ETH = asset('eip155:1/slip44:60', 'eip155:1', 18);
+const BASE_ETH = asset('eip155:8453/slip44:60', 'eip155:8453', 18);
+const USDC = asset('eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', 'eip155:1', 6);
+const FOX = asset('eip155:1/erc20:0xc770eefad204b5180df6a14ee197d99d808ee52d', 'eip155:1', 18);
+const SOL = asset('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/slip44:501', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 9);
+const WIF = asset('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', 6);
+const TON = asset('ton:mainnet/slip44:607', 'ton:mainnet', 9);
+const TON_USDT = asset('ton:mainnet/jetton:EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs', 'ton:mainnet', 6);
+const ATOM = asset('cosmos:cosmoshub-4/slip44:118', 'cosmos:cosmoshub-4', 6);
+const BTC_ADDRESS = 'bc1qar0srrr7xfkvy5l643lydnw9re59gtzz';
+const EVM_ADDRESS = '0xAbC0000000000000000000000000000000000001';
+const SOL_ADDRESS = 'GsbwXfJraMomNxBcjYLcG3mxkBUiyWXAB32fGbSMQRdW';
+const TON_ADDRESS = 'UQBFtnj3-yYK4p7XqXsyC5LNxfL2Rm5m0m3F0pvfDy7YQ9tk';
+describe('buildPaymentUri', () => {
+    it('builds a BIP-21 uri with a decimal coin amount', () => {
+        expect(buildPaymentUri({ address: BTC_ADDRESS, asset: BTC, amountCryptoPrecision: '0.05' })).toBe(`bitcoin:${BTC_ADDRESS}?amount=0.05`);
+    });
+    it('does not double-prefix a cashaddr that already carries its scheme', () => {
+        const address = 'bitcoincash:qr95sy3j9xwd2ap32xkykttr4cvcu7as4y';
+        expect(buildPaymentUri({ address, asset: BCH, amountCryptoPrecision: '1' })).toBe('bitcoincash:qr95sy3j9xwd2ap32xkykttr4cvcu7as4y?amount=1');
+    });
+    it('carries the chain id so an l2 deposit cannot be paid on mainnet', () => {
+        expect(buildPaymentUri({ address: EVM_ADDRESS, asset: BASE_ETH, amountCryptoPrecision: '2' })).toBe(`ethereum:${EVM_ADDRESS}@8453?value=2e18`);
+    });
+    it('targets the contract and moves the destination into the call for an erc20', () => {
+        expect(buildPaymentUri({ address: EVM_ADDRESS, asset: USDC, amountCryptoPrecision: '1.5' })).toBe(`ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48@1/transfer?address=${EVM_ADDRESS}&uint256=1.5e6`);
+    });
+    it('keeps every digit of a full-precision erc20 amount', () => {
+        expect(buildPaymentUri({
+            address: EVM_ADDRESS,
+            asset: FOX,
+            amountCryptoPrecision: '123.123456789012345678',
+        })).toBe(`ethereum:0xc770eefad204b5180df6a14ee197d99d808ee52d@1/transfer?address=${EVM_ADDRESS}&uint256=1.23123456789012345678e20`);
+        expect(buildPaymentUri({ address: EVM_ADDRESS, asset: USDC, amountCryptoPrecision: '0.000001' })).toBe(`ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48@1/transfer?address=${EVM_ADDRESS}&uint256=1`);
+    });
+    it('builds a Solana Pay uri with ui units', () => {
+        expect(buildPaymentUri({ address: SOL_ADDRESS, asset: SOL, amountCryptoPrecision: '1.5' })).toBe(`solana:${SOL_ADDRESS}?amount=1.5`);
+    });
+    it('names the mint and keeps the native account as recipient for an spl token', () => {
+        expect(buildPaymentUri({ address: SOL_ADDRESS, asset: WIF, amountCryptoPrecision: '0.1' })).toBe(`solana:${SOL_ADDRESS}?amount=0.1&spl-token=EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm`);
+    });
+    it('builds a ton transfer link in nanotons', () => {
+        expect(buildPaymentUri({ address: TON_ADDRESS, asset: TON, amountCryptoPrecision: '1.5' })).toBe(`ton://transfer/${TON_ADDRESS}?amount=1500000000`);
+    });
+    it('names the jetton master and uses the jetton units for a jetton', () => {
+        expect(buildPaymentUri({ address: TON_ADDRESS, asset: TON_USDT, amountCryptoPrecision: '5' })).toBe(`ton://transfer/${TON_ADDRESS}?jetton=EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs&amount=5000000`);
+    });
+    it('uses the cosmos sdk scheme', () => {
+        const address = 'cosmos1zqf0dq3nl3fhr8xk3pd2yq2sxwv0h2gd8qzptc';
+        expect(buildPaymentUri({ address, asset: ATOM, amountCryptoPrecision: '1' })).toBe(`cosmos:${address}?amount=1`);
+    });
+    it('falls back to the bare address on a chain with no scheme', () => {
+        const address = '0x04a1b2c3';
+        const starknet = asset('starknet:SN_MAIN/slip44:9004', 'starknet:SN_MAIN', 18);
+        expect(buildPaymentUri({ address, asset: starknet, amountCryptoPrecision: '1' })).toBe(address);
+    });
+    it('omits the amount from schemes that need one, but keeps the evm chain id', () => {
+        expect(buildPaymentUri({ address: BTC_ADDRESS, asset: BTC })).toBe(BTC_ADDRESS);
+        expect(buildPaymentUri({ address: SOL_ADDRESS, asset: SOL })).toBe(SOL_ADDRESS);
+        expect(buildPaymentUri({ address: TON_ADDRESS, asset: TON_USDT })).toBe(TON_ADDRESS);
+        expect(buildPaymentUri({ address: EVM_ADDRESS, asset: BASE_ETH })).toBe(`ethereum:${EVM_ADDRESS}@8453`);
+    });
+    it('passes a zero amount through', () => {
+        expect(buildPaymentUri({ address: BTC_ADDRESS, asset: BTC, amountCryptoPrecision: '0' })).toBe(`bitcoin:${BTC_ADDRESS}?amount=0`);
+        expect(buildPaymentUri({ address: EVM_ADDRESS, asset: ETH, amountCryptoPrecision: '0' })).toBe(`ethereum:${EVM_ADDRESS}@1?value=0`);
+    });
+    it('throws on a Solana address that is not a public key, as Solana Pay did', () => {
+        expect(buildPaymentUri({ address: 'not-a-pubkey', asset: SOL })).toBe('not-a-pubkey');
+        expect(() => buildPaymentUri({ address: 'not-a-pubkey', asset: SOL, amountCryptoPrecision: '1' })).toThrow('Invalid Solana address');
+        expect(() => buildPaymentUri({ address: `${SOL_ADDRESS}1`, asset: SOL, amountCryptoPrecision: '1' })).toThrow('Invalid Solana address');
+    });
+    it('writes a scientific-notation amount as a plain decimal', () => {
+        expect(buildPaymentUri({ address: BTC_ADDRESS, asset: BTC, amountCryptoPrecision: '1e-8' })).toBe(`bitcoin:${BTC_ADDRESS}?amount=0.00000001`);
+        expect(buildPaymentUri({ address: SOL_ADDRESS, asset: SOL, amountCryptoPrecision: '1e-9' })).toBe(`solana:${SOL_ADDRESS}?amount=0.000000001`);
+    });
+    it('throws on an amount finer than the asset', () => {
+        expect(() => buildPaymentUri({ address: BTC_ADDRESS, asset: BTC, amountCryptoPrecision: '0.000000001' })).toThrow('exceeds 8 decimals');
+        expect(() => buildPaymentUri({ address: EVM_ADDRESS, asset: USDC, amountCryptoPrecision: '0.0000001' })).toThrow('exceeds 6 decimals');
+    });
+    it('throws on an amount no wallet could pay', () => {
+        expect(() => buildPaymentUri({ address: BTC_ADDRESS, asset: BTC, amountCryptoPrecision: '-1' })).toThrow('Invalid payment amount');
+        expect(() => buildPaymentUri({ address: EVM_ADDRESS, asset: ETH, amountCryptoPrecision: 'abc' })).toThrow('Invalid payment amount');
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shapeshiftoss/utils",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "repository": "https://github.com/shapeshift/web",
   "license": "MIT",
   "type": "module",
@@ -25,8 +25,8 @@
     "bignumber.js": "^9.3.1",
     "dayjs": "^1.11.3",
     "lodash-es": "^4.17.23",
-    "@shapeshiftoss/caip": "^8.16.10",
-    "@shapeshiftoss/types": "^9.0.1"
+    "@shapeshiftoss/types": "^9.0.1",
+    "@shapeshiftoss/caip": "^8.17.0"
   },
   "devDependencies": {
     "@types/lodash-es": "^4.17.12"