SDK Interface

[r-near]

I'm working on improving our SDK's interface and could use some input. Here are the main issues I'm trying to solve:

Current Problems

1. The interface is inconsistent - we have omniTransfer for some operations but then you need to manually create clients for others
2. Different chains need different steps (like NEAR->ETH needing that extra signing step)
3. All cross-chain operations actually go through NEAR but this isn't clear in the API
4. You have to manually coordinate between blockchain operations and our centralized API (for fees, status tracking, etc.)
5. There's no clean way to handle operation lifecycles or state

The Wallet Problem

A big challenge is that different chains handle wallets and signing differently. You need to:

• Connect different types of wallets
• Handle transaction signing
• Deal with NEAR storage deposits
• Configure gas differently for each chain
• Maybe use custom RPC providers

One Possible Solution

I've been exploring an operation-centric interface that might look something like this:

const transfer = Transfer.create({
  sourceChain: ChainKind.Eth,
  destChain: ChainKind.Near,
  token: "eth:0x123...",
  recipient: "near:account.near",
  amount: "1.5"
})

// You control the wallets/signing
transfer.setSigners({
  eth: {
    wallet: ethWallet,
    provider: customProvider  // Optional
  },
  near: {
    account: nearAccount,
    // Your signing config
  }
})

// The SDK handles API integration and state management automatically
await transfer.init()     // Includes fee calculation
await transfer.sign()     // For NEAR egress only
await transfer.finalize() // Handles proof generation, status monitoring, etc

// Can check status/details at any point
console.log(transfer.getStatus())        // e.g. 'initialized', 'signed', etc.
console.log(transfer.getTransactionIds()) // Get tx hashes for each step

// Or just do it all at once if you prefer
await transfer.execute()

For comparison, here's what integration currently looks like:

// Have to manually call API
const api = new OmniBridgeAPI("mainnet")
const fee = await api.getFee(sender, recipient, tokenAddress)

// Connect wallet yourself
const wallet = await connectWallet()

// Create client manually
const client = new EvmBridgeClient(wallet, ChainKind.Eth)
const tx = await client.initTransfer({
  tokenAddress: "eth:0x123...",
  amount: amount,
  fee: fee.transferred_token_fee,
  nativeFee: fee.native_token_fee,
  recipient: "near:account.near"
})

// Check status manually 
const status = await api.getTransferStatus(originChain, originNonce)

// Wait for proof generation and get proof
const proof = await getEvmProof(tx.hash, TRANSFER_TOPIC)

// Create new client for finalization on NEAR
const nearClient = new NearBridgeClient(nearWallet)
await nearClient.finalizeTransfer(
  token,
  account,
  storageDeposit,
  ChainKind.Eth,
  undefined, // vaa
  proof
)

Status Monitoring

One key design question is how much the SDK should handle vs. leaving to the apps. For example, with transfer status monitoring, the SDK could either manage all the monitoring internally (polling, waiting for proofs etc.), or just provide the tools and let you implement your own monitoring.

I can see valid reasons for both. Your app might want to show its own progress UI, handle timeouts differently, or branch into different flows at each stage.

Feedback

Open to any feedback here, especially around:

• Wallet connection/signing flow
• Automatic execution vs. manual control
• Chain-specific configs you need to set
• Error/retry handling