Unify network configuration across Nuwa SDKs

[jolestar]

Problem

When integrating multiple Nuwa SDKs (identity-kit, payment-kit, cap-kit) in an application, developers face difficulties with network configuration due to:

1. Scattered configuration sources - Each SDK has its own way of determining network settings
2. Inconsistent parameter naming - rpcUrl vs roochUrl, different option structures
3. Implicit inference logic - Some SDKs infer network from hostnames, others require explicit config
4. Missing unified chain config - IdentityEnv.chainConfig doesn't exist, but code assumes it does

Current State

SDK / Module	Network Config Source	Parameter Naming
IdentityKitWeb	Inferred from cadopDomain + roochRpcUrl option	network, rpcUrl
PaymentHubClient	Constructor params, tried env.chainConfig (doesn't exist)	network, rpcUrl
CapKitMcp	capKitConfig.roochUrl	roochUrl, network
RoochPaymentChannelContract	Constructor params	rpcUrl, network

Specific Issues

1. IdentityKitWeb infers network from cadopDomain via resolveNetworkFromHost(), but if roochRpcUrl points to mainnet while cadopDomain is testnet, they conflict silently.

2. getChainConfigFromEnv() exists in payment-kit but is not easily discoverable. Developers may incorrectly assume env.chainConfig exists.

3. No single source of truth - Applications need to configure network in multiple places and ensure consistency manually.

Impact

• Developer confusion when setting up multi-SDK integrations
• Hard-to-debug issues when configurations are inconsistent
• Increased boilerplate code in applications to keep configs in sync

Proposed Improvements

Short-term (Documentation & Conventions)

• Standardize parameter naming: network + rpcUrl across all SDKs
• Document network configuration priority: explicit params > global config > env vars > hostname inference
• Export getChainConfigFromEnv() prominently from payment-kit

Mid-term (SDK Enhancements)

• Add chainConfig property to IdentityEnv during bootstrap
• Provide fromEnv() factory methods in each SDK:

  const hub = await PaymentHubClient.fromEnv(env, { defaultAssetId });
  const capKit = await CapKitMcp.fromEnv(env, { contractAddress });

• Support NUWA_NETWORK / VITE_NUWA_NETWORK environment variable in all SDKs

Long-term (Optional)

• Consider creating @nuwa-ai/sdk as unified entry point:

  const nuwa = await NuwaSDK.init({ network: 'main' });
  const payment = nuwa.getPaymentHubClient();
  const capKit = nuwa.getCapKitMcp();

Related

This issue was discovered while adding mainnet support to nuwa-client, where PaymentHubClient was incorrectly connecting to testnet despite other configs pointing to mainnet.

Labels

• enhancement
• sdk
• developer-experience