Payroll

This usecase explains how to implement private payroll.

Actors

In this usecase, we explain a triparty system handling private transfers for contractor payouts and payroll.

Payroll SaaS

The Software that exposes the private payments to their ‘users’, which are CFOs running payroll. The Payroll SaaS has a website and manages company accounts.

The Payroll SaaS does not hold funds for their users. Instead they use a multisig to manage their funds.

Sender

Recipient

Requirements

For this usecase we ensure the following requirements hold:

1. Recipients cannot see salaries of other recipients.
2. Recipients cannot see Sender funds (cold or hot wallets).
3. Sender can track payments.
4. Payroll SaaS can display payment success.

Effectively we do not want employees to know what their colleagues are being paid, nor how much money the company has.

Note

Although the payments are private, the party constructing the transfer (in this case the Payroll Saas), knows the individual payments, as if they were regular ERC-20 transfers.

Workflow

We’ll use Union Private Payments to implement the following protocol.

1. The Sender provides Recipients to the Payment SaaS (through their UI or API).
2. The Payment SaaS generates unsigned transaction.
3. The Payment SaaS requests the Sender to sign the unsigned transaction.
4. The Payment SaaS submits the transaction on behalf of the Sender.
5. The Payment SaaS monitors progress.
6. (optionally) The Payment SaaS can send a notification to the recipient/update their dashboard.
7. The Payment SaaS submits the redemption transaction.
8. The Recipient has access to the funds.

With this workflow, we ensure compliance and that the Sender always has a full overview of transactional data. The Payment SaaS can choose to KYC recipients depending on their regulatory need.

Code

Here we have an example implementation of the above protocol. This abstraction use viem to initialize the clients.

import { Domain } from "@unionlabs/payments";
import {
  Attestor,
  EvmWalletClient,
  Payment,
  Prover,
} from "@unionlabs/payments/promises";
import * as Viem from "viem";
import * as ViemAccounts from "viem/accounts";
import * as ViemChains from "viem/chains";

declare const privateKey: `0x${string}`;
declare const privateKey2: `0x${string}`;
// Make sure to replace this with your own RPC url.
declare const BASE_RPC: string;
declare const ASSET_ADDRESS: Domain.Erc20Address;
declare const BASE_UNIVERSAL_CHAIN_ID: Domain.UniversalChainId;
declare const BENEFICIARY: Domain.Erc20Address;


/**
 * The wallet controlled by the sender. This could be constructed
 * in the UI of the SaaS product.
 */
const senderWallet = await EvmWalletClient.fromViem(
  Viem.createWalletClient({
    account: ViemAccounts.privateKeyToAccount(privateKey),
    chain: ViemChains.base,
    transport: Viem.http(BASE_RPC),
  }),
);

/**
 * This wallet is used on the backend of the SaaS.
 */
const saasWallet = await EvmWalletClient.fromViem(
  Viem.createWalletClient({
    account: ViemAccounts.privateKeyToAccount(privateKey2),
    chain: ViemChains.base,
    transport: Viem.http(BASE_RPC),
  }),
);

/**
 * This is a test API_KEY.
 * Feel free to use it for test integrations, but it is not suitable for production usage.
 */
const ATTESTOR_KEY =
  "6af6f8068d38ebf6666b8db98f9b8b42959ab62646764bc290e663f7abb49eea";

// The wallet client is run on the backend of the SaaS.
// const paymentClient = Client.make({
//   rpcUrl: new URL(BASE_RPC),
//   assetAddress: ASSET_ADDRESS,
//   chainId: 8453n,
//   attestorApiKey: ATTESTOR_KEY,
//   proverUrl: "http://localhost:50051"
// });

/**
 * Attestation service is run on the backend of the Saas.
 */
const attestor = await Attestor.make({
  apiKey: ATTESTOR_KEY,
  baseUrl: "http://localhost:50051",
});

/**
 * Prover service is run on the backend of the Saas.
 */
const prover = await Prover.make({
  proverUrl: "http://localhost:50052",
});

/**
 * The `paymentKey` is generated by the SaaS and optionally shared with the
 * **sender**. Store this securely to ensure transfers are inspectable later.
 */
const paymentKey = await Payment.generateKey();

/**
 * Beneficiaries are provided by the **sender** ahead of time.
 * This is the address of the **recipient**.
 */
const beneficiaries = [
  Domain.Erc20Address("0x123"),
  /* ... */
];

const depositAddress = await Payment.getDepositAddress({
  paymentKey,
  beneficiaries,
  destinationChainId: BASE_UNIVERSAL_CHAIN_ID,
});

/**
 * The Payroll SaaS creates the deposit parameters and sends
 * the prepared tx to be signed and sent by the sender.
 */
const depositResult = await Payment.prepareDeposit({
  depositAddress,
  amount: 1n,
  sourceWalletClient: saasWallet,
  srcErc20Address: ASSET_ADDRESS,
  destinationChainId: BASE_UNIVERSAL_CHAIN_ID,
});

/**
 * Nullifier is computed by the owner of the payment key.
 */
const nullifier = await Payment.getNullifier({
  destinationChainId: BASE_UNIVERSAL_CHAIN_ID,
  paymentKey,
});

/**
 * Proof generation is run on the backend of the SaaS.
 */
const proof = await Payment.generateProof({
  paymentKey,
  depositAddress,
  nullifier,
  amount: 1n,
  clientIds: [5],
  beneficiary: BENEFICIARY,
  selectedClientId: 5,
  srcChainId: BASE_UNIVERSAL_CHAIN_ID,
  srcErc20Address: ASSET_ADDRESS,
  dstErc20Address: ASSET_ADDRESS,
  publicClient,
  sourcePublicClient: publicClient,
  destinationPublicClient: publicClient,
  prover,
});

const attestation = await attestor.get({
  unspendableAddress: depositAddress.zAssetAddress,
  beneficiary: BENEFICIARY,
});

/**
 * To finalize the payment, redeem must be called. This ensures the funds arrive
 * unwrapped in the account of the **recipient**. If the recipients wants to receive
 * private assets and unwrap themselves, this does not need to be called, but the
 * `paymentKey` needs to be shared with the recipient.
 */
const preparedRedemption = await Payment.prepareRedemption({
  proof,
  dstErc20Address: ASSET_ADDRESS,
  attestation,
  destinationWalletClient: senderWallet,
  // @annotate: of the destination
  universalChainId: BASE_UNIVERSAL_CHAIN_ID,
});

const submittedRedemption = saasWallet.signAndSubmit(preparedRedemption);
const submittedRedemption: Promise<{
    readonly _tag: "SubmissionEvm";
    readonly hash: Domain.TxHash;
}>

Conclusion

With the above protocol, we ensure all requirements from the workflow are accomplished. Companies ensure that their employees cannot see origin of funds, or salaries being paid out to their colleagues, while regular accounting tools can provide exactly the same experience as with regular transfers. In the backend, we need to introduce 1 additional onchain transaction in the payment flow, although if contractors choose to receive private assets, this can be omitted.