JPYC Development Toolkit

Overview

This skill provides comprehensive support for building applications with JPYC (Japanese Yen Pegged Coin), a stablecoin pegged to the Japanese Yen. It covers three main development approaches:

1. JPYC SDK v1 - Using the official SDK for standard operations
2. Smart Contract Development - Building custom contracts that integrate with JPYC
3. Frontend Integration - Implementing JPYC features in web applications

The skill includes ready-to-use templates, deployment scripts, integration patterns, and best practices specifically tailored for JPYC development on Base Sepolia and other supported networks.

When to Use This Skill

Trigger this skill when users request:

• "Implement JPYC payment functionality"
• "Deploy JPYC to Base Sepolia"
• "Set up JPYC SDK in my project"
• "Create a JPYC transfer component"
• "Build a donation system with JPYC"
• "Integrate JPYC into my DApp"
• "How do I use transferWithAuthorization with JPYC?"

Quick Start Guide

For SDK Users

If using the JPYC SDK v1:

1. Setup: Run the setup script

   bashCopy

   bash scripts/setup_jpyc_sdk.sh
   

2. Configure: Edit .env with contract address and keys

   envCopy

   JPYC_CONTRACT_ADDRESS=0x431D5dfF03120AFA4bDf332c61A6e1766eF37BDB
   PRIVATE_KEY=0x...
   RPC_URL=https://sepolia.base.org
   

3. Use SDK functions: See references/sdk-features.md for all available operations

For Smart Contract Developers

If building custom contracts:

1. Copy template: Use assets/contract-templates/JPYCIntegration.sol as starting point

2. Configure Hardhat: Copy assets/hardhat-config/hardhat.config.example.ts to your project

3. Deploy to Base Sepolia: Use scripts/deploy_jpyc_base.ts

4. Choose integration pattern: See references/integration-patterns.md for recommended approaches

For Frontend Developers

If building web interfaces:

1. Copy components: Use templates from assets/frontend-examples/

   • JPYCBalance.tsx - Display JPYC balance
   • JPYCTransfer.tsx - Transfer JPYC tokens

2. Configure network: Set up wagmi/viem with Base Sepolia (see references/network-config.md)

3. Implement pattern: Follow integration patterns in references/integration-patterns.md

Core Development Tasks

Task 1: Setting Up JPYC SDK

When to use: Need to interact with JPYC using the official SDK

Steps:

1. Add SDK as Git Submodule:

   bashCopy

   git submodule add -b develop https://github.com/jcam1/sdks.git external/jpyc-sdk
   

2. Run automated setup:

   bashCopy

   bash scripts/setup_jpyc_sdk.sh
   

3. Configure environment variables in external/jpyc-sdk/packages/v1/.env

Available SDK operations:

• Mint new tokens
• Get total supply
• Transfer tokens
• Approve spender
• Transfer from
• Permit allowance (EIP-2612)
• Transfer with Authorization (EIP-3009)
• Receive with Authorization (EIP-3009)
• Cancel Authorization (EIP-3009)

Detailed reference: See references/sdk-features.md

Task 2: Deploying JPYC to Base Sepolia

When to use: Base Sepolia doesn't have official JPYC deployment, need custom deployment

Prerequisites:

• Base Sepolia ETH in your wallet
• JPYCv2 contract source code

Steps:

1. Add JPYCv2 as submodule:

   bashCopy

   git submodule add https://github.com/jcam1/JPYCv2.git external/jpyc-contract
   

2. Configure Hardhat with Base Sepolia (copy from assets/hardhat-config/hardhat.config.example.ts)

3. Set environment variables:

   envCopy

   PRIVATE_KEY=0x...
   BASE_SEPOLIA_RPC_URL=https://sepolia.base.org
   BASESCAN_API_KEY=your_api_key
   

4. Deploy using the script:

   bashCopy

   npx hardhat run scripts/deploy_jpyc_base.ts --network baseSepolia
   

5. Verify contract on Basescan:

   bashCopy

   npx hardhat verify --network baseSepolia <CONTRACT_ADDRESS>
   

Detailed guide: See references/network-config.md

Task 3: Implementing Payment Features

When to use: Need to add JPYC payment functionality to your application

Choose the right pattern based on use case:

Implementation approaches:

A. Using Smart Contracts

Start with the template contract:

// Copy from assets/contract-templates/JPYCIntegration.sol
contract JPYCIntegration {
    function processPayment(
        address from,
        address to,
        uint256 amount,
        string calldata paymentId
    ) external {
        // Payment processing with ID tracking
    }
}

Pros: Maximum flexibility, custom business logic Cons: Requires contract deployment and audit

B. Using EIP-3009 (Recommended)

Leverage JPYC's built-in transferWithAuthorization:

// Hash payment ID to use as nonce
const paymentId = "order_12345";
const nonce = ethers.keccak256(ethers.toUtf8Bytes(paymentId));

// User signs authorization (gasless)
const signature = await signer.signTypedData(domain, types, {
  from: userAddress,
  to: merchantAddress,
  value: amount,
  validAfter: 0,
  validBefore: deadline,
  nonce: nonce
});

// Backend executes transfer (pays gas)
await jpycContract.transferWithAuthorization(
  userAddress, merchantAddress, amount,
  0, deadline, nonce, v, r, s
);

Pros: No custom contract needed, secure, low cost Cons: Requires event monitoring and DB management

Detailed patterns: See references/integration-patterns.md

Task 4: Building Frontend Components

When to use: Need UI components for JPYC interactions

Available templates:

Balance Display Component

Copy assets/frontend-examples/JPYCBalance.tsx:

import { JPYCBalance } from './JPYCBalance';

<JPYCBalance jpycAddress="0x431D..." />

Features:

• Auto-refresh every 10 seconds
• Formatted display with decimals
• Loading and error states
• Customizable styling

Transfer Form Component

Copy assets/frontend-examples/JPYCTransfer.tsx:

import { JPYCTransfer } from './JPYCTransfer';

<JPYCTransfer
  jpycAddress="0x431D..."
  onSuccess={(txHash) => console.log('Success:', txHash)}
  onError={(error) => console.error('Error:', error)}
/>

Features:

• Input validation
• Transaction status tracking
• Error handling
• Explorer link generation

Setup requirements:

1. Install dependencies: wagmi, viem
2. Configure network (see references/network-config.md)
3. Wrap app with WagmiProvider

Task 5: Implementing Gasless Transactions

When to use: Want users to interact without paying gas fees

Options:

Option 1: EIP-2612 Permit

Best for: Approval without gas

// User signs permit (no gas)
const signature = await signer.signTypedData(domain, permitTypes, {
  owner: userAddress,
  spender: contractAddress,
  value: amount,
  nonce: nonce,
  deadline: deadline
});

// Backend executes permit + transferFrom (pays gas)
await jpycContract.permit(userAddress, contractAddress, amount, deadline, v, r, s);
await contractAddress.transferFrom(userAddress, recipient, amount);

Option 2: EIP-3009 Transfer with Authorization

Best for: Direct transfers with payment ID

// User signs authorization (no gas)
const signature = await signer.signTypedData(domain, transferTypes, {
  from: userAddress,
  to: merchantAddress,
  value: amount,
  validAfter: 0,
  validBefore: deadline,
  nonce: nonce
});

// Backend executes (pays gas)
await jpycContract.transferWithAuthorization(
  userAddress, merchantAddress, amount, 0, deadline, nonce, v, r, s
);

Implementation details: See references/integration-patterns.md Pattern 4

Best Practices

Security

1. Approve Safety: Always reset to zero before changing allowance

   solidityCopy

   jpyc.approve(spender, 0);
   jpyc.approve(spender, newAmount);
   

   Or use increaseAllowance / decreaseAllowance

2. Signature Validation: Verify domain separator matches

   typescriptCopy

   const domain = {
     name: 'JPYCv2',
     version: '2',
     chainId: targetChainId,
     verifyingContract: jpycAddress
   };
   

3. Nonce Management: Ensure uniqueness to prevent replay

   typescriptCopy

   const paymentId = `order_${orderId}_${Date.now()}`;
   const nonce = ethers.keccak256(ethers.toUtf8Bytes(paymentId));
   

4. Deadline Setting: Set appropriate expiration times

   typescriptCopy

   const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour
   

Performance

1. Use L2 Networks: Deploy on Base Sepolia for lower gas costs

2. Batch Operations: Combine multiple operations when possible

3. Event Monitoring: Use WebSocket for real-time updates

   typescriptCopy

   jpycContract.on("Transfer", (from, to, amount) => {
     // Handle transfer event
   });
   

Development Workflow

1. Test Locally First: Use Hardhat network for development

   bashCopy

   npx hardhat node
   npx hardhat run scripts/deploy.ts --network localhost
   

2. Use Testnets: Deploy to Base Sepolia before mainnet

3. Verify Contracts: Always verify on block explorers

   bashCopy

   npx hardhat verify --network baseSepolia <ADDRESS>
   

Troubleshooting

Common Issues

"Insufficient funds" error

• Cause: Not enough Base Sepolia ETH
• Solution: Get from faucet (see references/resources.md)

"Network mismatch" error

• Cause: Wallet connected to wrong network
• Solution: Switch to Base Sepolia (Chain ID: 84532)

"Nonce already used" error

• Cause: EIP-3009 nonce collision
• Solution: Ensure unique payment IDs, check DB for duplicates

Signature verification fails

• Cause: Incorrect domain separator or expired deadline
• Solution: Verify chainId, contract address, and deadline

Resources

This skill includes comprehensive resources organized by type:

scripts/

setup_jpyc_sdk.sh - Automated SDK setup

• Adds Git Submodule
• Installs dependencies
• Compiles SDK
• Generates .env template

deploy_jpyc_base.ts - Base Sepolia deployment

• Pre-flight checks (balance, network)
• Deploys JPYCv2 contract
• Configures roles (MINTER, etc.)
• Generates verification command

references/

sdk-features.md - Complete SDK v1 reference

• All 9 available operations
• Setup instructions
• Code examples
• Security considerations

integration-patterns.md - Payment implementation patterns

• Pattern selection guide
• Code examples for each pattern
• Security best practices
• Trade-off analysis

network-config.md - Network configuration guide

• Base Sepolia setup
• Hardhat configuration
• Frontend setup (ethers.js, viem, wagmi)
• Troubleshooting

resources.md - External resources

• Official JPYC links
• GitHub repositories
• Technical articles
• Tools and explorers
• Faucets and RPC providers

assets/

contract-templates/JPYCIntegration.sol - Smart contract template

• Payment processing with ID tracking
• Event emission
• Security features (ReentrancyGuard)
• Refund functionality

frontend-examples/ - React components

• JPYCBalance.tsx - Balance display component
• JPYCTransfer.tsx - Transfer form component
• Uses wagmi + viem
• Production-ready with error handling

hardhat-config/hardhat.config.example.ts - Hardhat configuration

• Base Sepolia + other networks
• Etherscan/Basescan verification
• Gas reporter
• TypeChain support

Additional Notes

• Target Network: Base Sepolia recommended for development (Chain ID: 84532)
• JPYC Decimals: 18 (same as ETH)
• Contract Standard: ERC20 with EIP-2612 and EIP-3009 extensions
• Recommended Pattern: EIP-3009 transferWithAuthorization for most use cases

For detailed information on any topic, refer to the corresponding file in references/.