Shogun Contracts SDK

SDK TypeScript per interagire con i contratti smart contract del protocollo Shogun.

Build

L'SDK viene compilato automaticamente prima della pubblicazione del package. Per compilarlo manualmente:

npm run build:sdk

I file compilati vengono generati in sdk/dist/.

Installazione

npm install shogun-contracts
# oppure
yarn add shogun-contracts

Utilizzo

Configurazione base

import { ShogunSDK } from 'shogun-contracts/sdk';
import { JsonRpcProvider, Wallet } from 'ethers';

// Provider senza signer (solo lettura)
const provider = new JsonRpcProvider('https://sepolia.base.org');
const sdk = new ShogunSDK({
  provider,
  chainId: 84532 // Base Sepolia
});

// Con signer (per transazioni)
const wallet = new Wallet('PRIVATE_KEY', provider);
const sdkWithSigner = new ShogunSDK({
  provider,
  signer: wallet,
  chainId: 84532
});

Relay Registry

const relayRegistry = sdk.getRelayRegistry();

// Registrare un relay
await relayRegistry.registerRelay(
  'https://relay.example.com',
  '0x...', // pubkey
  '0x...', // epub
  BigInt('1000000000000000000'), // stake amount
  BigInt('1000') // griefing ratio
);

// Ottenere informazioni su un relay
const relayInfo = await relayRegistry.getRelayInfo('0x...');

// Ottenere tutti i relay attivi
const activeRelays = await relayRegistry.getActiveRelays();

Storage Deal Registry

const storageDeal = sdk.getStorageDealRegistry();

// Registrare un nuovo deal
await storageDeal.registerDeal(
  '0x...', // dealId
  '0x...', // client address
  'Qm...', // CID
  BigInt(100), // sizeMB
  BigInt('1000000'), // priceUSDC (6 decimals)
  BigInt(30), // durationDays
  BigInt('500000') // clientStake
);

// Ottenere informazioni su un deal
const deal = await storageDeal.getDeal('0x...');

// Completare un deal
await storageDeal.completeDeal('0x...');

Data Post Registry

const dataPost = sdk.getDataPostRegistry();

// Pubblicare un nuovo post
const tx = await dataPost.publishPost(
  '0x...', // proofHash
  'Qm...', // encryptedDataHash
  'Description of the data',
  'category',
  BigInt('1000000') // priceUSDC
);

// Ottenere tutti i post attivi
const activePosts = await dataPost.getActivePosts();

// Ottenere post per categoria
const posts = await dataPost.getPostsByCategory('category');

Data Sale Escrow Factory

const escrowFactory = sdk.getDataSaleEscrowFactory();

// Creare un nuovo escrow
const escrowAddress = await escrowFactory.createEscrow(
  '0x...', // postId
  '0x...', // seller address
  BigInt(3600) // countdownDuration (seconds)
);

// Ottenere escrow per buyer
const buyerEscrows = await escrowFactory.getEscrowsByBuyer('0x...');

Stealth Pool

const stealthPool = sdk.getStealthPool();

// Registrare un deposito
await stealthPool.registerDeposit(
  '0x...', // commitment
  BigInt('1000000000000000000') // amount
);

// Prelevare
const merkleProof = await stealthPool.generateMerkleProof('0x...');
await stealthPool.withdraw(
  '0x...', // commitment
  '0x...', // nonce
  '0x...', // recipient
  BigInt('1000000000000000000'), // amount
  merkleProof[0] // merkle proof
);

API Reference

ShogunSDK

Classe principale per interagire con i contratti.

Metodi

• getRelayRegistry(): Restituisce un'istanza di RelayRegistry
• getStorageDealRegistry(): Restituisce un'istanza di StorageDealRegistry
• getDataPostRegistry(): Restituisce un'istanza di DataPostRegistry
• getDataSaleEscrowFactory(): Restituisce un'istanza di DataSaleEscrowFactory
• getStealthPool(): Restituisce un'istanza di StealthPool
• getOracleFeedRegistry(): Restituisce un'istanza di OracleFeedRegistry
• getContractDeployment(contractName): Ottiene informazioni sul deployment di un contratto
• getChainId(): Restituisce il chain ID corrente
• getProvider(): Restituisce il provider
• getSigner(): Restituisce il signer (se disponibile)
• setSigner(signer): Imposta un nuovo signer

Oracle Feed Registry

import { OracleFeedRegistry, OraclePacketSigner, OracleDataType } from 'shogun-contracts/sdk';

const oracleRegistry = sdk.getOracleFeedRegistry();

// Registrare un feed (da un relay attivo)
await oracleRegistry.registerFeed(
  'ETH/USD',
  OracleDataType.PRICE,
  '(uint256)',
  BigInt('1000000'), // 1 USDC
  60 // update ogni 60 secondi
);

// Ottenere i feed di un relay
const feeds = await oracleRegistry.getRelayFeeds('0x...');

// Firmare un pacchetto oracle (lato relay)
const signer = new OraclePacketSigner(
  'PRIVATE_KEY',
  84532, // chainId
  '0x...' // oracle contract address
);

const packet = await signer.signPacket('ETH/USD', 3500_00000000n, '(uint256)');

Utility Functions

import { 
  getContractDeployment, 
  getAvailableChainIds, 
  isChainSupported 
} from 'shogun-contracts/sdk';

// Verificare se una chain è supportata
if (isChainSupported(84532)) {
  console.log('Chain supported!');
}

// Ottenere deployment info
const deployment = getContractDeployment(84532, 'ShogunRelayRegistry');

// Ottenere tutte le chain disponibili
const chains = getAvailableChainIds();

Chain Supportate

• 84532 (Base Sepolia)
• 11155111 (Sepolia)

Note

• Tutti gli import utilizzano estensioni .js anche per file TypeScript (richiesto per ESM)
• Le quantità devono essere passate come bigint
• Gli indirizzi devono essere stringhe valide (0x...)

Esempi Completi

Vedi la cartella examples/ per esempi più dettagliati.