Shred APIs

$\mathtt{Shreds}$ are a core concept in the RISE blockchain architecture. A $\mathtt{Shred}$ acts as a sub-block that contains:

• A subset of transactions;
• The receipts for those transactions;
• All state changes (such as account balances, nonces, storage, and contract code updates) resulting from those transactions.

$\mathtt{Shreds}$ are produced and broadcast by the network before they are assembled into full blocks. rise_subscribe enables a client to receive detailed notifications for each $\mathtt{Shred}$, including all transactions, receipts, logs, and state changes. This gives you a comprehensive and up-to-date view of the network’s activity before blocks are finalized.

Log Subscription

The log subscription allows clients to receive real-time notifications of contract events (logs) as soon as they are emitted. You can filter which logs you want to receive by specifying one or more contract addresses and/or topics. This is especially useful for monitoring specific contracts or event types.
The rise_subscribe log subscription is similar to the eth_subscribe log subscription in Ethereum, with one key difference: the blockHash field in the log notification is null. This means the transaction containing the log is included in a $\mathtt{Shred}$ but not yet finalized in a block.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rise_subscribe",
  "params": [
    "logs",
    {
      "address":  "0x99dbe4aea58e518c50a1c04ae9b48c9f6354612f",
      "topics":  ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ]
}

Parameter Descriptions

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
id	integer	An identifier for this request. Used to match responses with requests.
method	string	The RPC method to call. Always "rise_subscribe".
params	array	Parameters for the subscription: 1. "logs": Subscription type. 2. Filter object:   - address (optional): Either an address or an array of addresses. Only logs that are created from these addresses are returned.   - topics (optional): Only logs that match these specified topics are returned.

---

Example Response

Initial Subscription Response

{"jsonrpc":"2.0","id":1,"result":"0x862db97373b7b4c0cebcdff1801c78b4"}

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
id	integer	The same ID as in the request, for matching.
result	string	The subscription ID. Use this to unsubscribe if needed.

---

Log Notification

{
  "jsonrpc": "2.0",
  "method": "rise_subscription",
  "params": {
    "subscription": "0x862db97373b7b4c0cebcdff1801c78b4",
    "result": {
      "address": "0xe03f4c6749c2b1b1638e0e42a1b1b33af1195c12",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x000000000000000000000000a54924e8bdd79e75626f9ae9bf139c669debd550",
        "0x0000000000000000000000000000000000000000000000000000000000000000"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000000000000007134",
      "blockHash": null,
      "blockNumber": "0xc481e2",
      "transactionHash": "0xcd46330358ed58eced0b35e2466a6edf49c4a3e1e9402f16a3744a4f1ec83eb5",
      "transactionIndex": "0x0",
      "logIndex": "0x0",
      "removed": false
    }
  }
}

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
method	string	Always "rise_subscription" for notifications.
params.subscription	string	The subscription ID returned earlier.
params.result.address	string	The contract address from which this log originated.
params.result.topics	array	Array of topics provided by the log.
params.result.data	string	The data associated with the log.
params.result.blockHash	string or null	The hash of the block containing the log, or null if the log is only in a $\mathtt{Shred}$ (not yet finalized in a block).
params.result.blockNumber	string	The block number where this log was included (hex string).
params.result.transactionHash	string	Hash of the transaction containing the log.
params.result.transactionIndex	string	Index of the transaction within the block (hex string).
params.result.logIndex	string	Index of the log within the block (hex string).
params.result.removed	boolean	true if the log was removed due to a chain reorganization, otherwise false.

---

$\mathtt{Shred}$ Subscription

The $\mathtt{Shred}$ subscription enables clients to receive detailed notifications about $\mathtt{Shreds}$—sub-blocks that contain transactions and state changes before they are finalized in a block. This is useful for advanced monitoring, analytics, or building real-time tools that need to react to state changes as soon as they occur in the network.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "rise_subscribe",
  "params": []
}

Parameter Descriptions

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
id	integer	An identifier for this request. Used to match responses with requests.
method	string	The RPC method to call. Always "rise_subscribe".
params	array	Empty

---

Example Response

Initial Subscription Response

{"jsonrpc":"2.0","id":1,"result":"0x656cd5c476a0616f0f0e588949eab10e"}

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
id	integer	The same ID as in the request, for matching.
result	string	The subscription ID. Use this to unsubscribe if needed.

---

$\mathtt{Shred}$ Notification

{
  "jsonrpc":"2.0",
  "method":"rise_subscription",
  "params":{
    "subscription":"0x656cd5c476a0616f0f0e588949eab10e",
    "result":{
      "block_number":12878495,
      "shred_idx":19,
      "transactions":[
        {
          "transaction":{
            "type":"0x0",
            "chainId":"0xaa39db",
            "nonce":"0x30",
            "gasPrice":"0x186a0",
            "gas":"0x5208",
            "to":"0x431bfa4dda71620e9e84ec4cfc0f70bf4559518e",
            "value":"0x23f66ed85c7c",
            "input":"0x",
            "r":"0x7c8cb16371f0970327afa0455b233f07c2bec3552f27b1120af93ee6e9a4f055",
            "s":"0x43b5e009cffb86cc5eaf146863aed4e964cfdcf1d2a508ef17e07cd6161b44a",
            "v":"0x15473da",
            "hash":"0xea02d5268e0b90c079958f2169e92bf551cd0bcd8ad14af643f849c03b7043c6"
          },
          "receipt":{
            "Legacy":{
              "status":"0x1",
              "cumulativeGasUsed":"0x668a0",
              "logs":[]
            }
          }
        }
      ],
      "state_changes":{
        "0x420000000000000000000000000000000000001a":{
          "nonce":0,
          "balance":"0x2003435b15d552b2b",
          "storage":{},
          "new_code":null
        },
        "0x420000000000000000000000000000000000001b":{
          "nonce":0,
          "balance":"0x0",
          "storage":{},
          "new_code":null
        },
        "0xa093680ec5ebf2df821a3b861c8f853e2f8c8a53":{
          "nonce":49,
          "balance":"0xf9dd239417b91",
          "storage":{},
          "new_code":null
        },
        "0x431bfa4dda71620e9e84ec4cfc0f70bf4559518e":{
          "nonce":49,
          "balance":"0xabaad195142ac",
          "storage":{},
          "new_code":null
        },
        "0x4200000000000000000000000000000000000011":{
          "nonce":0,
          "balance":"0x809eb257c095cae43",
          "storage":{},
          "new_code":null
        },
        "0x4200000000000000000000000000000000000019":{
          "nonce":0,
          "balance":"0x11e9cd67a21df",
          "storage":{},
          "new_code":null
        }
      }
    }
  }
}

Field	Type	Description
jsonrpc	string	The JSON-RPC protocol version. Always "2.0".
method	string	Always "rise_subscription" for notifications.
params.subscription	string	The subscription ID returned earlier.
params.result.block_number	integer	The block number this $\mathtt{Shred}$ is associated with.
params.result.shred_idx	integer	The index of this $\mathtt{Shred}$ within the block.
params.result.transactions	array	Array of objects, each containing: - transaction: Transaction object (fields as in Ethereum). - receipt: Receipt object (fields as in Ethereum).
params.result.state_changes	object	Mapping from account address to state change: - nonce: Account nonce after this $\mathtt{Shred}$. - balance: Account balance after this $\mathtt{Shred}$ (hex string). - storage: Mapping of storage slots to values. - new_code: New contract code if deployed, otherwise null.

---