MATRIX Wallet SDK

The MATRIX Wallet SDK is an open-source project developed by [MATRIX] contributors.

The Wallet SDK enables dApp and DeFi developers to provide privacy to users safely and conveniently on Ethereum, Polygon and BNB Chain.

The repo is written in TypeScript, and compatible with node.js and modern web browsers.

HTTP V2 and private transfers

Current workspace sources implement user scenarios in design 30.

• MatrixPrivateTransferWallet / createPrivateTransferWalletForID estimate, prove and submit W→W′ directly to Matrix. They need pool pins and the private wallet, with no E, delegated implementation or Account signer.
• MatrixHttpBroadcasterClient(endpoint, poolDeployment, 'private-transfer') obtains V2 private-note quotes. estimatePrivateTransfer, provePrivateTransfer, submitPrivateTransferHttp and submitPrivateTransferDirect share encrypted note custody with Account operations. Proofs stay local during preview; failed/unknown submissions retain their original intent for retry and canonical receipt reconciliation.
• Account clients use feeOfferV2(token, 'public-erc20') and accountFeesForHttpOffer(offer) to pay the operator from E in the same execution. No private proof is needed unless the request also spends private notes. publicFee.paymentIndex places payment before explicit final transfers; generated re-shield calls follow it.
• previewCloseExecutionAccount({ account }) defaults to the current private wallet. An explicit destination: { type: 'public', recipient } selects a public exit; the legacy explicit recipient remains public. closeExecutionAccountHttp supports either fee mode. Unsupported residue prevents archive, and reopenExecutionAccountForCleanup explicitly reopens an old address when new tracked assets arrive.

Relayed Unshield and gas-priced quotes

• MatrixRelayedUnshieldWallet / createRelayedUnshieldWalletForID exit the pool without the user's public address signing or paying gas. type: 'erc20' unshields a token straight to recipientAddress through Matrix.execute; type: 'base-token' unshields the wrapped base token to the pinned deployment.relayAdapt, which unwraps it and sends ETH to recipientAddress (RelayAdapt.relay, requireSuccess, exactly two calls).
• Flow: estimateRelayedUnshield(request) (dummy proof; include the worst-case quote as feeOutput so note selection covers it) → quoteRelayedUnshieldHttp(id, client, feeToken) (sends the estimate as gasEstimate and writes the exact quote into the private fee note) → proveRelayedUnshield(id) → submitRelayedUnshieldHttp(id, client, offer) → pollRelayedUnshieldHttp / retryRelayedUnshieldHttp / reconcileRelayedUnshield. Use new MatrixHttpBroadcasterClient(endpoint, poolDeployment, 'unshield').
• feeOfferV2(token, mode, { gasEstimate }) requests a signed gas quote (fee = ceil(1.5 × gas × gasPrice) in the fee token, gasPrice = latest baseFee + submitter tip) from broadcasters that advertise pricing: 'gas-estimate'. The broadcaster sets the outer transaction's fee fields itself; the Wallet's values are advisory and only gasLimit binds. quotePrivateTransferHttp does the same for private transfers. A broadcaster REQUOTE_REQUIRED after a gas spike leaves the proof intact: retry accepts a fresh quote only when it does not exceed the proved fee.

Pool transfer deadlines are transport deadlines, not proof revocation. Do not release notes merely because an operator is offline. pollPrivateTransferHttp / reconcilePrivateTransfer verify pool effects and can recover a missing transaction hash from owned spent notes; production factories synchronize history for this check.

Native ingress remains the existing atomic wrap/approve/shield transaction through RelayAdapt. It is not replaced with a user-visible three-transaction flow. DeFi Account execution calls protocols directly.

Run pnpm run test:http-v2:e2e after building contracts, Engine, shared-models and http-broadcaster. It uses local Anvil, disposable PostgreSQL and real existing Groth16 artifacts; it does not deploy to a public chain.