@tatchi-xyz/sdk
v0.58.0
Published
An embedded passkey wallet SDK built on NEAR protocol
Downloads
96
Maintainers
Readme
Web3Authn SDK
Passkey wallet SDK for NEAR Protocol. An embedded wallet powered by VRF WebAuthn, cross-origin iframe isolation, and WASM-based cryptography.
Installation
Install the published package:
npm install @tatchi-xyz/sdk
# or
pnpm add @tatchi-xyz/sdk
# or
yarn add @tatchi-xyz/sdkFor SDK Developers
Build:
# From repo root
pnpm install
pnpm -C sdk build # Builds WASM + bundles
pnpm -C sdk dev # Watch modeTest:
pnpm -C sdk test # Playwright tests
pnpm -C sdk run type-check # TypeScript validationQuick Start
React Integration
The easiest way to get started with React (React 18+)
import { TatchiPasskeyProvider, useTatchi } from '@tatchi-xyz/sdk/react'
function App() {
return (
<TatchiPasskeyProvider
config={{
nearRpcUrl: 'https://rpc.testnet.near.org',
nearNetwork: 'testnet',
contractId: 'w3a-v1.testnet',
iframeWallet: {
walletOrigin: 'https://wallet.web3authn.org',
},
relayer: {
url: 'https://relay-server.example.com',
},
}}
>
<YourApp />
</TatchiPasskeyProvider>
)
}
function SignInButton() {
const tatchi = useTatchi()
const handleSignIn = async () => {
const result = await tatchi.registerPasskey('alice.testnet')
console.log('Registered:', result.success)
}
return <button onClick={handleSignIn}>Sign In with Passkey</button>
}Vite Plugin Integration
Use the Vite plugins to serve wallet assets in dev and emit the right headers for production.
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tatchiDev, tatchiBuildHeaders } from '@tatchi-xyz/sdk/plugins/vite'
export default defineConfig({
plugins: [
react(),
tatchiDev({
walletOrigin: process.env.VITE_WALLET_ORIGIN,
sdkBasePath: '/sdk',
walletServicePath: '/wallet-service',
}),
tatchiBuildHeaders({
walletOrigin: process.env.VITE_WALLET_ORIGIN,
}),
]
})See examples/next-js for other examples.
Configuration Options
interface TatchiPasskeyConfig {
// NEAR blockchain settings
nearRpcUrl: string // RPC endpoint
nearNetwork: 'testnet' | 'mainnet'
contractId: string // WebAuthn contract
// Wallet iframe settings (recommended)
iframeWallet?: {
walletOrigin: string // e.g., 'https://wallet.web3authn.org'
walletServicePath?: string // Default: '/wallet-service'
rpIdOverride?: string // Optional: Credential scope override
}
// Optional relay server (for account creation & Shamir 3-pass)
relayer?: {
url: string
}
}Wallet Iframe Architecture
The SDK isolates all sensitive operations in a cross-origin iframe (e.g., wallet.web3authn.org). Your app communicates via secure MessageChannel, but can never access keys directly.
Configuration
Recommended (dedicated wallet origin):
iframeWallet: {
walletOrigin: 'https://wallet.web3authn.org',
walletServicePath: '/wallet-service',
}Project Structure
sdk/
├── src/
│ ├── core/ # Framework-agnostic core
│ │ ├── TatchiPasskey.ts # Main SDK class
│ │ ├── WebAuthnManager.ts # WebAuthn operations
│ │ └── WalletIframe/ # Iframe host/client, messaging
│ ├── react/ # React bindings
│ │ ├── PasskeyProvider.tsx # Context provider
│ │ └── hooks.ts # usePasskeyManager, etc.
│ ├── wasm_signer_worker/ # Rust WASM (transaction signing)
│ ├── wasm_vrf_worker/ # Rust WASM (VRF challenges)
│ └── plugins/
│ └── vite.ts # Vite dev/build helpers
│
├── dist/ # Build output
│ ├── core/ # Core SDK bundles
│ ├── react/ # React component bundles
│ ├── workers/ # WASM worker modules
│ └── wallet-iframe-host.js # Wallet iframe entry point
│
├── build-paths.ts # Build configuration (source of truth)
├── rolldown.config.ts # Rolldown bundler config
└── README.md # This fileLicense
MIT License - see LICENSE for details.
Support
- Documentation: ../examples/tatchi-docs/
- Issues: GitHub Issues
