Skip to content

myBraavos/starknet-url

Repository files navigation

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

Releases

No releases published

Packages

No packages published