@thru/thru-sdk 0.0.4

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@thru/thru-sdk",
+  "version": "0.0.4",
+  "type": "module",
+  "main": "./dist/sdk.js",
+  "types": "./dist/sdk.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/sdk.js",
+      "types": "./dist/sdk.d.ts"
+    }
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.9.0",
+    "@connectrpc/connect": "^2.1.0",
+    "@connectrpc/connect-web": "^2.1.0",
+    "@noble/ed25519": "^2.3.0",
+    "@noble/hashes": "^1.4.0"
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "^1.58.0",
+    "@bufbuild/protoc-gen-es": "^2.9.0",
+    "ts-node": "^10.9.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "get-height": "ts-node thru-ts-client-sdk/get-height.ts",
+    "counter": "tsx --tsconfig tsconfig.json thru-ts-client-sdk/counter.ts",
+    "create-account": "tsx --tsconfig tsconfig.json thru-ts-client-sdk/create-account.ts",
+    "protobufs:pull": "rm -rf proto && cp -a ../../../proto ./proto",
+    "protobufs:generate": "buf generate --include-imports",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "test:transactions": "node --loader ts-node/esm --test \"thru-ts-client-sdk/transactions/__tests__/*.test.ts\"",
+    "clean": "rm -rf dist"
+  }
+}

package/proto/thru/common/v1/consensus.proto

@@ -0,0 +1,75 @@
+edition = "2023";
+
+package thru.common.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/common/v1;commonv1";
+option java_multiple_files = true;
+option java_package = "network.thru.common.v1";
+option csharp_namespace = "Thru.Common.V1";
+option ruby_package = "Thru::Common::V1";
+option objc_class_prefix = "THU";
+option swift_prefix = "THU";
+
+// ConsensusStatus represents the minimum consensus level a resource has
+// achieved when returned by the service.
+enum ConsensusStatus {
+  // CONSENSUS_STATUS_UNSPECIFIED indicates the consensus status is unknown.
+  CONSENSUS_STATUS_UNSPECIFIED = 0;
+
+  // CONSENSUS_STATUS_OBSERVED indicates the resource has been observed but
+  // not yet confirmed in a finalized block.
+  CONSENSUS_STATUS_OBSERVED = 1;
+
+  // CONSENSUS_STATUS_INCLUDED indicates the resource has been included in the
+  // ledger but may not be finalized.
+  CONSENSUS_STATUS_INCLUDED = 2;
+
+  // CONSENSUS_STATUS_FINALIZED indicates the resource is finalized for a slot.
+  CONSENSUS_STATUS_FINALIZED = 3;
+
+  // CONSENSUS_STATUS_LOCALLY_EXECUTED indicates the local node executed the
+  // resource but broader cluster finality may not have been achieved.
+  CONSENSUS_STATUS_LOCALLY_EXECUTED = 4;
+
+  // CONSENSUS_STATUS_CLUSTER_EXECUTED indicates the entire cluster has
+  // executed and agreed on the resource.
+  CONSENSUS_STATUS_CLUSTER_EXECUTED = 5;
+}
+
+// VersionContext selects which logical version of a resource should be
+// returned. At least one field must be set.
+message VersionContext {
+  option (buf.validate.message).cel = {
+    id: "version_context_has_selector"
+    message: "one of current, slot, or timestamp must be set"
+    expression: "has(this.current) || has(this.slot) || has(this.timestamp)"
+  };
+
+  // Specifies the desired version semantics.
+  oneof version {
+    // Request the latest version available at request time.
+    CurrentVersion current = 1 [(google.api.field_behavior) = OPTIONAL];
+
+    // Request the latest version, or historical on.
+    CurrentOrHistoricalVersion currentOrHistorical = 2 [(google.api.field_behavior) = OPTIONAL];
+
+    // Request the version for a specific slot number.
+    uint64 slot = 3 [(google.api.field_behavior) = OPTIONAL];
+
+    // Request the version nearest to the provided block timestamp.
+    google.protobuf.Timestamp timestamp = 4
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+}
+
+// CurrentVersion is an empty marker message for VersionContext.current.
+message CurrentVersion {}
+
+// CurrentOrHistoricalVersion is an empty marker message for VersionContext.current.
+message CurrentOrHistoricalVersion {}

package/proto/thru/common/v1/errors.proto

@@ -0,0 +1,67 @@
+edition = "2023";
+
+package thru.common.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/common/v1;commonv1";
+option java_multiple_files = true;
+option java_package = "network.thru.common.v1";
+option csharp_namespace = "Thru.Common.V1";
+option ruby_package = "Thru::Common::V1";
+option objc_class_prefix = "THU";
+option swift_prefix = "THU";
+
+// ErrorType captures structured error categories returned by the services.
+enum ErrorType {
+  // ERROR_TYPE_UNSPECIFIED is an unknown error condition.
+  ERROR_TYPE_UNSPECIFIED = 0;
+
+  // ERROR_TYPE_NOT_FOUND indicates requested data does not exist.
+  ERROR_TYPE_NOT_FOUND = 1;
+
+  // ERROR_TYPE_NOT_RETAINED indicates requested data was not retained under TTL.
+  ERROR_TYPE_NOT_RETAINED = 2;
+
+  // ERROR_TYPE_NOT_FOUND_OR_NOT_RETAINED indicates an ambiguous not found vs TTL case.
+  ERROR_TYPE_NOT_FOUND_OR_NOT_RETAINED = 3;
+
+  // ERROR_TYPE_INVALID_REQUEST indicates the request failed validation.
+  ERROR_TYPE_INVALID_REQUEST = 4;
+
+  // ERROR_TYPE_CEL_VALIDATION_FAILED indicates a CEL filter failed validation.
+  ERROR_TYPE_CEL_VALIDATION_FAILED = 5;
+
+  // ERROR_TYPE_INTERNAL_ERROR indicates an internal server error occurred.
+  ERROR_TYPE_INTERNAL_ERROR = 6;
+}
+
+// ErrorDetail provides structured error metadata attached to gRPC errors.
+message ErrorDetail {
+  // High-level error category.
+  ErrorType error_type = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Human-readable error summary.
+  string message = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).string.max_len = 1024
+  ];
+
+  // Optional retention window expressed in slots when applicable.
+  uint64 retention_window_slots = 3
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional retention cutoff timestamp when applicable.
+  google.protobuf.Timestamp retention_cutoff = 4
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional name of the field associated with the error.
+  string field_name = 5 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 128
+  ];
+}

package/proto/thru/common/v1/filters.proto

@@ -0,0 +1,50 @@
+edition = "2023";
+
+package thru.common.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/common/v1;commonv1";
+option java_multiple_files = true;
+option java_package = "network.thru.common.v1";
+option csharp_namespace = "Thru.Common.V1";
+option ruby_package = "Thru::Common::V1";
+option objc_class_prefix = "THU";
+option swift_prefix = "THU";
+
+// Filter represents a CEL-based expression applied to query or stream results.
+message Filter {
+  // CEL expression applied server-side. Empty expressions are treated as no-op.
+  string expression = 1 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 4096
+  ];
+
+  // Named parameter bindings for expression parameterization.
+  map<string, string> params = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// CelFilterValidation describes the validation configuration returned to
+// clients to help them build safe filter expressions.
+message CelFilterValidation {
+  // List of allowed CEL function names for a specific request type.
+  repeated string allowed_functions = 1 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).repeated.max_items = 128
+  ];
+
+  // List of allowed field names accessible to the CEL expression.
+  repeated string allowed_fields = 2 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).repeated.max_items = 256
+  ];
+
+  // Maximum AST node count permitted for a CEL expression.
+  uint32 max_complexity = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).uint32.lte = 1000
+  ];
+}

package/proto/thru/common/v1/pagination.proto

@@ -0,0 +1,47 @@
+edition = "2023";
+
+package thru.common.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/common/v1;commonv1";
+option java_multiple_files = true;
+option java_package = "network.thru.common.v1";
+option csharp_namespace = "Thru.Common.V1";
+option ruby_package = "Thru::Common::V1";
+option objc_class_prefix = "THU";
+option swift_prefix = "THU";
+
+// PageRequest contains pagination parameters for listing RPCs.
+message PageRequest {
+  // Maximum number of items to return in a single response.
+  uint32 page_size = 1 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).uint32.gte = 1,
+    (buf.validate.field).uint32.lte = 1000
+  ];
+
+  // Token identifying the position to resume from.
+  string page_token = 2 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 512
+  ];
+
+  // Optional ordering specification in "field [asc|desc]" form.
+  string order_by = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 256
+  ];
+}
+
+// PageResponse captures pagination metadata returned with list results.
+message PageResponse {
+  // Token to retrieve the next page of results, if any.
+  string next_page_token = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Total number of items available when known.
+  uint64 total_size = 2 [(google.api.field_behavior) = OPTIONAL];
+}

package/proto/thru/core/v1/account.proto

@@ -0,0 +1,138 @@
+edition = "2023";
+
+package thru.core.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+import "thru/common/v1/consensus.proto";
+import "thru/core/v1/types.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/core/v1;corev1";
+option java_multiple_files = true;
+option java_package = "network.thru.core.v1";
+option csharp_namespace = "Thru.Core.V1";
+option ruby_package = "Thru::Core::V1";
+option objc_class_prefix = "THUC";
+option swift_prefix = "THUC";
+
+// AccountView controls which sections of account resources are returned.
+enum AccountView {
+  // ACCOUNT_VIEW_UNSPECIFIED uses service defaults.
+  ACCOUNT_VIEW_UNSPECIFIED = 0;
+
+  // ACCOUNT_VIEW_PUBKEY_ONLY returns only the account address.
+  ACCOUNT_VIEW_PUBKEY_ONLY = 1;
+
+  // ACCOUNT_VIEW_META_ONLY returns only account metadata.
+  ACCOUNT_VIEW_META_ONLY = 2;
+
+  // ACCOUNT_VIEW_DATA_ONLY returns only account data.
+  ACCOUNT_VIEW_DATA_ONLY = 3;
+
+  // ACCOUNT_VIEW_FULL returns address, metadata, and data.
+  ACCOUNT_VIEW_FULL = 4;
+}
+
+// AccountFlags enumerates boolean account capability flags.
+message AccountFlags {
+  bool is_program = 1 [(google.api.field_behavior) = OPTIONAL];
+  bool is_privileged = 2 [(google.api.field_behavior) = OPTIONAL];
+  bool is_uncompressable = 3 [(google.api.field_behavior) = OPTIONAL];
+  bool is_ephemeral = 4 [(google.api.field_behavior) = OPTIONAL];
+  bool is_deleted = 5 [(google.api.field_behavior) = OPTIONAL];
+  bool is_new = 6 [(google.api.field_behavior) = OPTIONAL];
+  bool is_compressed = 7 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// AccountMeta captures metadata associated with an account.
+message AccountMeta {
+  uint32 version = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).uint32.gte = 1
+  ];
+  AccountFlags flags = 2 [(google.api.field_behavior) = OPTIONAL];
+  uint32 data_size = 3 [(google.api.field_behavior) = REQUIRED];
+  uint64 state_counter = 4 [(google.api.field_behavior) = OPTIONAL];
+  Pubkey owner = 5 [(google.api.field_behavior) = REQUIRED];
+  uint64 balance = 6 [(google.api.field_behavior) = OPTIONAL];
+  uint64 nonce = 7 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// AccountData contains account data payloads.
+message AccountData {
+  bytes data = 1 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).bytes.max_len = 16777216
+  ];
+  bool compressed = 2 [(google.api.field_behavior) = OPTIONAL];
+  string compression_algorithm = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 64
+  ];
+}
+
+// DataSlice describes a contiguous range of account data to return.
+message DataSlice {
+  uint32 offset = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).uint64.lte = 16777216
+  ];
+  uint32 length = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).uint64.lte = 16777216
+  ];
+}
+
+// AccountPage represents a 4KB chunk for streaming account data.
+message AccountPage {
+  uint32 page_idx = 1 [(google.api.field_behavior) = REQUIRED];
+  uint32 page_size = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).uint32.lte = 4096
+  ];
+  bytes page_data = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.max_len = 4096
+  ];
+  bool compressed = 4 [(google.api.field_behavior) = OPTIONAL];
+  string compression_algorithm = 5 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).string.max_len = 64
+  ];
+}
+
+// VersionContextMetadata captures context for a returned account state.
+message VersionContextMetadata {
+  uint64 slot = 1 [(google.api.field_behavior) = OPTIONAL];
+  google.protobuf.Timestamp block_timestamp = 2
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Account models a fully decoded account resource.
+message Account {
+  Pubkey address = 1 [(google.api.field_behavior) = REQUIRED];
+  AccountMeta meta = 2 [(google.api.field_behavior) = OPTIONAL];
+  AccountData data = 3 [(google.api.field_behavior) = OPTIONAL];
+  VersionContextMetadata version_context = 4
+      [(google.api.field_behavior) = OPTIONAL];
+  thru.common.v1.ConsensusStatus consensus_status = 5
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// RawAccount captures raw serialized account bytes.
+message RawAccount {
+  Pubkey address = 1 [(google.api.field_behavior) = REQUIRED];
+  bytes raw_meta = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.max_len = 4096
+  ];
+  bytes raw_data = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).bytes.max_len = 16777216
+  ];
+  VersionContextMetadata version_context = 4
+      [(google.api.field_behavior) = OPTIONAL];
+}

package/proto/thru/core/v1/block.proto

@@ -0,0 +1,82 @@
+edition = "2023";
+
+package thru.core.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+import "thru/common/v1/consensus.proto";
+import "thru/core/v1/types.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/core/v1;corev1";
+option java_multiple_files = true;
+option java_package = "network.thru.core.v1";
+option csharp_namespace = "Thru.Core.V1";
+option ruby_package = "Thru::Core::V1";
+option objc_class_prefix = "THUC";
+option swift_prefix = "THUC";
+
+// BlockView controls how much of a block resource is returned.
+enum BlockView {
+  BLOCK_VIEW_UNSPECIFIED = 0;
+  BLOCK_VIEW_HEADER_ONLY = 1;
+  BLOCK_VIEW_HEADER_AND_FOOTER = 2;
+  BLOCK_VIEW_BODY_ONLY = 3;
+  BLOCK_VIEW_FULL = 4;
+}
+
+// BlockHeader describes metadata about a block.
+message BlockHeader {
+  uint64 slot = 1 [(google.api.field_behavior) = REQUIRED];
+  BlockHash block_hash = 2 [(google.api.field_behavior) = REQUIRED];
+  Signature header_signature = 3 [(google.api.field_behavior) = REQUIRED];
+  uint32 version = 4 [(google.api.field_behavior) = REQUIRED];
+  Pubkey producer = 5 [(google.api.field_behavior) = REQUIRED];
+  google.protobuf.Timestamp expiry_timestamp = 6
+      [(google.api.field_behavior) = OPTIONAL];
+  uint64 start_slot = 7 [(google.api.field_behavior) = OPTIONAL];
+  uint32 expiry_after = 8 [(google.api.field_behavior) = OPTIONAL];
+  uint32 max_block_size = 9 [(google.api.field_behavior) = OPTIONAL];
+  uint64 max_compute_units = 10 [(google.api.field_behavior) = OPTIONAL];
+  uint32 max_state_units = 11 [(google.api.field_behavior) = OPTIONAL];
+  uint64 price = 12 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// ExecutionStatus enumerates block execution results.
+enum ExecutionStatus {
+  EXECUTION_STATUS_UNSPECIFIED = 0;
+  EXECUTION_STATUS_PENDING = 1;
+  EXECUTION_STATUS_EXECUTED = 2;
+  EXECUTION_STATUS_FAILED = 3;
+}
+
+// BlockFooter captures execution result metadata for a block.
+message BlockFooter {
+  Signature signature = 1 [(google.api.field_behavior) = REQUIRED];
+  ExecutionStatus status = 2 [(google.api.field_behavior) = REQUIRED];
+  uint64 consumed_compute_units = 3 [(google.api.field_behavior) = OPTIONAL];
+  uint32 consumed_state_units = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Block represents a fully decoded block resource.
+message Block {
+  BlockHeader header = 1 [(google.api.field_behavior) = REQUIRED];
+  BlockFooter footer = 2 [(google.api.field_behavior) = OPTIONAL];
+  bytes body = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).bytes.max_len = 33554432
+  ];
+  thru.common.v1.ConsensusStatus consensus_status = 4
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// RawBlock captures raw block bytes for direct access.
+message RawBlock {
+  uint64 slot = 1 [(google.api.field_behavior) = REQUIRED];
+  bytes raw_block = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.max_len = 33554432
+  ];
+}

package/proto/thru/core/v1/state.proto

@@ -0,0 +1,37 @@
+edition = "2023";
+
+package thru.core.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "google/api/field_behavior.proto";
+import "thru/core/v1/types.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/core/v1;corev1";
+option java_multiple_files = true;
+option java_package = "network.thru.core.v1";
+option csharp_namespace = "Thru.Core.V1";
+option ruby_package = "Thru::Core::V1";
+option objc_class_prefix = "THUC";
+option swift_prefix = "THUC";
+
+// StateProofType selects the type of state proof to generate.
+enum StateProofType {
+  STATE_PROOF_TYPE_UNSPECIFIED = 0;
+  STATE_PROOF_TYPE_CREATING = 1;
+  STATE_PROOF_TYPE_UPDATING = 2;
+  STATE_PROOF_TYPE_EXISTING = 3;
+}
+
+// StateProofRequest describes a request to generate an account state proof.
+message StateProofRequest {
+  Pubkey address = 1 [(google.api.field_behavior) = REQUIRED];
+  StateProofType proof_type = 2 [(google.api.field_behavior) = REQUIRED];
+  uint64 target_slot = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// StateProof returns binary proof data along with context.
+message StateProof {
+  bytes proof = 1 [(google.api.field_behavior) = REQUIRED];
+  uint64 slot = 2 [(google.api.field_behavior) = REQUIRED];
+}

package/proto/thru/core/v1/transaction.proto

@@ -0,0 +1,95 @@
+edition = "2023";
+
+package thru.core.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+import "thru/core/v1/types.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/core/v1;corev1";
+option java_multiple_files = true;
+option java_package = "network.thru.core.v1";
+option csharp_namespace = "Thru.Core.V1";
+option ruby_package = "Thru::Core::V1";
+option objc_class_prefix = "THUC";
+option swift_prefix = "THUC";
+
+// TransactionView controls how transactions are materialized in responses.
+enum TransactionView {
+  TRANSACTION_VIEW_UNSPECIFIED = 0;
+  TRANSACTION_VIEW_SIGNATURE_ONLY = 1;
+  TRANSACTION_VIEW_HEADER_ONLY = 2;
+  TRANSACTION_VIEW_HEADER_AND_BODY = 3;
+  TRANSACTION_VIEW_FULL = 4;
+}
+
+// TransactionHeader carries structured metadata for a transaction.
+message TransactionHeader {
+  Signature fee_payer_signature = 1 [(google.api.field_behavior) = REQUIRED];
+  uint32 version = 2 [(google.api.field_behavior) = REQUIRED];
+  uint32 flags = 3 [(google.api.field_behavior) = OPTIONAL];
+  uint32 readwrite_accounts_count = 4 [(google.api.field_behavior) = OPTIONAL];
+  uint32 readonly_accounts_count = 5 [(google.api.field_behavior) = OPTIONAL];
+  uint32 instruction_data_size = 6 [(google.api.field_behavior) = OPTIONAL];
+  uint32 requested_compute_units = 7 [(google.api.field_behavior) = OPTIONAL];
+  uint32 requested_state_units = 8 [(google.api.field_behavior) = OPTIONAL];
+  uint32 requested_memory_units = 9 [(google.api.field_behavior) = OPTIONAL];
+  uint32 expiry_after = 10 [(google.api.field_behavior) = OPTIONAL];
+  uint64 fee = 11 [(google.api.field_behavior) = OPTIONAL];
+  uint64 nonce = 12 [(google.api.field_behavior) = OPTIONAL];
+  uint64 start_slot = 13 [(google.api.field_behavior) = OPTIONAL];
+  Pubkey fee_payer_pubkey = 14 [(google.api.field_behavior) = OPTIONAL];
+  Pubkey program_pubkey = 15 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// TransactionExecutionResult captures execution outcomes.
+message TransactionExecutionResult {
+  uint32 consumed_compute_units = 1 [(google.api.field_behavior) = OPTIONAL];
+  uint32 consumed_memory_units = 2 [(google.api.field_behavior) = OPTIONAL];
+  uint32 consumed_state_units = 3 [(google.api.field_behavior) = OPTIONAL];
+  uint64 user_error_code = 4 [(google.api.field_behavior) = OPTIONAL];
+  uint32 vm_error = 5 [(google.api.field_behavior) = OPTIONAL];
+  uint64 execution_result = 6 [(google.api.field_behavior) = OPTIONAL];
+  uint32 pages_used = 7 [(google.api.field_behavior) = OPTIONAL];
+  uint32 events_count = 8 [(google.api.field_behavior) = OPTIONAL];
+  uint32 events_size = 9 [(google.api.field_behavior) = OPTIONAL];
+  repeated Pubkey readwrite_accounts = 10
+      [(google.api.field_behavior) = OPTIONAL];
+  repeated Pubkey readonly_accounts = 11
+      [(google.api.field_behavior) = OPTIONAL];
+  repeated TransactionEvent events = 12
+      [(google.api.field_behavior) = OPTIONAL];
+}
+// TransactionEvent describes an event emitted during transaction execution.
+message TransactionEvent {
+  string event_id = 1 [(google.api.field_behavior) = OPTIONAL];
+  uint32 call_idx = 2 [(google.api.field_behavior) = OPTIONAL];
+  uint32 program_idx = 3 [(google.api.field_behavior) = OPTIONAL];
+  Pubkey program = 4 [(google.api.field_behavior) = OPTIONAL];
+  bytes payload = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Transaction describes a fully decoded transaction resource.
+message Transaction {
+  Signature signature = 1 [(google.api.field_behavior) = REQUIRED];
+  TransactionHeader header = 2 [(google.api.field_behavior) = OPTIONAL];
+  bytes body = 3 [
+    (google.api.field_behavior) = OPTIONAL,
+    (buf.validate.field).bytes.max_len = 16777216
+  ];
+  TransactionExecutionResult execution_result = 4
+      [(google.api.field_behavior) = OPTIONAL];
+  uint64 slot = 5 [(google.api.field_behavior) = OPTIONAL];
+  uint32 block_offset = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// RawTransaction provides direct access to serialized transaction bytes.
+message RawTransaction {
+  Signature signature = 1 [(google.api.field_behavior) = REQUIRED];
+  bytes raw_transaction = 2 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.max_len = 16777216
+  ];
+}

package/proto/thru/core/v1/types.proto

@@ -0,0 +1,52 @@
+edition = "2023";
+
+package thru.core.v1;
+
+option features.field_presence = EXPLICIT;
+
+import "buf/validate/validate.proto";
+import "google/api/field_behavior.proto";
+
+option go_package = "github.com/Unto-Labs/thru-net/grpc/pkg/proto/thru/core/v1;corev1";
+option java_multiple_files = true;
+option java_package = "network.thru.core.v1";
+option csharp_namespace = "Thru.Core.V1";
+option ruby_package = "Thru::Core::V1";
+option objc_class_prefix = "THUC";
+option swift_prefix = "THUC";
+
+// Pubkey represents a 32-byte public key value.
+message Pubkey {
+  // 32-byte public key buffer.
+  bytes value = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.len = 32
+  ];
+}
+
+// Hash represents a 32-byte hash value.
+message Hash {
+  // 32-byte hash buffer.
+  bytes value = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.len = 32
+  ];
+}
+
+// BlockHash represents a 64-byte hash for block identifiers.
+message BlockHash {
+  // 64-byte block hash buffer.
+  bytes value = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.len = 64
+  ];
+}
+
+// Signature represents a 64-byte signature value.
+message Signature {
+  // 64-byte signature buffer.
+  bytes value = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (buf.validate.field).bytes.len = 64
+  ];
+}