SOSHI Integration Guide

Official integration documentation for SOSHI Protocol partners

Overview

SOSHI is a next-generation Web3 social network token built on Ethereum and Layer 2 networks. Designed for seamless integration with MeWe's social networking platform, SOSHI provides:

• ERC-20 compliant token with permit functionality
• Cross-chain support (Ethereum, Arbitrum, Base)
• Built-in staking mechanisms for social engagement rewards
• Programmable transfer policies for regulatory compliance

Quick Start

Installation

# Install the SDK (recommended approach)
npm install @soshi/sdk

# Or with yarn
yarn add @soshi/sdk

# Or with pnpm
pnpm add @soshi/sdk

Basic Integration

Important: All blockchain interactions MUST go through @soshi/sdk. Direct usage of viem/ethers is not supported for production integrations.

Recommended: Using @soshi/sdk

import { SoshiSDK } from '@soshi/sdk';
import addresses from '@soshi/sdk/addresses.json';

// Initialize SDK with your provider
const sdk = new SoshiSDK({
  network: 'mainnet', // or 'arbitrum', 'base', 'sepolia'
  provider: window.ethereum // or any EIP-1193 provider
});

// Read user balance
const balance = await sdk.balances.get(userAddress);
console.log('Balance:', sdk.utils.formatToken(balance));

// Check transfer eligibility
const canTransfer = await sdk.transfers.checkEligibility(from, to, amount);
if (!canTransfer.allowed) {
  console.log('Transfer blocked:', canTransfer.reason);
}

// Watch transfer events
const unsubscribe = sdk.events.watchTransfers({
  onTransfer: (from, to, amount) => {
    console.log(`Transfer: ${from} → ${to}, Amount: ${amount}`);
  }
});

// Get current transfer policy mode
const mode = await sdk.policy.getTransferMode();
// Returns: 'disabled' | 'whitelist' | 'open'

// Check if address is whitelisted
const isWhitelisted = await sdk.policy.isWhitelisted(address);

Temporary Fallback (Alpha only): Direct Contract Access

⚠️ Warning: This approach is for alpha testing only and will be deprecated. Production integrations MUST use the SDK.

import { SoshiSDK } from '@soshi/sdk';

// For alpha testing only - get ABI and addresses
const { abi, addresses } = await SoshiSDK.getContractInfo('mainnet');

// Then use with your preferred library (viem/ethers)
// This pattern will be removed in production releases

Integration Flows

Buy/Sell Integration

For detailed on-ramp and off-ramp integration:

• 📖 On-ramp Buy/Sell Documentation

// Check if user can receive tokens (e.g., after purchase)
const canReceive = await sdk.transfers.canReceive(userAddress);
if (!canReceive) {
  console.log('User wallet not eligible to receive SOSHI');
  // Guide user through whitelisting process
}

// Initiate buy flow (partners with KYC/AML)
const buyOrder = await sdk.onramp.prepareBuyOrder({
  userId: 'user-123',
  amount: '1000', // SOSHI amount
  paymentMethod: 'card'
});

Staking Read Model

Access staking data for displaying user rewards and positions:

• 📖 Staking Read Model Documentation

// Get user's staking position
const position = await sdk.staking.getUserPosition(userAddress);
console.log('Staked:', position.stakedAmount);
console.log('Rewards:', position.pendingRewards);
console.log('APY:', position.currentAPY);

// Subscribe to staking updates
sdk.staking.watchPosition(userAddress, (position) => {
  updateUI(position);
});

Networks & Addresses

Note: Always load addresses from @soshi/sdk/addresses.json. Never hardcode addresses in your application.

Network	Chain ID	Status	Explorer
Ethereum Mainnet	1	🔄 Pending	Etherscan
Arbitrum One	42161	🔄 Pending	Arbiscan
Base	8453	🔄 Pending	BaseScan
Sepolia Testnet	11155111	✅ Deployed	Sepolia Etherscan

// Always load addresses dynamically
import { getAddresses } from '@soshi/sdk';

const addresses = await getAddresses('mainnet');
console.log('Token:', addresses.token);
console.log('Staking:', addresses.staking);
console.log('Policy:', addresses.transferPolicy);

Token Information

• Name: Sochi Token
• Symbol: SOCHI
• Decimals: 18
• Total Supply: 1,000,000,000 SOCHI
• Contract Type: ERC-20 with ERC-20Permit
• Transfer Policy: Programmable (Disabled → Whitelist → Open)

SDK Features

// Complete SDK API surface
const sdk = new SoshiSDK({ network, provider });

// Balance operations
sdk.balances.get(address)
sdk.balances.getMultiple(addresses[])
sdk.balances.watchBalance(address, callback)

// Transfer operations
sdk.transfers.checkEligibility(from, to, amount)
sdk.transfers.canReceive(address)
sdk.transfers.send(to, amount) // Requires signer
sdk.transfers.approve(spender, amount) // Requires signer

// Staking operations
sdk.staking.getUserPosition(address)
sdk.staking.getCurrentAPY()
sdk.staking.stake(amount) // Requires signer
sdk.staking.unstake(amount) // Requires signer
sdk.staking.claimRewards() // Requires signer

// Policy queries
sdk.policy.getTransferMode()
sdk.policy.isWhitelisted(address)
sdk.policy.getWhitelistStatus(addresses[])

// Event subscriptions
sdk.events.watchTransfers(options)
sdk.events.watchStaking(options)
sdk.events.getPastEvents(filter)

// Utilities
sdk.utils.formatToken(amount)
sdk.utils.parseToken(string)
sdk.utils.isValidAddress(address)

Roadmap

Feature	Status	Target Date	Description
SDK Alpha Release	✅	Completed	Core SDK with read operations
Testnet Deployment	✅	Completed	Sepolia testnet contracts
Write Operations	🔄	Q1 2025	Transfer, approve, stake via SDK
Partner API Endpoints	📅	Q2 2025	REST API for non-Web3 integrations
Mainnet Launch	📅	Q2 2025	Production deployment on Ethereum
Cross-chain Bridge	📅	Q2 2025	Native bridging between networks
Advanced Staking	📅	Q3 2025	Tiered staking with multipliers
Social Network Features	📅	Q3 2025	MeWe platform integrations

Security

• ✅ Audited by leading security firms
• ✅ Bug Bounty Program via Immunefi (up to $100k)
• ✅ Multi-sig Treasury with 3/5 Gnosis Safe
• ✅ Timelock on critical functions (48-hour delay)
• ✅ Transfer Policies for compliance and security

Transfer Restriction Modes

SOSHI implements three transfer modes for different phases:

// Query current mode via SDK
const mode = await sdk.policy.getTransferMode();

switch(mode) {
  case 'disabled':
    // All transfers paused (emergency/launch phase)
    break;
  case 'whitelist':
    // Only KYC'd addresses can transfer
    break;
  case 'open':
    // Unrestricted transfers (final phase)
    break;
}

Best Practices

DO ✅

• Always use @soshi/sdk for blockchain interactions
• Load addresses from @soshi/sdk/addresses.json
• Handle all error cases and policy restrictions
• Subscribe to events for real-time updates
• Cache read operations appropriately

DON'T ❌

• Never import viem/ethers directly in production
• Never hardcode contract addresses
• Never store private keys in code
• Never bypass transfer policy checks
• Never assume transfers will succeed

Support

Documentation

• 📚 Full Documentation
• 📱 Social Network Integration Guide
• 🔧 SDK API Reference
• 📖 Smart Contract Docs

Developer Resources

• GitHub Repository
• NPM Package
• Example Integrations

Contact

• Technical Support: dev@soshi.xyz
• Partnership Inquiries: partners@soshi.xyz
• Security Issues: security@soshi.xyz (PGP available)
• Discord: discord.gg/soshi
• Twitter: @SoshiProtocol

For MeWe Integration

Special support channel for MeWe platform:

• Dedicated Slack Channel: #mewe-integration
• Technical Lead: Assigned social platform engineer
• Priority Support: 24h response time SLA
• Direct Access: Request via partners@soshi.xyz

Migration Guide

From Direct Contract Access to SDK

If you're currently using direct contract access (alpha phase), migrate to SDK:

// ❌ OLD (deprecated)
import { createPublicClient } from 'viem';
const client = createPublicClient(...);
const balance = await client.readContract({
  address: HARDCODED_ADDRESS,
  abi: [...],
  functionName: 'balanceOf'
});

// ✅ NEW (required)
import { SoshiSDK } from '@soshi/sdk';
const sdk = new SoshiSDK({ network, provider });
const balance = await sdk.balances.get(address);

License

MIT License - See LICENSE for details

---

Last updated: December 2024
SDK Version: 1.0.0-alpha.1