# API Methods (/docs/builders/shreds/api-methods)

# API Methods

Core methods that power RISE's realtime capabilities.

<Callout type="info">
  For standard Ethereum methods, visit the [Ethereum JSON-RPC Documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/).
</Callout>

## sendTransactionSync

Creates, signs, and sends a transaction synchronously, returning the complete transaction receipt.

This is a convenience method from viem that handles the entire transaction lifecycle in one call. It's simpler to use but makes multiple RPC calls (chainId, nonce, gas estimation).

### Parameters

Standard viem transaction parameters:

* `to` - Recipient address
* `value` - Amount to send (optional)
* `data` - Transaction data (optional)
* Other standard transaction fields

### Returns

Complete `TransactionReceipt` object

### Example

```typescript
import { createWalletClient, http, parseEther } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { riseTestnet } from 'viem/chains'

const account = privateKeyToAccount('0x...')
const client = createWalletClient({
  account,
  chain: riseTestnet,
  transport: http()
})

// Simple one-call transaction
const receipt = await client.sendTransactionSync({
  to: '0x...',
  value: parseEther('1.0')
})

console.log('Transaction confirmed:', receipt)
```

### When to Use

* **Quick prototyping**: Get started fast without manual signing
* **Simple applications**: When RPC overhead isn't critical
* **Standard workflows**: Works with existing viem patterns

## eth\_sendRawTransactionSync

Sends a **pre-signed** transaction and waits for instant confirmation, returning the complete transaction receipt.

This method is based on [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966), which introduces synchronous transaction confirmation to Ethereum. RISE implements this standard to provide instant transaction finality.

**Use this for maximum performance** when you need the absolute fastest transaction times, as it requires only a single RPC call.

### Parameters

1. `data` - Signed transaction data (hex string)

### Returns

Complete `TransactionReceipt` object with all standard fields:

```typescript
{
  transactionHash: string,
  blockNumber: string,
  blockHash: string,
  transactionIndex: string,
  from: string,
  to: string | null,
  gasUsed: string,
  cumulativeGasUsed: string,
  status: string, // "0x1" for success, "0x0" for failure
  logs: Log[],
  logsBloom: string,
  contractAddress: string | null
}
```

### Example

```typescript
const receipt = await client.request({
  method: 'eth_sendRawTransactionSync',
  params: ['0x...signed_transaction']
})

//Transaction receipt
console.log('Transaction hash:', receipt.transactionHash)
console.log('Status:', receipt.status === '0x1' ? 'Success' : 'Failed')
```

### Using with viem

```typescript
import { createWalletClient, createPublicClient, http, parseEther } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { shredActions } from 'shreds/viem'
import { riseTestnet } from 'viem/chains'

const account = privateKeyToAccount('0x...')

// Wallet client for signing
const walletClient = createWalletClient({
  account,
  chain: riseTestnet,
  transport: http()
})

// Public client for sending
const publicClient = createPublicClient({
  chain: riseTestnet,
  transport: http()
}).extend(shredActions)

// Prepare and sign transaction
const request = await walletClient.prepareTransactionRequest({
  to: '0x...',
  value: parseEther('1.0')
})

const serializedTransaction = await walletClient.signTransaction(request)

// Send with instant confirmation
const receipt = await publicClient.sendRawTransactionSync({
  serializedTransaction
})

console.log('Transaction confirmed:', receipt)
```

### When to Use

* **Performance-critical applications**: Gaming, high-frequency trading, competitive scenarios
* **Pre-signed transaction pools**: Batch signing transactions in advance
* **Minimal RPC overhead**: Only 1 RPC call vs 3+ with `sendTransactionSync`

### Key Benefits

* **Instant confirmation**: No waiting for block inclusion
* **Complete receipt**: All transaction details immediately available
* **Synchronous flow**: Simplifies application logic
* **Error handling**: Failed transactions return immediately with status `0x0`
* **Maximum performance**: Single RPC call for fastest possible transactions

## Comparison: sendTransactionSync vs sendRawTransactionSync

| Feature              | `sendTransactionSync`                      | `sendRawTransactionSync`  |
| -------------------- | ------------------------------------------ | ------------------------- |
| **RPC Calls**        | 3+ (chainId, nonce, gas estimation + send) | 1 (send only)             |
| **Setup Complexity** | Simple                                     | Requires manual signing   |
| **Performance**      | Good (\~10-20ms overhead)                  | Best (minimal overhead)   |
| **Use Case**         | Prototyping, simple apps                   | Performance-critical apps |
| **Viem Support**     | Built-in                                   | Via shreds library        |

### Example: Simple Approach

```typescript
// Using sendTransactionSync (simpler, more RPC calls)
const receipt = await client.sendTransactionSync({
  to: '0x...',
  value: parseEther('1.0')
})
```

### Example: Performance-Optimized Approach

```typescript
// Using sendRawTransactionSync (optimal, 1 RPC call)
const request = await walletClient.prepareTransactionRequest({
  to: '0x...',
  value: parseEther('1.0')
})
const serialized = await walletClient.signTransaction(request)
const receipt = await publicClient.sendRawTransactionSync({
  serializedTransaction: serialized
})
```

## Usage Patterns

### Synchronous Transaction Flow

```typescript
import { sendRawTransactionSync } from 'shreds/viem'

// Traditional async pattern (not needed with RISE)
// const hash = await client.sendTransaction(tx)
// const receipt = await client.waitForTransactionReceipt({ hash })

// RISE synchronous pattern
// 1. Prepare and sign
const request = await walletClient.prepareTransactionRequest(tx)
const serialized = await walletClient.signTransaction(request)

// 2. Send and get instant receipt
const receipt = await sendRawTransactionSync(publicClient, { serializedTransaction: serialized })
// Transaction already confirmed!
```

## Performance Characteristics

### RTT (Round-Trip Time) Targets

* **Shred Confirmation**: 3-5ms (p50), 10ms (p99)
* **Event Delivery**: \< 10ms from transaction execution
* **State Updates**: Immediate upon shred confirmation

### Throughput

* **Transactions per Shred**: 1-100
* **Shreds per Second**: 1000+
* **Total TPS**: 10,000+

## Best Practices

### 1. Choose the Right Method

```typescript
// For prototyping and simple apps - use sendTransactionSync
const receipt = await client.sendTransactionSync({
  to: '0x...',
  value: parseEther('1.0')
})

// For performance-critical apps - use sendRawTransactionSync with pre-signing
const request = await walletClient.prepareTransactionRequest(tx)
const serialized = await walletClient.signTransaction(request)
const receipt = await publicClient.sendRawTransactionSync({
  serializedTransaction: serialized
})
```

### 2. Pre-sign Transactions for Maximum Performance

```typescript
// Sign a batch of transactions in advance
const preSignedTxs = await Promise.all(
  txRequests.map(async (req, i) => {
    const request = await walletClient.prepareTransactionRequest({
      ...req,
      nonce: baseNonce + i
    })
    return await walletClient.signTransaction(request)
  })
)

// Send them instantly when needed (single RPC call each)
for (const signedTx of preSignedTxs) {
  const receipt = await publicClient.sendRawTransactionSync({
    serializedTransaction: signedTx
  })
}
```

### 3. Handle Errors Immediately

```typescript
try {
  const receipt = await client.sendTransactionSync({
    to: '0x...',
    value: parseEther('1.0')
  })
  // Transaction confirmed immediately
} catch (error) {
  // Handle failure immediately - no need to wait
  console.error('Transaction failed:', error)
}
```

## Next Steps

* [Watching Events](/docs/builders/shreds/watching-events) - Realtime subscriptions
* [Quickstart](/docs/builders/shreds/quickstart) - Build your first app