Add multi-agent simulation specifications and TypeScript steps

FEATURE_COVERAGE.md

@@ -756,7 +756,7 @@
 | Feature                         | TS       | Go      | Rust     | Java     | Kotlin | Python  | .NET     | C++     | Swift |
 | ------------------------------- | -------- | ------- | -------- | -------- | ------ | ------- | -------- | ------- | ----- |
 | **error-handling** `@required`  | 🟡 28/30 | 🟡 1/30 | 🟡 27/30 | 🟡 28/30 | 🟡     | ❌ 0/30 | 🟡 15/30 | ❌ 0/30 | ❌    |
-| **simulation** `@preferred`     | 🟡 21/26 | ❌ 0/26 | ❌ 0/26  | ❌ 0/26  | ❌     | ❌ 0/26 | ❌ 0/26  | ❌ 0/26 | ❌    |
+| **simulation** `@preferred`     | 🟡 19/31 | ❌ 0/31 | ❌ 0/31  | ❌ 0/31  | ❌     | ❌ 0/31 | ❌ 0/31  | ❌ 0/31 | ❌    |
 | **multi-agent** `@optional`     | ✅ 20/20 | ❌ 0/20 | ❌ 0/20  | ❌ 0/20  | ❌     | ❌ 0/20 | ❌ 0/20  | ❌ 0/20 | ❌    |
 | **fee-payer** `@optional`       | ✅ 23/23 | ❌ 0/23 | ❌ 0/23  | ❌ 0/23  | ❌     | ❌ 0/23 | ❌ 0/23  | ❌ 0/23 | ❌    |
 | **multi-signature** `@optional` | ✅ 23/23 | ❌ 0/23 | ❌ 0/23  | ❌ 0/23  | ❌     | ❌ 0/23 | ❌ 0/23  | ❌ 0/23 | ❌    |
@@ -818,16 +818,21 @@
 | 14  | Simulate at specific version          | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
 | 15  | Simulate with gas override            | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
 | 16  | Simulate with gas price override      | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 17  | Simulate multi-agent tx               | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 18  | Simulate fee payer tx                 | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 19  | Simulation doesn't commit             | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 20  | Simulation may differ from exec       | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 21  | Simulation with current seq           | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 22  | Simulate multiple txs                 | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 23  | Simulate tx sequence                  | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 24  | Simulation network error              | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 25  | Invalid tx for simulation             | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
-| 26  | Simulation timeout                    | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 17  | Multi-agent sim with signer pubkeys   | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 18  | Multi-agent sim without pubkeys       | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 19  | Multi-agent sim with partial checks   | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 20  | Reject malformed signer key mapping   | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 21  | Multi-agent sim includes changes      | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 22  | Multi-agent + fee payer sim (skip)    | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 23  | Multi-agent + fee payer sim (keys)    | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 24  | Simulation doesn't commit             | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 25  | Simulation may differ from exec       | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 26  | Simulation with current seq           | ✅  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 27  | Simulate multiple txs                 | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 28  | Simulate tx sequence                  | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 29  | Simulation network error              | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 30  | Invalid tx for simulation             | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
+| 31  | Simulation timeout                    | ❌  | ❌  | ❌   | ❌   | ❌     | ❌     | ❌   | ❌  | ❌    |
 
 ### multi-agent.feature `@optional`
 

features/06-advanced/simulation.feature

@@ -134,17 +134,64 @@ Feature: Transaction Simulation
   # Multi-Agent Simulation
   # =============================================================================
   @preferred
-  Scenario: Simulate multi-agent transaction
+  Scenario: Simulate multi-agent tx with signerPublicKey + secondarySignersPublicKeys
     Given a multi-agent transaction
+    And sender public key is provided for simulation
+    And secondary signer public keys are provided for simulation
     When I simulate it
     Then simulation should work
+    And auth-key checks should run for all provided signers
+
+  @preferred
+  Scenario: Simulate multi-agent tx with no public keys (skip auth-key checks)
+    Given a multi-agent transaction
+    And no signer public keys are provided for simulation
+    When I simulate it
+    Then simulation should work
+    And auth-key checks should be skipped
+
+  @preferred
+  Scenario: Simulate multi-agent tx with partial auth-key checks using undefined placeholders
+    Given a multi-agent simulation transaction with 3 secondary signers
+    And sender public key is provided for simulation
+    And secondary signer public keys include undefined placeholders
+    When I simulate it
+    Then simulation should work
+    And auth-key checks should run only for provided signer slots
+
+  @preferred
+  Scenario: Reject simulation input when secondary signer key mapping is malformed
+    Given a multi-agent simulation transaction with 2 secondary signers
+    And secondary signer public key mapping has wrong length
+    When I try to simulate
+    Then I should get validation error before simulation even runs
+
+  @preferred
+  Scenario: Simulation result includes changes/events across involved accounts
+    Given a multi-agent transaction
+    And a simulation result covering sender and secondary accounts
+    When I inspect the multi-agent simulation result
+    Then simulation should work
     And show changes for all involved accounts
+    And it should include events for involved accounts
 
   @preferred
-  Scenario: Simulate fee payer transaction
-    Given a fee payer transaction
+  Scenario: Simulate multi-agent + fee payer transaction with skipped auth-key checks
+    Given a fee payer transaction with sender, secondary, and sponsor
+    And no signer public keys are provided for simulation
     When I simulate it
-    Then gas should be charged to fee payer
+    Then simulation should work
+    And gas should be charged to fee payer
+    And simulation should reflect that
+
+  @preferred
+  Scenario: Simulate multi-agent + fee payer transaction with explicit signer key checks
+    Given a fee payer transaction with sender, secondary, and sponsor
+    And sender, secondary, and fee payer public keys are provided for simulation
+    When I simulate it
+    Then simulation should work
+    And gas should be charged to fee payer
+    And auth-key checks should run for all provided signers
     And simulation should reflect that
 
   # =============================================================================

features/06-advanced/spec.md

@@ -164,6 +164,25 @@ message = SHA3-256("APTOS::RawTransactionWithData") || bcs(FeePayer {
 
 ---
 
+## Transaction Simulation Semantics (Preferred - P1)
+
+### Description
+
+Simulation validates transaction structure and executes VM logic without committing state.
+
+### Multi-Agent / Fee Payer Simulation Rules
+
+- Simulation input MAY include sender, secondary signer, and fee payer public keys for optional
+  authentication key checks.
+- SDKs MAY allow simulation when signer public keys are omitted; in this mode, authentication key
+  checks are skipped.
+- For multi-agent simulation, SDKs MAY support partial checks by allowing undefined placeholders in
+  secondary signer public key slots.
+- Simulation does NOT require full transaction authenticator validation and does NOT imply the
+  transaction can be submitted successfully on-chain.
+
+---
+
 ## Keyless Accounts (Optional - P2)
 
 ### Description

specifications/07-advanced-features.md

@@ -553,11 +553,50 @@ Transaction simulation executes a transaction without committing, returning expe
 ```
 simulate(
     raw_txn: RawTransaction,
-    sender_public_key: PublicKey
+    sender_public_key: Option<PublicKey>
 ) -> Result<SimulationResult, Error>
 ```
 
-### 6.3 Simulation Result [P1]
+`sender_public_key` is optional for SDKs that support skipping authentication key checks in
+simulation.
+
+### 6.3 Multi-Agent / Fee Payer Simulation Inputs [P1]
+
+For multi-agent and fee payer simulation, SDKs MAY accept additional signer public keys to run
+authentication key checks before simulation.
+
+**TypeScript-style shape (illustrative):**
+
+```
+simulate_multi_agent(
+    raw_txn: RawTransaction,
+    secondary_signer_addresses: Vec<AccountAddress>,
+    signer_public_key: Option<PublicKey>,
+    secondary_signers_public_keys: Option<Vec<Option<PublicKey>>>
+) -> Result<SimulationResult, Error>
+
+simulate_fee_payer(
+    raw_txn: RawTransaction,
+    secondary_signer_addresses: Vec<AccountAddress>,
+    fee_payer_address: AccountAddress,
+    signer_public_key: Option<PublicKey>,
+    secondary_signers_public_keys: Option<Vec<Option<PublicKey>>>,
+    fee_payer_public_key: Option<PublicKey>
+) -> Result<SimulationResult, Error>
+```
+
+**Requirements:**
+
+1. If signer public keys are provided, SDK **MUST** check provided signer/address mappings via
+   authentication keys.
+2. If signer public keys are omitted, SDK **MAY** skip authentication key checks and still simulate.
+3. For multi-agent simulation, SDK **MAY** support partial checks by allowing `undefined`/`None`
+   entries in secondary signer key slots.
+4. Malformed key mappings (e.g., address count and key-slot count mismatch) **MUST** fail validation
+   before simulation request execution.
+5. Simulation **MUST NOT** be treated as full transaction authenticator validation.
+
+### 6.4 Simulation Result [P1]
 
 | Field     | Type        | Description                    |
 | --------- | ----------- | ------------------------------ |
@@ -567,7 +606,7 @@ simulate(
 | changes   | Vec<Change> | State changes that would occur |
 | events    | Vec<Event>  | Events that would be emitted   |
 
-### 6.4 Use Cases [P1]
+### 6.5 Use Cases [P1]
 
 1. **Gas Estimation:** Determine gas needed before submission
 2. **Error Preview:** Check for errors before submission
@@ -718,7 +757,7 @@ Test vectors in `test-vectors/multi-sig.json`:
 - `features/06-advanced/multi-agent.feature` - 22 multi-agent scenarios
 - `features/06-advanced/fee-payer.feature` - 23 fee payer scenarios
 - `features/06-advanced/keyless.feature` - 28 keyless scenarios
-- `features/06-advanced/simulation.feature` - 23 simulation scenarios
+- `features/06-advanced/simulation.feature` - 31 simulation scenarios
 - `features/06-advanced/codegen.feature` - 30 codegen scenarios
 
 ### 10.3 Test Vectors

tests/typescript/SDK_STATUS.md

@@ -1,7 +1,7 @@
 # TypeScript SDK Test Status
 
-> **Last Updated:** 2026-02-23  
-> **Last Verified:** 2026-02-23 via `bun run cucumber-js`
+> **Last Updated:** 2026-03-17  
+> **Last Verified:** 2026-03-17 via `bun run cucumber-js --dry-run --format summary`
 
 ---
 
@@ -25,15 +25,15 @@
 | Required (P0)  | ~494     | 580     | ~85%       | 🟡     |
 | Preferred (P1) | included | -       | -          | -      |
 | Optional (P2)  | included | -       | -          | -      |
-| **Total**      | **494**  | **791** | **62%**    | 🟡     |
+| **Total**      | **494**  | **796** | **62%**    | 🟡     |
 
 > **Notes:**
 >
-> - 580 non-network/perf scenarios: 494 passed, 49 failed, 37 undefined
+> - 584 non-network/perf scenarios: 494 passed, 49 failed, 41 undefined
 > - 133 api-client scenarios: Require network access (timeout without network)
 > - 78 network/performance scenarios: Require live devnet/testnet
 > - 49 failures in Secp256r1, simulation, retry
-> - 37 undefined (codegen, some advanced features)
+> - 41 undefined (codegen, some advanced features)
 > - Some keyless and script tests use mocks
 
 ---
@@ -237,16 +237,17 @@ To add or update tests for this SDK:
 | 03-account-management   | 84     | 0      | 0         | 84    |
 | 04-transaction-building | 69     | 0      | 0         | 69    |
 | 05-api-clients          | ~80    | ~4     | ~10       | ~190  |
-| 06-advanced             | 116    | 36     | 37        | 189   |
+| 06-advanced             | 116    | 36     | 42        | 194   |
 
 > **Note:** API client tests require network connectivity (devnet/testnet) and timeout in CI
 > environments without network access. Results for 05-api-clients are estimated from previous runs.
+> 06-advanced total/undefined counts reflect spec updates validated by dry-run.
 
 ### Dry Run Summary (all scenarios)
 
 ```
-791 scenarios (750 with step definitions, 41 undefined)
-3058 steps (136 undefined, 2922 defined)
+796 scenarios (755 with step definitions, 41 undefined)
+3090 steps (136 undefined, 2954 defined)
 ```
 
 ### Non-Network Test Summary
@@ -256,5 +257,5 @@ core-types:    121 passed
 cryptography:  79 passed, 13 failed
 accounts:      84 passed
 transactions:  69 passed
-advanced:      116 passed, 36 failed, 37 undefined
+advanced:      116 passed, 36 failed, 42 undefined
 ```