Building Meridian Pay: A Scalable Smart Wallet on Stellar

Meridian Pay was built as a web-based experience, accessible from any browser without installing an app. Users are able to pin the link to their home screen for easy access.

When designing Meridian Pay, we knew we needed an instantaneous and secure onboarding experience that eliminated one of blockchain’s biggest hurdles: key management. We believe users shouldn’t be expected to remember seed phrases or worry about storing credentials securely in order to use a blockchain wallet.

This led us to passkeys, which solve authentication with WebAuthn. Meridian Pay users never have to see or manage their private key, or worry about seed phrases or passwords. Instead, they can authenticate using familiar methods they already trust like Face ID, Touch ID, or their device PIN. This made Meridian Pay feel like any simple web2 product while everything under the hood happened onchain.

If you can manage opening your phone’s home screen, you can manage using a wallet like Meridian Pay.

A bit more on passkeys:

Passkeys are a cryptographically secure solution created by the FIDO Alliance to be phishing-resistant, and to sync across devices through cloud providers. Meridian Pay uses passkeys for both initial login and signing transactions. If a user were to lose their device, they could reauthenticate using their cloud-synced passkey or an event-specific email recovery mechanism. This helped us prioritise speed, safety, and simplicity in the Meridian Pay design.

Here’s how it works:

1. Setup: When a user creates an account, the device generates a passkey keypair and the wallet contract stores the public key as its signer

2. Transaction Initiation: The user initiates a transaction (ex: to claim an NFT or make a payment) and the frontend constructs a WebAuthn challenge to be signed

3. Authentication: The device prompts the user for Face ID, Touch ID, or PIN and signs the challenge, creating an assertion

4. Verification: The account contract verifies the assertion’s signature against the stored public key for that user

5. Authorization and Execution: If valid, the transaction executes onchain

To the user, this looks like scanning a QR code, tapping a link, and authenticating with Face ID, with near-instant confirmation. In reality, those taps trigger wallet creation or transactions, fee sponsorship, and onchain contract execution all within a few seconds.

Meridian Pay relied on Stellar smart contracts for programmable wallet behavior. Here's a little more on what was happening behind-the-scenes.

Account contract with passkey authentication

Each user's wallet was managed with an Account Contract, which defined how authentication and recovery worked. The Meridian Pay Account Contract acted as a programmable wallet that authorized user actions based on WebAuthn credentials, rather than static keys. Traditional Stellar accounts use a static ed25519 keypair for authorization. Smart wallets go a step further: they can implement custom authentication logic through a special contract function called __check_auth that validates WebAuthn signatures. When a user first sets up their wallet, their passkey's public key is registered in the Account Contract, allowing future transactions to be signed via biometrics or device PIN and validated on-chain.

This made wallets seedless, recoverable, and designed to be phishing-resistant. If a user lost their device, they could reauthenticate via a cloud-synced passkey or an event-specific email recovery flow.

For Meridian Pay, recovery was done by authorizing two distinct servers to sign jointly (multi-sig) in order to recover the account. However, lost passkeys can be replaced in multiple ways. In practice, smart wallets can define any logic they want for recovery, including recovery passphrases, distributed multi-sig services, hard wallet signers, etc.

Multicall contract: bundled transactions

For developers used to bundling operations into a single transaction on Stellar, the constraint of only being able to execute a single contract invocation at a time may seem foreign. We knew Meridian Pay users would need to perform multiple actions at once and did not want to sacrifice user experience by making them sign with their passkey for each individual action.

Enter: the Multicall Contract. Based on Creit Tech's Stellar Router Contract, the Multicall Contract allows multiple contract invocations to execute in a single on-chain transaction. The contract validates authentication, then executes all bundled actions atomically. This allowed us to bundle multiple contract invocations into a single transaction, with the user authenticating one time and all actions being executed at once on-chain.

This was used for actions like redeeming multiple swag items in a single transaction or transferring many NFTs at once. It improved both performance and user experience, reducing multiple round-trips to a single blockchain interaction.

Merkle distributor: efficient bulk claims

To support large-scale distributions, Meridian Pay also included a Merkle Distributor Contract. We built this contract to facilitate sending tokens to thousands of people in a single moment, without collecting their addresses in advance, as a total surprise to the receivers. This allowed for a special moment on stage at Meridian when Stellar Development Foundation CEO and Executive Director Denelle Dixon announced in her opening keynote that all attendees could open their phones to claim 500 XLM with Meridian Pay. Attendees went to the Meridian Pay website and were prompted to claim their XLM with their passkey. They immediately received the XLM in their wallet. The best part? The engineering team wasn't managing or monitoring 1000 separate transactions. All the administrative work had been done in advance. The Merkle tree with eligible addresses had been set up early, even before attendees created their Meridian Pay wallets, and operated smoothly as attendees verified and claimed their tokens.

This was possible because contract addresses are not random keypairs. They are deterministically derived from the deployer address and a salt. For Meridian Pay, we used registered email addresses as the salt, meaning we could calculate every attendee's wallet address before the wallet was created and without any interaction with users. This allowed us to confidently set up a Merkle Tree of wallet addresses for the mass distribution.

Generally, Merkle Trees let you prove a value is on a list without storing the entire list. You store the root hash onchain, enabling minimal storage costs, and then users prove eligibility by submitting a cryptographic "receipt" (a Merkle proof) to claim funds. The contract is pre-funded, which allows receivers to claim en masse or asynchronously on their own time. Unclaimed tokens stay in the contract and can be clawed back after a certain time period, which prevents sending tokens into inactive addresses. Using this structure allows for turbocharged distributions with almost no limit on the number of people you can pay at once.

The combination of efficient scalability, lightweight user participation, hands-off administration, and the protection of unused funds makes Merkle Tree contracts ideal for controlled distributions. We used Merkle Trees for distributing XLM and SWAG tokens when users participated in a selfie machine activation by Checkpoint and Refraction that was at Meridian on-site. However, the sky is the limit. Whether initiating airdrops, rewards, or even something like aid distributions to people affected by disasters, using a Merkle Tree to manage payments onchain can help you distribute efficiently to the correct receivers with minimal costs and administrative overhead.