Card Pay Early Access Program Guide

The step-by-step guide to test the Card Pay protocol dApp and mobile wallet

UPDATE: You can now download the Card Wallet app directly; join our Discord to get the download link and test the app with the support of our community.

Thank you for applying to the early access program for Card Pay. If you were accepted into the beta program, you should have received an email with instructions on how to join our private Discord channel and request test tokens. This email will also contain an invite code to download the beta application using TestFlight on iOS. If you haven’t received this email and would like to join the program, please fill out this application form: https://cardstack.typeform.com/to/Oe1xtI8z. We will contact you when we expand the number of testers in the program.

To learn more about the Card Pay protocol — its motivation, technology, token economics, and components — we invite you to read this comprehensive Card Pay protocol paper: http://cardstack.com/cardpaypaper

Card Pay Protocol Family

The Card Pay protocol family consists of four core protocols:

1. Card Pay Protocol: This is the core payment protocol that allows customers to settle transactions using stablecoin and leverage an exchange rate to determine the price at the time of transaction.
2. Card Bridge Protocol: This is a layer 1 and layer 2 token bridge that bridges stablecoins and other community tokens to one of many layer 2 networks so that transaction fees for customer payments remain low. Merchants who earn layer 2 tokens can withdraw their earnings on Ethereum mainnet and, thus, swap or trade to the preferred crypto or fiat currency.
3. Card Reward: This protocol generates a rewards program where the administrator can distribute tokens or NFTs based on various on-chain activities such as spending, community participation, and various DAO memberships.
4. Card Commerce: This protocol allows merchants to create a product inventory priced on-chain that is capable of being delivered automatically to customers when payments are received.

These four protocols work together to bring decentralized commerce to the mainstream. We are launching the protocol family in phases, starting with the core payment protocol “Card Pay” and the layer 2 bridging protocol “Card Bridge.” To provide users of varied ability access to the protocol, we are launching a web-based dApp that walks users through the various steps necessary to participate in the protocol. To grant users control over their assets and allow them to securely sign transactions, we are releasing Card Wallet, a mobile application for iOS (and soon Android) that provides a convenient daily use app to interact with the protocol.

Design of the Beta Program

We have designed the Card Pay early access program to be an on-going early customer feedback program equipped with a steady rollout of new features and a comprehensive feedback collection system that allows our team to address technical and usability issues. Members of this program provide valuable service to the network by testing various applications in real-world situations and by providing suggestions for improvement in constructive ways.

The Card Pay protocol operates with a few different types of users in mind. During the initial launch, however, we will educate all members equally so they can perform a variety of actions across the user types. When this application is launched to the public, we expect each user group to utilize only a subset of the features. For example, customers using prepaid cards for merchandise would never have to interact with the high gas fees on mainnet. Instead, token suppliers will have already bridged various stablecoins and other community tokens in bulk ahead of time.

The five core user types are:

1. Token Suppliers: This user type deposits various tokens on mainnet and receives an equal number of tokens on the xDAI chain that can be sold or gifted to customers and merchants as fungible tokens.
2. Prepaid Card Issuer: An issuer packages the supply of layer 2 fungible tokens into Prepaid Cards. Customers can then buy these Prepaid Cards from the issuer by paying an additional small fee in exchange for preloaded balances.
3. Customers: Customers are not required to do any type of KYC. They need only a mobile wallet with an Ethereum address loaded with some funds. These funds can be used to not only pay the merchants but also to cover the on-chain transaction fees required by the xDAI chain. Customers can create multiple accounts (each with a different address) to segregate their purchases into the different spheres of their digital lives.
4. Merchant: Merchants have to set prices and list the products (SKUs) that they intend to offer in the network. They can also set discounts and bonuses to incentivize or disincentivize payments in different currencies. Merchants who only accept crypto payments that don’t touch any fiat rails do not need to go through KYC. Anybody can be a merchant as long as they fill out a merchant profile.
5. Reward Program Administrator: Merchants linked to a reward program will also act as Reward Program Administrators. They set reward ratios for certain categories of spend against certain products, including conditions like timeframes, limits, and qualifications. A Reward Program Administrator might offer a reward to VIP badge holders, for example. Anybody can establish a reward program. However, to do so, they must act as suppliers who onboard their own reward tokens or vouchers to the network by way of the layer 1 reward pool.

Each of the above user types engages with the same underlying protocol functionality, but sometimes through very different user interfaces. Customers, for example, need to use only the mobile app since we’ve worked to make the user experience as easy as operating a basic app that you might download from the app store. More advanced roles like prepaid card issuers and token suppliers, however, may interact with multiple blockchains and require the use of browser-based wallets like MetaMask.

The smart contract for the Card Pay and the Card Bridge protocol has already undergone one round of security audit and is currently undergoing another round, but it should be considered feature-complete.

We have developed a Card Pay SDK that grants developers easy access to to the capabilities of the Card Pay Protocol: https://github.com/cardstack/cardstack/tree/main/packages/cardpay-sdk

This provides developers with convenient methods to access prepaid Card balances, claim merchant earnings, track transaction history, and more. Most of the capabilities are already available in the Card Pay SDK. With this infrastructure in place, our development team has shifted their attention toward adding the various workflows and dashboards needed for each of the five user types.

Below is a table displaying the various functions supported by the protocol and our progress toward delivering an end-to-end experience for each of the user types. Please note that the table covers only Card Pay and Card Bridge. We will update this table with Card Reward and Card Commerce capabilities once the smart contracts underlying those protocols reach a steady state.

The first phase of the beta program will include all of the features ready to test. They are marked above with solid dots. Features that are currently missing some user interface elements will be rolled out continuously, either by pushing a new release through the Testflight account of the user or by pushing updates to the web app without any user intervention. We will communicate the details of our progress through the Discord channel as we unveil new features.

Setting Up Your Layer 2 Card Wallet

Let’s get started by installing the Card Wallet on your iOS device.

The beta version of the Card Wallet is not yet published on the app store but is available to download instead through a private distribution channel provided by Apple called TestFlight. If you have never participated in a private beta program, now is a good time to download TestFlight from the app store.

Once you have installed TestFlight, you can download the Card Wallet. If you’ve been invited to the beta program, you should have received an email invite that looks like this:

While viewing this email on your iOS device, click on the “View in TestFlight” button to open the app on TestFlight. Once you are in TestFlight, you should see a link to install the Card Wallet, which looks like the image below. (Make sure you have version 1.0.3 build or above.)

Once Card Wallet is installed, open it. Click on “Create a new account.”

Now, create a name for the account so that it can be easily identified in the future. This information is private and visible only to you. You may also change the color of the profile by tapping the colored circle above “Name your account.”

You have now created a new account containing a private key that belongs only to you. Funds created with this Card Wallet will be completely under your control.

If you’d like to further customize your account, you can upload a favorite picture or an avatar from your camera roll by tapping the circle here:

We are conducting the first segment of the beta program on testnets. Since Card Wallet is a layer 2 wallet, the testnet we are using is called Sokol. By default, Card Wallet is already configured to use Sokol. To ensure that you are on the correct Sokol testnet, click on the gear icon in the upper-right corner, put a tick on “Show testnets,” and select “Sokol.”

You are now ready to use the Card Wallet as your layer 2 wallet in support of the workflows that appear on the web-based dApp.

Getting Test Tokens on Layer 1

During this beta program, you will get to experience all of the different user types offered by the Card Pay protocol. For example, you will eventually assume the role of what’s called a token supplier. Token suppliers bridge stablecoins and other community tokens to layer 2 so that other users such as merchants and customers can conduct transactions on a much faster and cheaper network.

We are using the Kovan testnet as a stand-in for Ethereum mainnet during the beta program. Kovan testnet is supported by many popular Ethereum wallets. In this walk-through, we will assume that you have MetaMask already installed on your device. If preferred, you may use another layer 1 Web 3 wallet, such as Rainbow wallet.

You should now switch MetaMask to the Kovan testnets. There are two ways to change networks: 1) Go to Settings, Networks, and click “Kovan Test Network.” Or 2) Click on “Wallet” in the header and a network menu will open. Choose “Kovan Test Network.”

We recommend that you create a new account dedicated to testing the Card Pay protocol.

Don’t worry. We will provide the test tokens needed to exercise the functions of the protocol.

Once you have created this empty account, you should prepare the wallet so it is ready to receive three types of tokens:

1. Kovan ETH (KETH): this token allows you to pay the gas fees on layer 1 and the cost of the transaction fee for bridging and for withdrawal.
2. Kovan DAI (DAI): this stablecoin supports the prepaid card value used in the Card Wallet.
3. Kovan Cardstack Token (CARD): this is the main community reward token. It forms the basis of the reward Card features that will be released as the beta program evolves.

To receive the Kovan DAI and the Kovan Cardstack token on your MetaMask, please use the “Add Token” button.

Add DAI token to Kovan MetaMask by pasting the following address in Token Contract Address:

0x4f96fe3b7a6cf9725f59d353f723c1bdb64ca6aa

The Token Symbol and Token Decimal should automatically populate. Do not change these. You may now click “Next.”

You will now see a [X] DAI balance in your MetaMask wallet.

Next, we need to add CARD token to the Kovan MetaMask. You will again press “Add Token.” Add CARD token to Kovan MetaMask by pasting the following address in Token Contract Address:

0xd6e34821f508e4247db359cfcee0cb5e8050972a

Now request Kovan ETH, DAI, and CARD by pasting your Kovan address in the Cardstack Discord via #testnet-faucet.

This is most easily done by accessing Discord from the same device as your MetaMask. To copy the address, click the address on the homescreen. This will add your wallet address to the clipboard. Paste this address in the Discord channel #testnet-faucet.

This is a manual process that may take a few hours depending on whether someone is available to distribute the test tokens.

We will inform you of the tokens’ successful distribution through the appearance of an emoji checkmark. You should receive a standard allotment of 10 KETH, 500 DAI, 50000 CARD.

Double-check that you have received the Kovan ETH, Kovan DAI, and Kovan CARD in MetaMask. You will need these tokens to continue the beta program.

Becoming a Token Supplier

As a token supplier, you will bridge layer 1 tokens from your MetaMask and deposit them into your Card Wallet on layer 2. To do this, you must use the Card Pay dApp on a desktop web browser.

Using Google Chrome (recommended), go to the staging site provided in the #testnet-faucet channel.

This is the main dashboard for users of the Card Pay protocol. Since you are bridging tokens, click on the Token Suppliers tab and select “Deposit Tokens.”

You are now experiencing the Cardstack workflow system as it operates through a sequence of steps to perform complicated on-chain interactions. In this case, you are interacting simultaneously with a layer 1 wallet (MetaMask) and a layer 2 wallet (Card Wallet). Don’t worry if this sounds complicated. We will navigate this connection process step-by-step.

First, you need to connect the MetaMask account containing the test tokens to the dApp. To do this, click “Connect Wallet” on MetaMask. An authorization will appear. Accept it.

Congratulations! You have completed the first milestone.

Next, connect your layer 2 Card Wallet by scanning a QR code with the WalletConnect protocol. You can access the QR code scanning screen from the Card Wallet by swiping twice to the right. A screen reading “QR code reader” will appear.

Once you scan the QR code, the app will ask you to confirm the connection. Click “Connect.”

The top of the page will display your connection between the layer 1 Kovan wallet and the layer 2 Sokol wallet. You can always view connections and addresses by looking at the top right of the Card Pay dApp dashboard.

Card Protocol uses stablecoin as the unit of accounting for payment between customer and merchant, so we will need to bridge enough DAI from layer 1 to support the economic activity on the layer 2 networks. As a token supplier, you can bridge some of the Kovan DAI received from the Faucet channel. Let’s choose DAI and bridge 25 DAI.

Click “Unlock.” This will trigger a request from MetaMask. Please authorize the request. The Card Pay protocol will then be allowed to transfer the DAI into the reserve pool.

Click “Deposit.” This will complete the deposit and trigger the beginning of the bridging process.

You need to complete these two steps because ERC20 requires two transactions for sending tokens the first time. Again, don’t worry if this sounds overcomplicated. We have made this a one-step process in the layer 2 network by implementing the ERC677 standard.

From this point onward, the operation is completely automated. We are using a service called Arbitrary Message Bridge (AMB) to bridge the token across the two networks. You can track the progress of these activities in both the bridge and the Sokol testnet by clicking on these two links in the workflow.

When the bridged tokens are distributed to the Sokol network, you will receive a summary card displaying a confirmation of the bridging operation. It will look something like this:

The layer 1 token is now deposited in your Card Wallet. Go to your Card Wallet, and on the main account page, pull down to refresh. Check to see if the deposit appears. Please note that it may take some time to index as the node requires time to connect to other nodes.

What you’ve done here:

1. Connected 2 wallets to operate simultaneously on 1 dApp across 2 networks.
2. Use a token bridge to bridge layer 1 tokens to a layer 2 variant with a suffix CPXD that bears the same value as the layer 1 DAI, but with a much cheaper and faster transactional speed.
3. You are creating a smart contract wallet called a depot that holds these layer 2 assets, and you can utilize this wallet without having to pay gas fees via the local gas token xDAI.

Issue Prepaid Card

Before you start creating a prepaid card:

• Ensure that you have more than 30 DAI in your layer 2 Card Wallet. This should appear in your depot within the Card Wallet app.
• Make sure to bridge at least 200 DAI.
• You should still be connected to the Sokol testnet with your wallet. In case you are not connected anymore, you can disconnect and then connect again.

Click on the Card Balances tab. Click on the “Issue Prepaid Card” button.

Choose a layout and create an issuer name. The issuer name is any name that you choose to represent your brand. However, it shouldn’t contain any personal or identifiable information that you wish to keep private. Proceed with the flow as instructed.

Proceed with the flow and choose a Face Value from the available options. Then click “Set Face Value.”

When you click on “Confirm,” a confirmation prompt will be sent to Card Wallet. Confirm the prompt that appears.

A second prompt will be sent to the Card Wallet. Confirm the prompt.

You have now created a Prepaid Card that can be used to pay for products and services offered by other merchants on the Card Pay network. Since you are the issuer of this beautifully designed and customized Prepaid Card, you can create additional cards with the bridged token balance. You can also gift or sell the balance to acquaintances or customers.

You can check out how the Prepaid Card looks in your wallet by pulling down and refreshing the Prepaid Card balances.

You might even earn rewards as the Card issuer for facilitating commerce on the Card Pay network. We will tell you more about this later.

How to File a Bug

If you encountered a bug during the process, please take a screenshot and/or screen recording of the issue encountered. Please post the screenshot to our Discord channel and provide the information listed below in your message.

Description of Issue:

Steps to Replicate:

Device Used: (Please inform us of the specific iOS version and the browser used during the test.)

We will acknowledge the reported bug by placing an emoji checkmark on your message. We may ask for more details if we are unable to recreate the bug.

Thank you for participating in our beta program. We will be releasing new features of the app as operations stabilize, and we will regularly provide updates on our progress. Stay tuned for more announcements.