starknet-url

StarkNet URL generator & parser.
Supporting common Ethereum URL standards such as ERC-681 and ERC-831.

This is a base standardizing lib to be used mainly by infrastructure devs/builders.
Use starknet-deeplink for easily generating StarkNet deeplinks - such as payment requests, dApp launching, and more.

Installation

using npm -

  npm install starknet-url

or yarn -

  yarn add starknet-url

Examples

Goerli ETH payment request:

import { STARKNET_ETH, StarknetChainId, transfer } from 'starknet-url'

const beneficiaryAddress = "0x123456789abcdef";
const url = transfer(beneficiaryAddress, {
    token: {
        token_address: STARKNET_ETH,
        chainId: StarknetChainId.GOERLI
    },
    amount: 0.02
})

// "starknet:0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7@0x534e5f474f45524c49/transfer?address=0x123456789abcdef&uint256=2e-2"

Add (listing) token request:

import { addToken, StarknetChainId } from 'starknet-url'


const url = addToken({
    token_address: "0x123456789abcdef",
    chainId: StarknetChainId.GOERLI,
});

// "starknet:0x123456789abcdef@0x534e5f474f45524c49/watchAsset?type=ERC20"

dApp launching request:

import { dapp } from 'starknet-url'


const url = dapp("https://example.com");

// "starknet:dapp-example.com"

Custom URI:

import { build, parse } from 'starknet-url'


// build a custom URI
const url = build({
    target_address: "0x12456789abcdef",
    function_name: "custom",
    chain_id: "0x13579",
    parameters: {
        "my": "custom",
        "function": "params",
    },
})
// "starknet:0x12456789abcdef@0x13579/custom?my=custom&function=params"

// parse a custom URI
const parsed = parse(url);
/*
    {
      schema: "starknet",
      target_address: "0x12456789abcdef",
      chain_id: "0x13579",
      function_name: "custom",
      parameters: { my: "custom", function: "params" }
    }
*/

API Reference

build (options: BuildOptions)

Build a StarkNet URI.
returns a URI string

Parameter	Type	Description
options	BuildOptions	Required. StarkNet URI build options

parse (uri: string)

Parse a StarkNet URI.
returns a ParseResult object

Parameter	Type	Description
uri	string	Required. StarkNet URI

transfer (to_address: string, options: TransferOptions)

Generate a transfer StarkNet URI, i.e. for a payment request.
returns a URI string

Parameter	Type	Description
to_address	string	Required. beneficiary address
options	TransferOptions	Required. defines a token to be used, and optionally the amount to be transferred

addToken (token: Token)

Generate a watchAsset StarkNet URI, for watching the given token (asset).
returns a URI string

Parameter	Type	Description
token	Token	Required. the token to be added (listed) by this watchAsset request

dapp (url: string)

Generate a dapp StarkNet URI, for launching a dApp in a StarkNet supporting browser client.
returns a URI string

Parameter	Type	Description
url	string	Required. dapp url

Types

BuildOptions

Parameter	Type	Description
target_address	string	Required. defines either the beneficiary of native token payment, or the contract address with which the user is asked to interact
prefix	string	Optional. defines the use-case for this URI
chain_id	string	Optional. defines the decimal chain ID, such that transactions on various test- and private networks can be requested
function_name	string	Optional. transfer, dapp, watchAsset, etc.
parameters	{ [key]: string }	Optional. defines extra parameters per use-case

ParseResult

Same as BuildOptions (per given URI use-case), plus schema which must always be starknet:

TransferOptions

Parameter	Type	Description
token	Token	Required. token to be used
amount	string or number	Optional. requested amount

Token

Parameter	Type	Description
token_address	string	Required. the token address
chainId	ChainId	Required. token address's chain ID

ChainId

Could be either StarknetChainId, string or a number (hex)

StarknetChainId

enum of common StarkNet chain IDs, such as -

    MAINNET = "0x534e5f4d41494e",
    GOERLI = "0x534e5f474f45524c49",
    GOERLI2 = "0x534e5f474f45524c4932",

Acknowledgements

This lib is inspired by the excellent Ethereum (L1) build/parse lib: eth-url-parser.

License

MIT

Related

starknet-deeplink - StarkNet deeplink generator