@layerzerolabs/protocol-stellar-v2 0.2.8 → 0.2.10

package/contracts/utils/src/tests/buffer_reader.rs

@@ -2,1005 +2,766 @@ use soroban_sdk::{address_payload::AddressPayload, testutils::Address as _, Addr
 
 use crate::buffer_reader::BufferReader;
 use crate::buffer_writer::BufferWriter;
+use crate::bytes_ext::BytesExt;
 
-#[test]
-fn test_new_buffer_reader() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0u8, 1, 2, 3, 4, 5]);
-    let _reader = BufferReader::new(&bytes);
-
-    // Verify reader is created (we can't access pos directly but can verify by reading)
-    assert!(true); // Successfully created
-}
-
-#[test]
-fn test_read_u32() {
-    let env = Env::default();
-    // Create bytes representing u32 value 0x01020304 (16909060 in decimal)
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u32();
-    assert_eq!(value, 0x01020304u32);
-}
-
-#[test]
-fn test_read_u32_zero() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00, 0x00, 0x00, 0x00]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u32();
-    assert_eq!(value, 0u32);
-}
-
-#[test]
-fn test_read_u32_max_value() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF, 0xFF, 0xFF, 0xFF]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u32();
-    assert_eq!(value, u32::MAX);
-}
-
-#[test]
-fn test_read_u64() {
-    let env = Env::default();
-    // Create bytes representing u64 value 0x0102030405060708
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
-    let mut reader = BufferReader::new(&bytes);
+use crate::tests::test_helper::{assert_address_payload_matches, assert_panics_contains};
 
-    let value = reader.read_u64();
-    assert_eq!(value, 0x0102030405060708u64);
-}
+type ReaderStep = fn(&mut BufferReader);
 
-#[test]
-fn test_read_u64_zero() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u64();
-    assert_eq!(value, 0u64);
+fn assert_reader_panics_contains(case: &str, raw: &[u8], step: ReaderStep, expected_substring: &str) {
+    assert_panics_contains(case, expected_substring, || {
+        let env = Env::default();
+        let bytes = Bytes::from_slice(&env, raw);
+        let mut reader = BufferReader::new(&bytes);
+        step(&mut reader);
+    });
 }
 
-#[test]
-fn test_read_u64_max_value() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]);
+/// Helper to test U256 read roundtrip
+fn test_u256_read_roundtrip(env: &Env, value: &soroban_sdk::U256) {
+    let mut writer = BufferWriter::new(env);
+    writer.write_u256(value.clone());
+    let bytes = writer.to_bytes();
     let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u64();
-    assert_eq!(value, u64::MAX);
+    assert_eq!(reader.read_u256(), *value);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
-#[test]
-fn test_sequential_reads() {
-    let env = Env::default();
-
-    // Create a buffer with multiple values:
-    // - u32: 0x01020304
-    // - u64: 0x0102030405060708
-    // - another u32: 0xAABBCCDD
-    let buffer_array: [u8; 16] = [
-        0x01, 0x02, 0x03, 0x04, // u32
-        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, // u64
-        0xAA, 0xBB, 0xCC, 0xDD, // u32
-    ];
+/// Helper to test address roundtrip
+fn test_address_roundtrip(env: &Env, address: &Address) {
+    let mut writer = BufferWriter::new(env);
+    writer.write_address(address);
+    let bytes = writer.to_bytes();
 
-    let bytes = Bytes::from_array(&env, &buffer_array);
     let mut reader = BufferReader::new(&bytes);
+    let read_address = reader.read_address();
 
-    // Read in sequence and verify position is being tracked correctly
-    let val1 = reader.read_u32();
-    assert_eq!(val1, 0x01020304u32);
-
-    let val2 = reader.read_u64();
-    assert_eq!(val2, 0x0102030405060708u64);
-
-    let val3 = reader.read_u32();
-    assert_eq!(val3, 0xAABBCCDDu32);
+    assert_eq!(read_address, *address);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
-#[test]
-fn test_read_multiple_u32() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0x00, 0x00, 0x00, 0x01, // 1
-            0x00, 0x00, 0x00, 0x02, // 2
-            0x00, 0x00, 0x00, 0x03, // 3
-        ],
-    );
-    let mut reader = BufferReader::new(&bytes);
-
-    assert_eq!(reader.read_u32(), 1u32);
-    assert_eq!(reader.read_u32(), 2u32);
-    assert_eq!(reader.read_u32(), 3u32);
-}
+// ============================================
+// read_primitives tests (u8, u16, u32, u64, u128, u256, bool)
+// ============================================
 
 #[test]
-fn test_read_multiple_u64() {
+fn test_read_primitives_big_endian_golden_bytes() {
     let env = Env::default();
     let bytes = Bytes::from_array(
         &env,
         &[
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, // 1
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, // 2
+            0x12, // u8
+            0x34, 0x56, // u16
+            0x78, 0x9A, 0xBC, 0xDE, // u32
+            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, // u64
+            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F,
+            0x10, // u128
         ],
     );
     let mut reader = BufferReader::new(&bytes);
 
-    assert_eq!(reader.read_u64(), 1u64);
-    assert_eq!(reader.read_u64(), 2u64);
-}
-
-#[test]
-#[should_panic]
-fn test_read_u32_insufficient_bytes_empty() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
-    let mut reader = BufferReader::new(&bytes);
-
-    // Should panic - no bytes available
-    reader.read_u32();
+    assert_eq!(reader.read_u8(), 0x12);
+    assert_eq!(reader.read_u16(), 0x3456);
+    assert_eq!(reader.read_u32(), 0x789ABCDE);
+    assert_eq!(reader.read_u64(), 0x0102030405060708);
+    assert_eq!(reader.read_u128(), 0x0102030405060708090a0b0c0d0e0f10);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-#[should_panic]
-fn test_read_u32_insufficient_bytes_partial() {
+fn test_read_primitives_roundtrip() {
     let env = Env::default();
-    // Only 3 bytes, need 4 for u32
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03]);
-    let mut reader = BufferReader::new(&bytes);
-
-    // Should panic - not enough bytes
-    reader.read_u32();
-}
+    let mut writer = BufferWriter::new(&env);
+    writer
+        .write_u8(0x12)
+        .write_u16(0x3456)
+        .write_u32(0x789ABCDE)
+        .write_u64(0x0102030405060708)
+        .write_u128(0x0102030405060708090a0b0c0d0e0f10);
 
-#[test]
-#[should_panic]
-fn test_read_u32_insufficient_bytes_one() {
-    let env = Env::default();
-    // Only 1 byte, need 4 for u32
-    let bytes = Bytes::from_array(&env, &[0x01]);
+    let bytes = writer.to_bytes();
     let mut reader = BufferReader::new(&bytes);
 
-    // Should panic - not enough bytes
-    reader.read_u32();
+    assert_eq!(reader.read_u8(), 0x12);
+    assert_eq!(reader.read_u16(), 0x3456);
+    assert_eq!(reader.read_u32(), 0x789ABCDE);
+    assert_eq!(reader.read_u64(), 0x0102030405060708);
+    assert_eq!(reader.read_u128(), 0x0102030405060708090a0b0c0d0e0f10);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-#[should_panic]
-fn test_read_u64_insufficient_bytes_empty() {
+fn test_read_boundary_values() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
-    let mut reader = BufferReader::new(&bytes);
+    let mut writer = BufferWriter::new(&env);
 
-    // Should panic - no bytes available
-    reader.read_u64();
-}
+    // Write boundary values for each type
+    writer
+        .write_u8(0)
+        .write_u8(u8::MAX)
+        .write_u16(0)
+        .write_u16(u16::MAX)
+        .write_u32(0)
+        .write_u32(u32::MAX)
+        .write_u64(0)
+        .write_u64(u64::MAX)
+        .write_u128(0)
+        .write_u128(u128::MAX);
 
-#[test]
-#[should_panic]
-fn test_read_u64_insufficient_bytes_partial() {
-    let env = Env::default();
-    // Only 7 bytes, need 8 for u64
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]);
+    let bytes = writer.to_bytes();
     let mut reader = BufferReader::new(&bytes);
 
-    // Should panic - not enough bytes
-    reader.read_u64();
+    assert_eq!(reader.read_u8(), 0);
+    assert_eq!(reader.read_u8(), u8::MAX);
+    assert_eq!(reader.read_u16(), 0);
+    assert_eq!(reader.read_u16(), u16::MAX);
+    assert_eq!(reader.read_u32(), 0);
+    assert_eq!(reader.read_u32(), u32::MAX);
+    assert_eq!(reader.read_u64(), 0);
+    assert_eq!(reader.read_u64(), u64::MAX);
+    assert_eq!(reader.read_u128(), 0);
+    assert_eq!(reader.read_u128(), u128::MAX);
 }
 
 #[test]
-#[should_panic]
-fn test_read_u64_insufficient_bytes_only_four() {
+fn test_read_bool() {
     let env = Env::default();
-    // Only 4 bytes, need 8 for u64
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
+    let bytes = Bytes::from_array(&env, &[0x00, 0x01, 0x02, 0x7F, 0x80, 0xFF]);
     let mut reader = BufferReader::new(&bytes);
 
-    // Should panic - not enough bytes
-    reader.read_u64();
+    assert!(!reader.read_bool()); // 0x00 -> false
+    assert!(reader.read_bool()); // 0x01 -> true
+    assert!(reader.read_bool()); // 0x02 -> true (any non-zero is true)
+    assert!(reader.read_bool()); // 0x7F -> true
+    assert!(reader.read_bool()); // 0x80 -> true
+    assert!(reader.read_bool()); // 0xFF -> true
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-#[should_panic]
-fn test_sequential_reads_run_out_of_bytes() {
+fn test_read_u256_boundary_values() {
+    use soroban_sdk::U256;
     let env = Env::default();
 
-    // Only enough for u32 and partial u64
-    let buffer_array: [u8; 10] = [
-        0x01, 0x02, 0x03, 0x04, // u32 (4 bytes)
-        0x01, 0x02, 0x03, 0x04, 0x05, 0x06, // partial u64 (only 6 bytes, need 8)
-    ];
-
-    let bytes = Bytes::from_array(&env, &buffer_array);
-    let mut reader = BufferReader::new(&bytes);
+    // Zero
+    let zero = U256::from_u32(&env, 0);
+    test_u256_read_roundtrip(&env, &zero);
 
-    // First read succeeds
-    let _val1 = reader.read_u32();
+    // From u128::MAX
+    let from_u128_max = U256::from_u128(&env, u128::MAX);
+    test_u256_read_roundtrip(&env, &from_u128_max);
 
-    // Second read should panic - not enough bytes for u64
-    reader.read_u64();
+    // Max (all 0xFF bytes)
+    let max_bytes = Bytes::from_array(&env, &[0xFF; 32]);
+    let max_u256 = U256::from_be_bytes(&env, &max_bytes);
+    test_u256_read_roundtrip(&env, &max_u256);
 }
 
-#[test]
-#[should_panic]
-fn test_read_after_buffer_exhausted() {
-    let env = Env::default();
-    // Exactly 4 bytes
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
-    let mut reader = BufferReader::new(&bytes);
-
-    // First read succeeds and exhausts the buffer
-    let _val = reader.read_u32();
-
-    // Second read should panic - no bytes left
-    reader.read_u32();
-}
+// ============================================
+// read_bytes tests (read_bytes, read_bytes_n)
+// ============================================
 
-// Tests for read() method
 #[test]
-fn test_read() {
+fn test_read_bytes_operations() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06]);
     let mut reader = BufferReader::new(&bytes);
 
+    // Read partial
     let chunk1 = reader.read_bytes(3);
     assert_eq!(chunk1.len(), 3);
     assert_eq!(chunk1.get(0).unwrap(), 0x01);
-    assert_eq!(chunk1.get(1).unwrap(), 0x02);
     assert_eq!(chunk1.get(2).unwrap(), 0x03);
 
-    let chunk2 = reader.read_bytes(2);
-    assert_eq!(chunk2.len(), 2);
+    // Read remaining
+    let chunk2 = reader.read_bytes_until_end();
+    assert_eq!(chunk2.len(), 3);
     assert_eq!(chunk2.get(0).unwrap(), 0x04);
-    assert_eq!(chunk2.get(1).unwrap(), 0x05);
-}
-
-#[test]
-fn test_read_single_byte() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xAB]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let chunk = reader.read_bytes(1);
-    assert_eq!(chunk.len(), 1);
-    assert_eq!(chunk.get(0).unwrap(), 0xAB);
+    assert_eq!(chunk2.get(2).unwrap(), 0x06);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_read_entire_buffer() {
+fn test_read_bytes_n() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
+    let bytes = Bytes::from_array(
+        &env,
+        &[
+            0x01, 0x02, 0x03, 0x04, // 4 bytes
+            0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, // 8 bytes
+            0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21,
+            0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f, // 32 bytes
+        ],
+    );
     let mut reader = BufferReader::new(&bytes);
 
-    let chunk = reader.read_bytes(4);
-    assert_eq!(chunk.len(), 4);
-    assert_eq!(chunk.get(0).unwrap(), 0x01);
-    assert_eq!(chunk.get(3).unwrap(), 0x04);
-}
-
-// Tests for rewind() method
-#[test]
-fn test_rewind() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06]);
-    let mut reader = BufferReader::new(&bytes);
+    let val4: BytesN<4> = reader.read_bytes_n();
+    assert_eq!(val4, BytesN::<4>::from_array(&env, &[0x01, 0x02, 0x03, 0x04]));
 
-    // Read 4 bytes
-    let _chunk1 = reader.read_bytes(4);
+    let val8: BytesN<8> = reader.read_bytes_n();
+    assert_eq!(val8, BytesN::<8>::from_array(&env, &[0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c]));
 
-    // Rewind 2 bytes
-    reader.rewind(2);
+    let val32: BytesN<32> = reader.read_bytes_n();
+    assert_eq!(
+        val32,
+        BytesN::<32>::from_array(
+            &env,
+            &[
+                0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+                0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f
+            ]
+        )
+    );
 
-    // Read again should get bytes starting from position 2
-    let chunk2 = reader.read_bytes(2);
-    assert_eq!(chunk2.get(0).unwrap(), 0x03);
-    assert_eq!(chunk2.get(1).unwrap(), 0x04);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_rewind_chaining() {
+fn test_read_bytes_zero_length() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    reader.read_bytes(4);
-    // Test that rewind returns &mut Self for chaining
-    let chunk = reader.rewind(2).read_bytes(1);
-    assert_eq!(chunk.get(0).unwrap(), 0x03);
-}
-
-#[test]
-fn test_rewind_to_start() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xAA, 0xBB, 0xCC]);
-    let mut reader = BufferReader::new(&bytes);
-
-    reader.read_bytes(3);
-    reader.rewind(3);
+    // Read zero bytes should return empty bytes and not advance position
+    let chunk = reader.read_bytes(0);
+    assert_eq!(chunk.len(), 0);
+    assert_eq!(reader.position(), 0);
 
-    let chunk = reader.read_bytes(1);
-    assert_eq!(chunk.get(0).unwrap(), 0xAA);
+    // Should be able to read normally after zero-length read
+    assert_eq!(reader.read_u8(), 0x01);
 }
 
-// Tests for read_u8() method
-#[test]
-fn test_read_u8() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x42]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u8();
-    assert_eq!(value, 0x42);
-}
+// ============================================
+// read_bytes_until_end tests
+// ============================================
 
 #[test]
-fn test_read_u8_zero() {
+fn test_read_bytes_until_end_at_start() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_u8();
-    assert_eq!(value, 0u8);
+    let all_bytes = reader.read_bytes_until_end();
+    assert_eq!(all_bytes.len(), 4);
+    assert_eq!(all_bytes.get(0).unwrap(), 0x01);
+    assert_eq!(all_bytes.get(3).unwrap(), 0x04);
+    assert_eq!(reader.remaining_len(), 0);
+    assert_eq!(reader.position(), 4);
 }
 
 #[test]
-fn test_read_u8_max_value() {
+fn test_read_bytes_until_end_after_partial_read() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05]);
     let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_u8();
-    assert_eq!(value, u8::MAX);
+    reader.read_u16(); // Position is now 2
+    assert_eq!(reader.position(), 2);
+    let remaining = reader.read_bytes_until_end();
+    assert_eq!(remaining.len(), 3);
+    assert_eq!(remaining.get(0).unwrap(), 0x03);
+    assert_eq!(remaining.get(2).unwrap(), 0x05);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_read_multiple_u8() {
+fn test_read_bytes_until_end_when_exhausted() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    assert_eq!(reader.read_u8(), 0x01);
-    assert_eq!(reader.read_u8(), 0x02);
-    assert_eq!(reader.read_u8(), 0x03);
-    assert_eq!(reader.read_u8(), 0x04);
+    // Exhaust buffer by reading all bytes
+    reader.read_bytes(4);
+    assert_eq!(reader.remaining_len(), 0);
+
+    // read_bytes_until_end on exhausted buffer should return empty Bytes
+    let empty = reader.read_bytes_until_end();
+    assert_eq!(empty.len(), 0);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-#[should_panic]
-fn test_read_u8_insufficient_bytes() {
+fn test_read_bytes_until_end_on_empty_buffer() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[]);
     let mut reader = BufferReader::new(&bytes);
 
-    reader.read_u8();
+    assert_eq!(reader.remaining_len(), 0);
+    let empty = reader.read_bytes_until_end();
+    assert_eq!(empty.len(), 0);
+    assert_eq!(reader.remaining_len(), 0);
+    assert_eq!(reader.position(), 0);
 }
 
-// Tests for read_u16() method
-#[test]
-fn test_read_u16() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x12, 0x34]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u16();
-    assert_eq!(value, 0x1234u16);
-}
+// ============================================
+// read_address tests
+// ============================================
 
 #[test]
-fn test_read_u16_zero() {
+fn test_read_address_contract_roundtrip() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00, 0x00]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u16();
-    assert_eq!(value, 0u16);
+    let address = Address::generate(&env);
+    let payload = address.to_payload().unwrap();
+    assert!(matches!(payload, AddressPayload::ContractIdHash(_)));
+    test_address_roundtrip(&env, &address);
 }
 
 #[test]
-fn test_read_u16_max_value() {
+fn test_read_address_account_roundtrip() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF, 0xFF]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u16();
-    assert_eq!(value, u16::MAX);
+    let account_payload = BytesN::<32>::from_array(
+        &env,
+        &[
+            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12,
+            0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
+        ],
+    );
+    let address = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(account_payload));
+    let payload = address.to_payload().unwrap();
+    assert!(matches!(payload, AddressPayload::AccountIdPublicKeyEd25519(_)));
+    test_address_roundtrip(&env, &address);
 }
 
 #[test]
-fn test_read_multiple_u16() {
+fn test_read_address_all_zero_payload() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00, 0x01, 0x00, 0x02, 0x00, 0x03]);
-    let mut reader = BufferReader::new(&bytes);
-
-    assert_eq!(reader.read_u16(), 1u16);
-    assert_eq!(reader.read_u16(), 2u16);
-    assert_eq!(reader.read_u16(), 3u16);
+    let zero_payload = BytesN::<32>::from_array(&env, &[0x00; 32]);
+    let addr = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(zero_payload));
+    test_address_roundtrip(&env, &addr);
 }
 
 #[test]
-#[should_panic]
-fn test_read_u16_insufficient_bytes_empty() {
+fn test_read_address_mixed_types_roundtrip() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
-    let mut reader = BufferReader::new(&bytes);
-
-    reader.read_u16();
-}
+    let contract_addr = Address::generate(&env);
+    let account_payload = BytesN::<32>::from_array(&env, &[0x42; 32]);
+    let account_addr = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(account_payload));
 
-#[test]
-#[should_panic]
-fn test_read_u16_insufficient_bytes_one() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01]);
-    let mut reader = BufferReader::new(&bytes);
+    let mut writer = BufferWriter::new(&env);
+    writer.write_address(&contract_addr).write_address(&account_addr);
+    let bytes = writer.to_bytes();
 
-    reader.read_u16();
-}
+    assert_eq!(bytes.len(), 66); // 33 bytes per address
 
-// Tests for read_u256() method
-#[test]
-fn test_read_u256() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04,
-        ],
-    );
     let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u256();
-    let expected = soroban_sdk::U256::from_u32(&env, 0x01020304);
-    assert_eq!(value, expected);
+    assert_eq!(reader.read_address(), contract_addr);
+    assert_eq!(reader.read_address(), account_addr);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_read_u256_zero() {
+fn test_address_encoding_golden_bytes() {
     let env = Env::default();
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
-            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
-        ],
-    );
-    let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_u256();
-    let expected = soroban_sdk::U256::from_u32(&env, 0);
-    assert_eq!(value, expected);
-}
+    let account_payload = BytesN::<32>::from_array(&env, &[0x42; 32]);
+    let contract_payload = BytesN::<32>::from_array(&env, &[0x99; 32]);
 
-#[test]
-fn test_read_u256_max_value() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-            0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
-        ],
-    );
-    let mut reader = BufferReader::new(&bytes);
+    let account_addr = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(account_payload.clone()));
+    let contract_addr = Address::from_payload(&env, AddressPayload::ContractIdHash(contract_payload.clone()));
 
-    let value = reader.read_u256();
-    // Verify it's a large number by checking it's not zero
-    assert!(value > soroban_sdk::U256::from_u32(&env, 0));
-}
+    let mut w = BufferWriter::new(&env);
+    w.write_address(&account_addr).write_address(&contract_addr);
+    let bytes = w.to_bytes();
 
-#[test]
-#[should_panic]
-fn test_read_u256_insufficient_bytes() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]); // Only 4 bytes, need 32
-    let mut reader = BufferReader::new(&bytes);
+    // Validate raw encoding: 0/1 type byte + 32-byte payload.
+    let raw: [u8; 66] = bytes.to_array();
+    assert_eq!(raw[0], crate::buffer_writer::ACCOUNT_PAYLOAD_TYPE);
+    assert_eq!(raw[1..33], account_payload.to_array());
+    assert_eq!(raw[33], crate::buffer_writer::CONTRACT_PAYLOAD_TYPE);
+    assert_eq!(raw[34..66], contract_payload.to_array());
 
-    reader.read_u256();
+    // Validate reader can decode the raw bytes too.
+    let mut r = BufferReader::new(&bytes);
+    assert_eq!(r.read_address(), account_addr);
+    assert_eq!(r.read_address(), contract_addr);
+    assert_eq!(r.remaining_len(), 0);
 }
 
-// Tests for read_bytes_until_end() method
 #[test]
-fn test_read_bytes_until_end() {
+fn test_read_address_with_other_data_roundtrip() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06]);
-    let mut reader = BufferReader::new(&bytes);
+    let address = Address::generate(&env);
 
-    reader.read_bytes(2); // Read first 2 bytes
+    let mut writer = BufferWriter::new(&env);
+    writer.write_u32(0x12345678).write_address(&address).write_u64(0xAABBCCDDEEFF0011);
+    let bytes = writer.to_bytes();
 
-    let remaining = reader.read_bytes_until_end();
-    assert_eq!(remaining.len(), 4);
-    assert_eq!(remaining.get(0).unwrap(), 0x03);
-    assert_eq!(remaining.get(1).unwrap(), 0x04);
-    assert_eq!(remaining.get(2).unwrap(), 0x05);
-    assert_eq!(remaining.get(3).unwrap(), 0x06);
-}
+    assert_eq!(bytes.len(), 4 + 33 + 8);
 
-#[test]
-fn test_read_bytes_until_end_entire_buffer() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xAA, 0xBB, 0xCC]);
     let mut reader = BufferReader::new(&bytes);
-
-    let remaining = reader.read_bytes_until_end();
-    assert_eq!(remaining.len(), 3);
-    assert_eq!(remaining.get(0).unwrap(), 0xAA);
-    assert_eq!(remaining.get(1).unwrap(), 0xBB);
-    assert_eq!(remaining.get(2).unwrap(), 0xCC);
+    assert_eq!(reader.read_u32(), 0x12345678);
+    assert_eq!(reader.read_address(), address);
+    assert_eq!(reader.read_u64(), 0xAABBCCDDEEFF0011);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_read_bytes_until_end_empty() {
+#[should_panic(expected = "Error(Contract, #1001)")]
+fn test_read_address_invalid_payload_type() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02]);
-    let mut reader = BufferReader::new(&bytes);
-
-    reader.read_bytes(2); // Exhaust the buffer
-
-    let remaining = reader.read_bytes_until_end();
-    assert_eq!(remaining.len(), 0);
-}
+    // Create bytes with invalid payload type (not 0 or 1)
+    let mut writer = BufferWriter::new(&env);
+    writer.write_u8(0xFF); // Invalid payload type
+    writer.write_bytes_n(&BytesN::<32>::from_array(&env, &[0x42; 32]));
+    let bytes = writer.to_bytes();
 
-#[test]
-fn test_read_bytes_until_end_updates_position() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
-
-    reader.read_bytes(1);
-    let _remaining = reader.read_bytes_until_end();
-
-    // After read_bytes_until_end, position should be at the end
-    assert_eq!(reader.remaining(), 0);
+    reader.read_address(); // Should panic with BufferReaderError::InvalidAddressPayload (10001)
 }
 
-// Tests for len() method
+// ============================================
+// read_address_payload tests
+// ============================================
+
 #[test]
-fn test_len() {
+fn test_read_address_payload() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05]);
-    let reader = BufferReader::new(&bytes);
+    let address = Address::generate(&env);
+    let expected_payload = address.to_payload().unwrap();
 
-    assert_eq!(reader.len(), 5);
-}
+    let mut writer = BufferWriter::new(&env);
+    writer.write_address_payload(&address);
+    let bytes = writer.to_bytes();
 
-#[test]
-fn test_len_empty_buffer() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
-    let reader = BufferReader::new(&bytes);
+    assert_eq!(bytes.len(), 32); // Only payload, no type byte
 
-    assert_eq!(reader.len(), 0);
+    let mut reader = BufferReader::new(&bytes);
+    let payload = reader.read_address_payload();
+    assert_address_payload_matches(payload, expected_payload);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_len_unchanged_after_read() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_read_address_payload_insufficient_bytes() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
+    let bytes = Bytes::from_array(&env, &[0x00; 31]); // Need 32 bytes
     let mut reader = BufferReader::new(&bytes);
-
-    assert_eq!(reader.len(), 4);
-    reader.read_bytes(2);
-    assert_eq!(reader.len(), 4); // len() should not change
+    let _payload: BytesN<32> = reader.read_address_payload();
 }
 
-// Tests for remaining() method
-#[test]
-fn test_remaining_initial() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05]);
-    let reader = BufferReader::new(&bytes);
-
-    assert_eq!(reader.remaining(), 5);
-}
+// ============================================
+// position tests
+// ============================================
 
 #[test]
-fn test_remaining_after_read() {
+fn test_position_operations() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a]);
     let mut reader = BufferReader::new(&bytes);
 
-    reader.read_bytes(2);
-    assert_eq!(reader.remaining(), 4);
+    // Test 1: Initial state
+    assert_eq!(reader.position(), 0);
+    assert_eq!(reader.remaining_len(), 10);
+    assert_eq!(reader.len(), 10);
+    assert!(!reader.is_empty());
 
-    reader.read_bytes(3);
-    assert_eq!(reader.remaining(), 1);
+    // Test 2: Read and check position/remaining relationship
+    reader.read_u32();
+    assert_eq!(reader.position(), 4);
+    assert_eq!(reader.remaining_len(), 6);
 
-    reader.read_bytes(1);
-    assert_eq!(reader.remaining(), 0);
-}
+    // Test 3: Skip operation
+    reader.skip(2);
+    assert_eq!(reader.position(), 6);
+    assert_eq!(reader.remaining_len(), 4);
 
-#[test]
-fn test_remaining_empty_buffer() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
-    let reader = BufferReader::new(&bytes);
+    // Test 4: Rewind operation
+    reader.rewind(3);
+    assert_eq!(reader.position(), 3);
+    assert_eq!(reader.remaining_len(), 7);
 
-    assert_eq!(reader.remaining(), 0);
-}
+    // Test 5: Set position operation
+    reader.seek(5);
+    assert_eq!(reader.position(), 5);
+    assert_eq!(reader.remaining_len(), 5);
 
-#[test]
-fn test_remaining_after_rewind() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
-    let mut reader = BufferReader::new(&bytes);
+    // Test 6: Set position and read
+    reader.seek(1);
+    assert_eq!(reader.position(), 1);
+    assert_eq!(reader.read_u8(), 0x02);
 
-    reader.read_bytes(3);
-    assert_eq!(reader.remaining(), 1);
+    // Test 7: Method chaining - skip -> skip -> read
+    reader.seek(0);
+    let value = reader.skip(2).skip(1).read_u8();
+    assert_eq!(value, 0x04);
+    assert_eq!(reader.position(), 4);
 
+    // Test 8: Method chaining - rewind -> read
     reader.rewind(2);
-    assert_eq!(reader.remaining(), 3);
-}
-
-#[test]
-fn test_read_u128() {
-    let env = Env::default();
-    // Create bytes representing u128 value 0x0102030405060708090a0b0c0d0e0f10
-    let bytes = Bytes::from_array(
-        &env,
-        &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10],
-    );
-    let mut reader = BufferReader::new(&bytes);
+    let value = reader.read_u8();
+    assert_eq!(value, 0x03);
+    assert_eq!(reader.position(), 3);
 
-    let value = reader.read_u128();
-    assert_eq!(value, 0x0102030405060708090a0b0c0d0e0f10u128);
+    // Test 9: Method chaining - seek -> read
+    let value = reader.seek(0).read_u8();
+    assert_eq!(value, 0x01);
+    assert_eq!(reader.position(), 1);
 }
 
-#[test]
-fn test_read_u128_zero() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00; 16]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_u128();
-    assert_eq!(value, 0u128);
-}
+// ============================================
+// seek tests
+// ============================================
 
 #[test]
-fn test_read_u128_max_value() {
+fn test_seek_boundary_values() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF; 16]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_u128();
-    assert_eq!(value, u128::MAX);
-}
+    // Set to start
+    reader.seek(0);
+    assert_eq!(reader.position(), 0);
+    assert_eq!(reader.read_u8(), 0x01);
 
-#[test]
-fn test_read_u128_specific_value() {
-    let env = Env::default();
-    // Test with a specific value: 200000 (0x030d40)
-    let mut bytes_array = [0u8; 16];
-    // Fill with zeros except for the last 3 bytes
-    bytes_array[13] = 0x03;
-    bytes_array[14] = 0x0d;
-    bytes_array[15] = 0x40;
-    let bytes = Bytes::from_array(&env, &bytes_array);
-    let mut reader = BufferReader::new(&bytes);
+    // Set to end (exact boundary - should be valid)
+    reader.seek(4);
+    assert_eq!(reader.position(), 4);
+    assert_eq!(reader.remaining_len(), 0);
 
-    let value = reader.read_u128();
-    assert_eq!(value, 200000u128);
+    // Set to middle
+    reader.seek(2);
+    assert_eq!(reader.position(), 2);
+    assert_eq!(reader.read_u8(), 0x03);
 }
 
 #[test]
-fn test_read_bytes_n() {
+fn test_seek_on_empty_buffer() {
     let env = Env::default();
-    // Create 32 bytes with a pattern
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12,
-            0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
-        ],
-    );
+    let bytes = Bytes::from_array(&env, &[]);
     let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_bytes_n::<32>();
-    let expected = BytesN::<32>::from_array(
-        &env,
-        &[
-            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12,
-            0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
-        ],
-    );
-    assert_eq!(value, expected);
+    // Should be able to set position to 0 on empty buffer
+    reader.seek(0);
+    assert_eq!(reader.position(), 0);
+    assert_eq!(reader.remaining_len(), 0);
 }
 
 #[test]
-fn test_read_bytes_n_zeros() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_seek_beyond_buffer() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x00; 32]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_bytes_n::<32>();
-    let expected = BytesN::<32>::from_array(&env, &[0x00; 32]);
-    assert_eq!(value, expected);
+    reader.seek(5); // Buffer length is 4, position 5 is invalid
 }
 
-#[test]
-fn test_read_bytes_n_all_ones() {
-    let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0xFF; 32]);
-    let mut reader = BufferReader::new(&bytes);
-
-    let value = reader.read_bytes_n::<32>();
-    let expected = BytesN::<32>::from_array(&env, &[0xFF; 32]);
-    assert_eq!(value, expected);
-}
+// ============================================
+// skip tests
+// ============================================
 
 #[test]
-fn test_read_bytes_n_different_sizes() {
+fn test_skip_zero() {
     let env = Env::default();
-    // Create buffer with 4 + 8 + 16 = 28 bytes
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0x01, 0x02, 0x03, 0x04, // 4 bytes
-            0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, // 8 bytes
-            0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
-            0x1c, // 16 bytes
-        ],
-    );
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    let val4: BytesN<4> = reader.read_bytes_n();
-    assert_eq!(val4, BytesN::<4>::from_array(&env, &[0x01, 0x02, 0x03, 0x04]));
+    reader.read_u8(); // Position is now 1
+    assert_eq!(reader.position(), 1);
 
-    let val8: BytesN<8> = reader.read_bytes_n();
-    assert_eq!(val8, BytesN::<8>::from_array(&env, &[0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c]));
-
-    let val16: BytesN<16> = reader.read_bytes_n();
-    assert_eq!(
-        val16,
-        BytesN::<16>::from_array(
-            &env,
-            &[0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c]
-        )
-    );
-
-    assert_eq!(reader.remaining(), 0);
+    // Skip zero should be no-op
+    reader.skip(0);
+    assert_eq!(reader.position(), 1);
 }
 
 #[test]
-fn test_read_bytes_n_address_pattern() {
+fn test_skip_to_exact_end() {
     let env = Env::default();
-    // Test with a typical Ethereum-style address padded to 32 bytes
-    let bytes = Bytes::from_array(
-        &env,
-        &[
-            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xf3, 0x9f, 0xd6, 0xe5, 0x1a, 0xad, 0x88, 0xf6, 0xf4, 0xce, 0x6a, 0xb8,
-            0x82, 0x72, 0x79, 0xcf, 0xff, 0xb9, 0x22, 0x66,
-        ],
-    );
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    let value = reader.read_bytes_n::<32>();
-    let expected = BytesN::<32>::from_array(
-        &env,
-        &[
-            0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xf3, 0x9f, 0xd6, 0xe5, 0x1a, 0xad, 0x88, 0xf6, 0xf4, 0xce, 0x6a, 0xb8,
-            0x82, 0x72, 0x79, 0xcf, 0xff, 0xb9, 0x22, 0x66,
-        ],
-    );
-    assert_eq!(value, expected);
-}
-
-#[test]
-fn test_sequential_reads_with_u128_and_bytes32() {
-    let env = Env::default();
-
-    // Create a buffer with:
-    // - u8: 0x01
-    // - u16: 0x0011
-    // - u128: 200000
-    // - bytes32: all 0x42s
-    let mut final_bytes = Bytes::new(&env);
-
-    // u8
-    final_bytes.push_back(0x01);
-
-    // u16
-    final_bytes.extend_from_slice(&[0x00, 0x11]);
-
-    // u128 (200000)
-    final_bytes.extend_from_slice(&200000u128.to_be_bytes());
-
-    // bytes32
-    final_bytes.extend_from_slice(&[0x42; 32]);
-
-    let mut reader = BufferReader::new(&final_bytes);
-
-    // Read in sequence
-    let val1 = reader.read_u8();
-    assert_eq!(val1, 0x01);
-
-    let val2 = reader.read_u16();
-    assert_eq!(val2, 0x0011);
+    // Skip to exactly the end (boundary case)
+    reader.skip(4);
+    assert_eq!(reader.position(), 4);
+    assert_eq!(reader.remaining_len(), 0);
 
-    let val3 = reader.read_u128();
-    assert_eq!(val3, 200000u128);
-
-    let val4 = reader.read_bytes_n::<32>();
-    let expected = BytesN::<32>::from_array(&env, &[0x42; 32]);
-    assert_eq!(val4, expected);
-
-    // Should have read everything
-    assert_eq!(reader.remaining(), 0);
+    // Should be able to read_bytes_until_end without error (returns empty)
+    let empty = reader.read_bytes_until_end();
+    assert_eq!(empty.len(), 0);
 }
 
 #[test]
-fn test_read_arbitrary_size() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_skip_beyond_buffer() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
-
-    // Read 4 bytes
-    let chunk1 = reader.read_bytes(4);
-    assert_eq!(chunk1.len(), 4);
-    assert_eq!(chunk1.get(0).unwrap(), 0x01);
-    assert_eq!(chunk1.get(3).unwrap(), 0x04);
-
-    // Read remaining 4 bytes
-    let chunk2 = reader.read_bytes(4);
-    assert_eq!(chunk2.len(), 4);
-    assert_eq!(chunk2.get(0).unwrap(), 0x05);
-    assert_eq!(chunk2.get(3).unwrap(), 0x08);
-
-    // All bytes consumed
-    assert_eq!(reader.remaining(), 0);
+    reader.skip(5);
 }
 
+// ============================================
+// rewind tests
+// ============================================
+
 #[test]
-#[should_panic]
-fn test_read_insufficient_bytes() {
+fn test_rewind_zero() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    // Try to read more bytes than available
-    // Should panic with InsufficientBytes error
-    reader.read_bytes(10);
+    reader.read_u8(); // Position is now 1
+    assert_eq!(reader.position(), 1);
+
+    // Rewind zero should be no-op
+    reader.rewind(0);
+    assert_eq!(reader.position(), 1);
 }
 
 #[test]
-#[should_panic]
-fn test_read_insufficient_bytes_after_partial_read() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_rewind_beyond_start() {
     let env = Env::default();
     let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
-
-    // Read 2 bytes successfully
-    let _chunk = reader.read_bytes(2);
-    assert_eq!(reader.remaining(), 2);
-
-    // Try to read 3 bytes when only 2 remain
-    // Should panic with InsufficientBytes error
-    reader.read_bytes(3);
+    reader.read_bytes(2);
+    reader.rewind(3); // Can only rewind 2
 }
 
-// Tests for read_address() method
 #[test]
-fn test_read_address_contract_roundtrip() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_rewind_from_start() {
     let env = Env::default();
-
-    // Address::generate() creates a Contract address
-    let original_address = Address::generate(&env);
-    let payload = original_address.to_payload().unwrap();
-    assert!(matches!(payload, AddressPayload::ContractIdHash(_)));
-
-    // Serialize using BufferWriter, then read back
-    let mut writer = BufferWriter::new(&env);
-    writer.write_address(&original_address);
-    let bytes = writer.to_bytes();
-
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03]);
     let mut reader = BufferReader::new(&bytes);
-    let read_address = reader.read_address();
-
-    assert_eq!(read_address, original_address);
-    assert_eq!(reader.remaining(), 0);
+    assert_eq!(reader.position(), 0);
+    reader.rewind(1); // Position is 0, can't rewind
 }
 
+// ============================================
+// buffer_access tests (buffer, env, is_empty, len, remaining)
+// ============================================
+
 #[test]
-fn test_read_address_account_roundtrip() {
+fn test_buffer_access_and_empty_buffer() {
     let env = Env::default();
 
-    // Create an account address from a 32-byte payload
-    let account_payload = BytesN::<32>::from_array(
-        &env,
-        &[
-            0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12,
-            0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, 0x20,
-        ],
-    );
-    let original_address = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(account_payload));
-    let payload = original_address.to_payload().unwrap();
-    assert!(matches!(payload, AddressPayload::AccountIdPublicKeyEd25519(_)));
-
-    // Serialize using BufferWriter, then read back
-    let mut writer = BufferWriter::new(&env);
-    writer.write_address(&original_address);
-    let bytes = writer.to_bytes();
-
-    let mut reader = BufferReader::new(&bytes);
-    let read_address = reader.read_address();
+    // Test 1: Buffer and env access
+    let bytes1 = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
+    let mut reader1 = BufferReader::new(&bytes1);
+    reader1.read_u16();
+    let buffer = reader1.buffer();
+    assert_eq!(buffer.len(), 4);
+    assert_eq!(buffer.get(0).unwrap(), 0x01);
+    let _new_bytes = Bytes::from_array(reader1.env(), &[0x03, 0x04]);
 
-    assert_eq!(read_address, original_address);
-    assert_eq!(reader.remaining(), 0);
+    // Test 2: Empty buffer
+    let bytes2 = Bytes::from_array(&env, &[]);
+    let reader2 = BufferReader::new(&bytes2);
+    assert!(reader2.is_empty());
+    assert_eq!(reader2.len(), 0);
+    assert_eq!(reader2.remaining_len(), 0);
+    assert_eq!(reader2.position(), 0);
 }
 
 #[test]
-fn test_read_address_mixed_types_roundtrip() {
+fn test_is_empty_semantics() {
+    // is_empty() checks if the BUFFER is empty, not if remaining bytes is zero
     let env = Env::default();
 
-    // Generate contract address
-    let contract_addr = Address::generate(&env);
-
-    // Create account address
-    let account_payload = BytesN::<32>::from_array(&env, &[0x42; 32]);
-    let account_addr = Address::from_payload(&env, AddressPayload::AccountIdPublicKeyEd25519(account_payload));
+    // Non-empty buffer: is_empty should always be false regardless of position
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
+    let mut reader = BufferReader::new(&bytes);
 
-    // Serialize both addresses (33 * 2 = 66 bytes)
-    let mut writer = BufferWriter::new(&env);
-    writer.write_address(&contract_addr);
-    writer.write_address(&account_addr);
-    let bytes = writer.to_bytes();
+    assert!(!reader.is_empty());
+    reader.read_bytes(4); // Exhaust buffer
+    assert_eq!(reader.remaining_len(), 0);
+    assert!(!reader.is_empty()); // Buffer itself is NOT empty, just fully read
 
-    assert_eq!(bytes.len(), 66); // 33 bytes per address
-
-    let mut reader = BufferReader::new(&bytes);
-    assert_eq!(reader.read_address(), contract_addr);
-    assert_eq!(reader.read_address(), account_addr);
-    assert_eq!(reader.remaining(), 0);
+    // Empty buffer: is_empty should be true
+    let empty_bytes = Bytes::from_array(&env, &[]);
+    let empty_reader = BufferReader::new(&empty_bytes);
+    assert!(empty_reader.is_empty());
 }
 
 #[test]
-fn test_read_address_with_other_data_roundtrip() {
+fn test_len_immutable_after_reads() {
+    // len() returns total buffer length, should not change after reads
     let env = Env::default();
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]);
+    let mut reader = BufferReader::new(&bytes);
 
-    let original_address = Address::generate(&env);
-
-    // Create buffer: u32 + address (33 bytes) + u64
-    let mut writer = BufferWriter::new(&env);
-    writer.write_u32(0x12345678);
-    writer.write_address(&original_address);
-    writer.write_u64(0xAABBCCDDEEFF0011);
-    let bytes = writer.to_bytes();
+    assert_eq!(reader.len(), 8);
 
-    assert_eq!(bytes.len(), 4 + 33 + 8);
+    reader.read_u32();
+    assert_eq!(reader.len(), 8); // Still 8
+
+    reader.skip(2);
+    assert_eq!(reader.len(), 8); // Still 8
+
+    reader.read_bytes_until_end();
+    assert_eq!(reader.len(), 8); // Still 8
+}
+
+// ============================================
+// insufficient_bytes_error tests
+// ============================================
+
+#[test]
+fn test_buffer_reader_invalid_length_panics_table() {
+    const EXPECTED: &str = "Error(Contract, #1000)";
+
+    let cases: &[(&str, &[u8], ReaderStep)] = &[
+        ("read_u8 empty", &[], |r: &mut BufferReader| {
+            r.read_u8();
+        }),
+        ("read_u16 1 byte", &[0x01], |r: &mut BufferReader| {
+            r.read_u16();
+        }),
+        ("read_u32 3 bytes", &[0x01, 0x02, 0x03], |r: &mut BufferReader| {
+            r.read_u32();
+        }),
+        ("read_u64 7 bytes", &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07], |r: &mut BufferReader| {
+            r.read_u64();
+        }),
+        ("read_u128 15 bytes", &[0x01; 15], |r: &mut BufferReader| {
+            r.read_u128();
+        }),
+        ("read_u256 31 bytes", &[0x01; 31], |r: &mut BufferReader| {
+            r.read_u256();
+        }),
+        ("read_bytes(10) from 4", &[0x01, 0x02, 0x03, 0x04], |r: &mut BufferReader| {
+            r.read_bytes(10);
+        }),
+        ("read_bytes_n<4> from 3", &[0x01, 0x02, 0x03], |r: &mut BufferReader| {
+            let _val: BytesN<4> = r.read_bytes_n();
+        }),
+        ("read_address from 32 (needs 33)", &[0x00; 32], |r: &mut BufferReader| {
+            r.read_address();
+        }),
+        ("read_bool empty", &[], |r: &mut BufferReader| {
+            r.read_bool();
+        }),
+    ];
 
-    let mut reader = BufferReader::new(&bytes);
-    assert_eq!(reader.read_u32(), 0x12345678);
-    assert_eq!(reader.read_address(), original_address);
-    assert_eq!(reader.read_u64(), 0xAABBCCDDEEFF0011);
-    assert_eq!(reader.remaining(), 0);
+    for (name, raw, step) in cases {
+        assert_reader_panics_contains(name, raw, *step, EXPECTED);
+    }
 }
 
 #[test]
-#[should_panic]
-fn test_read_address_insufficient_bytes_empty() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_read_after_buffer_exhausted() {
     let env = Env::default();
-    let bytes = Bytes::from_array(&env, &[]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    // Should panic - no bytes available (need 33)
-    reader.read_address();
+    let _val = reader.read_u32(); // Exhausts the buffer
+    assert_eq!(reader.remaining_len(), 0);
+    reader.read_u8(); // Should panic
 }
 
 #[test]
-#[should_panic]
-fn test_read_address_insufficient_bytes_partial() {
+#[should_panic(expected = "Error(Contract, #1000)")]
+fn test_read_insufficient_bytes_after_partial_read() {
     let env = Env::default();
-    // Only 32 bytes, need 33
-    let bytes = Bytes::from_array(&env, &[0x00; 32]);
+    let bytes = Bytes::from_array(&env, &[0x01, 0x02, 0x03, 0x04]);
     let mut reader = BufferReader::new(&bytes);
 
-    // Should panic - not enough bytes
-    reader.read_address();
+    // Read 2 bytes successfully
+    let _chunk = reader.read_bytes(2);
+    assert_eq!(reader.remaining_len(), 2);
+
+    // Try to read 3 bytes when only 2 remain
+    // Should panic with InsufficientBytes error
+    reader.read_bytes(3);
 }