Add Proof Generation Utilities

[r-near]

Problem

The SDK currently requires developers to manually generate or fetch proofs (e.g., Wormhole VAAs, transaction signatures, or EVM logs) for critical operations like finalizeTransfer and deployToken. While these methods expect parameters such as signature or vaa, the SDK lacks utilities to programmatically obtain these values, forcing developers to:

• Implement external logic for proof retrieval (e.g., querying Wormhole for VAAs).
• Reverse-engineer chain-specific event logs (e.g., extracting Merkle proofs from EVM transactions).
• Handle edge cases (e.g., NEAR token deployment signatures) without SDK support.

This increases integration complexity and risks errors in production workflows.

Proposed Solution

Introduce chain-specific proof generation utilities to simplify fetching/generating required proofs. These utilities will:

1. Allow developers to retrieve proofs in one line using transaction hashes or identifiers.
2. Maintain compatibility with existing methods (e.g., finalizeTransfer, deployToken) without changing their signatures.

Key Features to Implement

1. Proof Retrieval Helpers

   // Example methods
   getVaaForTransfer(txHash: string): Promise<Vaa>; // Wormhole VAA
   getTransferSignature(txHash: string, chain: ChainKind): Promise<SignatureData>; // Chain-specific proof
   getDeploymentSignature(txHash: string, token: OmniAddress): Promise<string>; // For token deployment

   • EVM Chains: Extract event logs (e.g., TransferInitiated) and generate Merkle proofs.
   • Wormhole Chains: Fetch VAAs using the Wormhole SDK.
   • NEAR/Solana: Generate deployment/token-binding signatures.

2. Updated Workflow Example

   // 1. Initiate transfer
   const result = await omniTransfer(nearAccount, transfer);
   
   // 2. Fetch VAA using txHash
   const vaa = await api.getVaaForTransfer(result.txId);
   
   // 3. Finalize transfer with VAA
   const ethClient = getClient(ChainKind.Eth, ethWallet);
   await ethClient.finalizeTransfer(transferMessage, vaa);

3. Token Deployment Support

   // Fetch signature for NEAR token deployment
   const signature = await nearClient.getDeploymentSignature("near:token.near");
   await nearClient.deployToken(signature, { ... });

Acceptance Criteria

• Implement getVaaForTransfer using Wormhole’s SDK (supports EVM, NEAR, Solana).
• Add getTransferSignature to fetch chain-specific proofs (e.g., EVM logs, NEAR signatures).
• Add getDeploymentSignature for token deployment workflows.
• Update README examples to demonstrate proof retrieval (see below).
• Add error handling for invalid/missing transactions or proofs.

Example Documentation Update

Before (Ambiguous):

// Signature is undefined in example
await client.deployToken(signature, { ... });

After (With Utilities):

// Fetch deployment signature using transaction hash
const signature = await client.getDeploymentSignature("near:token.near");
await client.deployToken(signature, {
  token: "near:token.near",
  name: "MyToken",
  symbol: "MTK",
  decimals: 18,
});

Additional Context

• Wormhole Integration: Required for VAA retrieval. Add @wormhole-foundation/wormhole-sdk as a dependency.
• Testing: Validate against testnet transactions for all chains.
• Edge Cases:
  • Gracefully handle chains without Wormhole support (e.g., direct light client bridges).
  • Timeouts for VAA availability (Wormhole VAAs may take 15+ seconds to finalize).