Integrating Ground gtokens with Privy

npm install @privy-io/node viem
npm install -D typescript tsx @types/node

export GROUND_BASE_URL="https://sandbox.groundtech.co"
export GROUND_API_KEY="<your-sandbox-api-key>"
export PRIVY_APP_ID="<your-privy-app-id>"
export PRIVY_APP_SECRET="<your-privy-app-secret>"
export PRIVY_AUTHORIZATION_PRIVATE_KEY="<base64-PKCS8-developer-signer-key>"
export SEPOLIA_RPC_URL="<your-sepolia-rpc-url>"

addSigners({
  address: userWalletAddress,
  signers: [{signerId: quorumId, policyIds: [groundPolicyId]}]
});

import {PrivyClient, isEmbeddedWalletLinkedAccount} from '@privy-io/node';
const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});
// Obtain these from the authenticated request, not a global wallet setting.
const idToken = '<Privy identity token from request>';
const selectedWalletId = '<selected user wallet ID from request>';
// Verify the identity token before accepting a wallet ID from the request.
const user = await privy.users().get({id_token: idToken});
// Reject wallets that are not linked to this authenticated user.
const linkedWallet = user.linked_accounts
  .filter(isEmbeddedWalletLinkedAccount)
  .find((account) => account.id === selectedWalletId && account.chain_type === 'ethereum');
if (!linkedWallet) throw new Error('Selected wallet does not belong to the authenticated user');
const wallet = await privy.wallets().get(selectedWalletId);
// Authorize Privy requests with the developer signer the user added to their wallet.
const authorizationContext = {
  authorization_private_keys: [process.env.PRIVY_AUTHORIZATION_PRIVATE_KEY!]
};
const baseUrl = process.env.GROUND_BASE_URL!;
const headers = {Authorization: `Bearer ${process.env.GROUND_API_KEY!}`};
const response = await fetch(`${baseUrl}/v2/gvaults/yield-sources`, {headers});
if (!response.ok) throw new Error(`Discovery failed: ${response.status}`);
const {data: sources} = await response.json();
// Discover addresses from the catalogue instead of hardcoding the vault.
const source = sources.find(
  (row: {interface: string; chain: string}) =>
    row.interface === 'ground_ustb_v1' && row.chain === 'ethereum_sepolia'
);
if (!source) throw new Error('gUSTB is unavailable');

const accessUrl = `${baseUrl}/v2/gvaults/${encodeURIComponent(source.id)}/allowlist/${encodeURIComponent(wallet.address)}`;
// Ground supplies the exact typed data and expiry for this wallet and source.
const challengeResponse = await fetch(`${accessUrl}/authorization`, {headers});
if (!challengeResponse.ok) throw new Error(`Challenge failed: ${challengeResponse.status}`);
const challenge = await challengeResponse.json();
// Sign as the user wallet through its authorized developer signer; no onchain transaction yet.
const {signature} = await privy
  .wallets()
  .ethereum()
  .signTypedData(wallet.id, {
    authorization_context: authorizationContext,
    params: {
      typed_data: {
        domain: challenge.typedData.domain,
        types: challenge.typedData.types,
        primary_type: 'Admission',
        message: challenge.typedData.value
      }
    }
  });
const ownershipProof = {issuedAt: challenge.issuedAt, expiresAt: challenge.expiresAt, signature};
const submitted = await fetch(accessUrl, {
  method: 'PUT',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({ownershipProof})
});
if (!submitted.ok) throw new Error(`Allowlisting failed: ${submitted.status}`);
// Submission can be pending. Continue only once allowed is true; otherwise poll this GET.
const checked = await fetch(accessUrl, {headers});
if (!checked.ok) throw new Error(`Access check failed: ${checked.status}`);
const {allowed, status} = await checked.json();

import {
  createPublicClient,
  http,
  encodeFunctionData,
  erc20Abi,
  parseUnits,
  type Abi,
  type Address,
  type Hex
} from 'viem';
import {sepolia} from 'viem/chains';
import deployedAbi from './ground-ustb-abi.json';
const publicClient = createPublicClient({
  chain: sepolia,
  transport: http(process.env.SEPOLIA_RPC_URL!)
});
const owner = wallet.address as Address;
const vault = source.contractAddress as Address;
const asset = source.asset.contractAddress as Address;
const vaultAbi = deployedAbi as Abi;
// Convert 10 USDC to integer token units using the catalogue decimals.
const assets = parseUnits('10', source.asset.decimals);
// Confirm the vault accepts the asset we are about to approve.
const onchainAsset = (await publicClient.readContract({
  address: vault,
  abi: vaultAbi,
  functionName: 'asset'
})) as Address;
if (onchainAsset.toLowerCase() !== asset.toLowerCase())
  throw new Error('Deposit asset does not match catalogue');
// Reuse this helper for approval, deposit and redemption from the same user wallet.
async function send(to: Address, data: Hex) {
  const {hash} = await privy
    .wallets()
    .ethereum()
    .sendTransaction(wallet.id, {
      authorization_context: authorizationContext,
      caip2: 'eip155:11155111',
      params: {transaction: {to, data, value: '0x0'}}
    });
  // Persist hash before waiting; reconcile it before retrying.
  const receipt = await publicClient.waitForTransactionReceipt({hash: hash as Hex});
  if (receipt.status !== 'success') throw new Error('Transaction reverted');
  return receipt;
}
// Allow the vault to spend only the deposit amount, rather than an unlimited allowance.
await send(
  asset,
  encodeFunctionData({abi: erc20Abi, functionName: 'approve', args: [vault, assets]})
);

// Simulate first to catch current contract reverts before submitting.
await publicClient.simulateContract({
  account: owner,
  address: vault,
  abi: vaultAbi,
  functionName: 'deposit',
  args: [assets, owner]
});
// The second argument is the receiver: gUSTB shares stay in the user wallet.
const depositReceipt = await send(
  vault,
  encodeFunctionData({
    abi: vaultAbi,
    functionName: 'deposit',
    args: [assets, owner]
  })
);

// Read every balance at the same block for a consistent snapshot.
const blockNumber = await publicClient.getBlockNumber();
const read = (functionName: string, args: readonly unknown[] = [owner]) =>
  publicClient.readContract({address: vault, abi: vaultAbi, functionName, args, blockNumber});

const walletShares = (await read('balanceOf')) as bigint;
const requestedShares = (await read('pendingRedeemShares')) as bigint;
const settledShares = (await read('processedRedeemSharesByOwner')) as bigint;
const claimableUsdc = (await read('processedRedeemAssetsByOwner')) as bigint;
const awaitingSettlementShares = requestedShares - settledShares;

// The underlying calculator rejects zero; zero shares have zero value.
const investedUsdcEstimate =
  walletShares === 0n ? 0n : await read('convertToAssets', [walletShares]);
const pendingUsdcEstimate =
  awaitingSettlementShares === 0n ? 0n : await read('convertToAssets', [awaitingSettlementShares]);

const shares = walletShares;
// maxRedeem is immediate exit capacity; larger exits must use the queued flow.
const max = (await publicClient.readContract({
  address: vault,
  abi: vaultAbi,
  functionName: 'maxRedeem',
  args: [owner]
})) as bigint;
if (shares <= 0n || shares > max)
  throw new Error('Choose an amount within immediate capacity, or queue an exit');
await publicClient.simulateContract({
  account: owner,
  address: vault,
  abi: vaultAbi,
  functionName: 'redeem',
  args: [shares, owner, owner]
});
// redeem takes shares, receiver and owner; USDC returns to the same user wallet.
await send(
  vault,
  encodeFunctionData({abi: vaultAbi, functionName: 'redeem', args: [shares, owner, owner]})
);