@sprinkles-web3/client

Sprinkles Web3 Client for JS

Utility to interact with Sprinkles wallet.

User's interactions with their wallet and/or key will happen on the Sprinkles web app. App developers and Sprinkles will not have access to the user's private key. The result of the user's action will be sent to your app's callback endpoint, from the user's device. Use @sprinkles-web3/callback NPM package to parse the callback request.

Get started

npm install @sprinkles-web3/client

Sign up/in with Sprinkles

This utility will build Sprinkles /auth URL. When the user sign up/in, open this URL in a new window/popup. The user will interact with their wallet on that page.

You will need to provide a callbackUrl that will be invoked when the user completed the authentication. See @sprinkles-web3/callback to setup.

1. Your app will provide a globally unique session ID to be associated with the user's wallet address. Treat this ID as an opaque string. Consider using a secure generator such as nanoid.

npm install nanoid

2. Build the Sprinkles /auth URL using this utility.

3. Use this URL when the user is about to sign up/in.

Here is how the code should look:

import { authUrl, onClickOpenPopup } from '@sprinkles-web3/client'
import { nanoid } from 'nanoid'

// Static URL path to your domain. See NPM @sprinkles-web3/callback.
const callbackUrl = ...;

const sid = nanoid();
const sprinklesAuthUrl = authUrl(sid, callbackUrl);
const onClickHandler = onClickOpenPopup(sprinklesAuthUrl);

...
...

// Then when you render your page:
<a
  target={sprinklesAuthUrl.href}
  rel='popup'
  onClick={onClickHandler}
>
  Continue with your browser
</a>

Requesting user's information

App developers are able to request user's information via Sprinkles. The user can select which information they are consent to provide to the app developers.

To do so, provide the userItems parameter to authUrl() function.

...
...

const userItems: UserItemsRequest =  {
  verifiedEmailAddress: { required: true },
  verifiedPhoneNumber: { required: false },
};

const sprinklesAuthUrl = authUrl(
  sid,
  callbackUrl,
  userItems    // This is the user information being requested.
);

...
...

If the user consents, the information will be delivered along with their signature to your Sprinkles callback function. See @sprinkles-web3/callback.

const {
  address,
  rp,
  sid,
  signature,
  timestamp,
  data, // This is where the user information will be stored.
} = validateAuthCallback(requestBodyStr, {
  allowedRp: AllowedRelyingParty,
});

The data field will look as such:

{
  userItems: {
    verifiedEmailAddress: '[e-mail]',
    verifiedPhoneNumber: '[phone]'
  }
}

Sending a transaction with Sprinkles

This utility will build Sprinkles /send-tx URL. To ask the user to sign and send a transaction with Sprinkles, present a Send Transaction page using this URL. The user will interact with their wallet on that page.

You will need to provide a callbackUrl that will be invoked when the user completed the process. See @sprinkles-web3/callback to setup.

1. Your app will provide a globally unique session ID to be associated with the user's wallet address. Treat this ID as an opaque string. Consider using a secure generator such as nanoid.

npm install nanoid

2. Build the Sprinkles /send-tx URL using this utility.

3. Use this URL when the user is about to sign a transaction.

Here is how the code should look:

import {
  onClickOpenPopup,
  sendTxUrl,
  type EvmCreateTxInput
} from '@sprinkles-web3/client'
import { nanoid } from 'nanoid'

// Static URL path to your domain. See NPM @sprinkles-web3/callback.
const callbackUrl = ...;

const sid = nanoid();

const sendTxRequest: EvmCreateTxInput = {
  _type: 'EvmCreateTxInput',
  chainId: 1
  to: '0x000...',
  value: '10000000000000000000',
}

let sprinklesUrl;
try {
  sprinklesUrl = sendTxUrl(sid, callbackUrl, sendTxRequest);
} catch (e) {
  // Handle `SprinklesClientError`, likely due to an invalid `sendTxRequest`.
}

const onClickHandler = onClickOpenPopup(sprinklesUrl);

...
...

// Then when you render your page:
<a
  target={sprinklesUrl.href}
  rel='popup'
  onClick={onClickHandler}
>
  Send 1 ETH to James
</a>

Interacting with a smart contract

The most-preferred method of interacting with a smart contract is by passing an EvmContractInput to the EvmCreateTxInput.data field.

First, set the EvmCreateTxInput.to field as the address of the smart contract. For example, the address of USDC Token on Ethereum is 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48.

const contractAddress = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'

Next, select the smart contract function that you would like to execute, e.g. USDC contract functions.

Here is an example of EvmContractInput with USDC's transfer function.

import { type EvmContractInput } from '@sprinkles-web3/client'

const evmContractInput: EvmContractInput = {
  _type: 'EvmContractInput',
  fn: 'function transfer(address to, uint amount) returns (bool)'
  args: {
    to: '0x000...',
    amount: '10000000000000000000'
  }
}

Putting everything together, your EvmCreateTxInput should look like this:

const sendTxRequest: EvmCreateTxInput = {
  _type: 'EvmCreateTxInput',
  chainId: 1

  // USDC contract address, not the beneficiary of the `transfer` function.
  to: contractAddress,

  // You probably don't mean to transfer any ETH to the contract.
  // Make sure this is '0'.
  value: '0',

  // Pass the function and arguments to the data.
  data: evmContractInput
}

You can pass sendTxRequest to the sendTxUrl(...) like usual.

Contact

Discord

Email: [e-mail]