feat(contract): add occurrence param to Spec.findEvent (#1574)

Author: Ryang-21

CHANGELOG.md

@@ -10,7 +10,7 @@ A breaking change will get clearly marked in this log.
 - `authorizeEntry` / `authorizeInvocation` signing callbacks now receive the 32-byte signing payload (`hash(preimage.toXDR())`) as a second argument alongside the preimage, so signers — including HSMs and remote signers that only accept a digest — never have to re-derive it. Existing single-argument callbacks are unaffected ([#1532](https://github.com/stellar/js-stellar-sdk/issues/1532)).
 - `authorizeEntry` / `authorizeInvocation` now support non-Ed25519 signers: the signing callback may return `{ signatureScVal: xdr.ScVal, address?: string }`, and the given `ScVal` is written verbatim as the credentials' signature — no Ed25519 verification, no `{public_key, signature}` map, no `scvVec` wrapping. This lets smart-wallet / custom-account contracts (whose `__check_auth` expects its own signature structure) use the helper instead of hand-rolling preimage construction and credential assembly. The optional `address` routes the signature to a specific credential node, like `forAddress` ([#1530](https://github.com/stellar/js-stellar-sdk/issues/1530)).
 - `contract.Signer`: an interface pairing an `address` with the SEP-43 `signTransaction` and optional `signAuthEntry` methods, plus `contract.KeypairSigner`, a `Keypair`-backed implementation. The `signTransaction` and `signAuthEntry` options — on `ClientOptions`, `MethodOptions`, and `AssembledTransaction`'s `sign` / `signAndSend` / `signAuthEntries` — now accept a `Signer` or a bare `Keypair` in addition to a callback. Adds the `contract.SignTransactionLike` and `contract.SignAuthEntryLike` types. When `signAuthEntries` gets a `Signer` or `Keypair`, its default target `address` is now the signer's own address rather than `publicKey`. Existing callbacks work unchanged; one type-only caveat: the option fields are no longer plain function types, so derive callback shapes from `contract.SignTransaction` / `contract.SignAuthEntry` instead of the option field ([#1567](https://github.com/stellar/js-stellar-sdk/pull/1567), closes [#1462](https://github.com/stellar/js-stellar-sdk/issues/1462) and [#1063](https://github.com/stellar/js-stellar-sdk/issues/1063)).
-- `contract.Spec` now reads SEP-48 event declarations: `events()` and `findEvent(name)` list a contract's declared events, `parseEvent(topics, data)` decodes a fired event into `{ name, data }`, with topic-carried params merged into `data` (returns `undefined` when nothing matches), and `eventTopicFilter(name, topicValues?)` builds a `getEvents` filter row, with `"*"` for any topic param left unset. Generated client bindings gain a typed `<Name>Event` interface per event, a `ContractEvent` union, a `parseEvent()` method, and per-event `<name>EventFilter()` methods. Generated helper names receive a numeric suffix when needed to avoid a contract-method collision. Adds the `contract.ParsedEvent` type ([#1556](https://github.com/stellar/js-stellar-sdk/pull/1556), [#1565](https://github.com/stellar/js-stellar-sdk/pull/1565)).
+- `contract.Spec` now reads SEP-48 event declarations: `events()` and `findEvent(name, occurrence?)` list a contract's declared events, `parseEvent(topics, data)` decodes a fired event into `{ name, data }`, with topic-carried params merged into `data` (returns `undefined` when nothing matches), and `eventTopicFilter(name, topicValues?, occurrence?)` builds a `getEvents` filter row, with `"*"` for any topic param left unset. Generated client bindings gain a typed `<Name>Event` interface per event, a `ContractEvent` union, a `parseEvent()` method, and per-event `<name>EventFilter()` methods. A contract may declare the same event name more than once (composed modules each emitting their own `transfer`); each declaration gets its own interface and filter method, and `occurrence` — a 0-based index in declaration order — selects among them. Generated names receive a numeric suffix when needed to avoid a collision, and `stellar-sdk bindings` warns about duplicate declarations and renames. Adds the `contract.ParsedEvent` type ([#1556](https://github.com/stellar/js-stellar-sdk/pull/1556), [#1565](https://github.com/stellar/js-stellar-sdk/pull/1565), [#1572](https://github.com/stellar/js-stellar-sdk/pull/1572)).
 
 ### Fixed
 - `Spec.scValToNative` now handles contract values typed as `Val`

docs/reference/contracts-client.md

@@ -1060,7 +1060,7 @@ class Spec {
   events(): ScSpecEventV0[];
   eventTopicFilter(name: string, topicValues?: Record<string, any>, occurrence?: number): string[];
   findEntry(name: string): ScSpecEntry;
-  findEvent(name: string): ScSpecEventV0 | undefined;
+  findEvent(name: string, occurrence?: number): ScSpecEventV0 | undefined;
   funcArgsToScVals(name: string, args: object): ScVal[];
   funcResToNative(name: string, val_or_base64: string | ScVal): any;
   funcs(): ScSpecFunctionV0[];
@@ -1219,7 +1219,7 @@ a single topic filter row
 const topics = contractSpec.eventTopicFilter('transfer', { to: someAddress });
 ```
 
-**Source:** [src/contract/spec.ts:1307](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1307)
+**Source:** [src/contract/spec.ts:1312](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1312)
 
 ### `spec.findEntry(name)`
 
@@ -1243,7 +1243,7 @@ the entry
 
 **Source:** [src/contract/spec.ts:658](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L658)
 
-### `spec.findEvent(name)`
+### `spec.findEvent(name, occurrence)`
 
 Finds the XDR event spec for the given event name.
 
@@ -1252,17 +1252,24 @@ returns `undefined` so callers can probe a contract for an event without
 wrapping the call in a `try`.
 
 ```ts
-findEvent(name: string): ScSpecEventV0 | undefined;
+findEvent(name: string, occurrence?: number): ScSpecEventV0 | undefined;
 ```
 
 **Parameters**
 
 - **`name`** — `string` (required) — the name of the event
+- **`occurrence`** — `number` (optional) — (optional) 0-based index among same-named events, in
+         declaration order, for contracts that declare the same event name
+         more than once (defaults to the first)
 
 **Returns**
 
 the event spec, or `undefined` if the contract declares no event
-         with that name
+         with that name (at that occurrence)
+
+**Throws**
+
+- if `occurrence` is not a non-negative integer
 
 **Example**
 
@@ -1272,7 +1279,7 @@ if (contractSpec.findEvent("transfer")) {
 }
 ```
 
-**Source:** [src/contract/spec.ts:1246](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1246)
+**Source:** [src/contract/spec.ts:1251](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1251)
 
 ### `spec.funcArgsToScVals(name, args)`
 
@@ -1395,7 +1402,7 @@ the converted JSON schema
 
 - if the contract spec is invalid
 
-**Source:** [src/contract/spec.ts:1331](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1331)
+**Source:** [src/contract/spec.ts:1336](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1336)
 
 ### `spec.nativeToScVal(val, ty)`
 
@@ -1459,7 +1466,7 @@ if (parsed) {
 }
 ```
 
-**Source:** [src/contract/spec.ts:1278](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1278)
+**Source:** [src/contract/spec.ts:1283](https://github.com/stellar/js-stellar-sdk/blob/main/src/contract/spec.ts#L1283)
 
 ### `spec.scValStrToNative(scv, typeDef)`
 

src/contract/spec.ts

@@ -1233,8 +1233,13 @@ export class Spec {
    * wrapping the call in a `try`.
    *
    * @param name - the name of the event
+   * @param occurrence - (optional) 0-based index among same-named events, in
+   *        declaration order, for contracts that declare the same event name
+   *        more than once (defaults to the first)
    * @returns the event spec, or `undefined` if the contract declares no event
-   *          with that name
+   *          with that name (at that occurrence)
+   *
+   * @throws if `occurrence` is not a non-negative integer
    *
    * @example
    * ```ts
@@ -1243,8 +1248,8 @@ export class Spec {
    * }
    * ```
    */
-  findEvent(name: string): xdr.ScSpecEventV0 | undefined {
-    return findEventImpl(this.entries, name);
+  findEvent(name: string, occurrence?: number): xdr.ScSpecEventV0 | undefined {
+    return findEventImpl(this.entries, name, occurrence);
   }
 
   /**

test/unit/spec/event_spec.test.ts

@@ -81,6 +81,48 @@ describe("Spec events", () => {
     expect(() => spec.eventTopicFilter("nope")).toThrow(/no such event: nope/);
   });
 
+  it("findEvent selects among same-named events by occurrence", () => {
+    // Composed contracts can declare the same event name more than once, with
+    // different params; `occurrence` picks one in declaration order.
+    const first = new xdr.ScSpecEventV0({
+      doc: "",
+      lib: "",
+      name: "transfer",
+      prefixTopics: ["transfer"],
+      params: [param("amount", i128Type, DATA)],
+      dataFormat: xdr.ScSpecEventDataFormat.scSpecEventDataFormatSingleValue(),
+    });
+    const second = new xdr.ScSpecEventV0({
+      doc: "",
+      lib: "",
+      name: "transfer",
+      prefixTopics: ["transfer"],
+      params: [param("count", u32Type, DATA)],
+      dataFormat: xdr.ScSpecEventDataFormat.scSpecEventDataFormatSingleValue(),
+    });
+    const spec = new Spec([entryFor(first), entryFor(second)]);
+
+    // No occurrence means the first declaration, as before.
+    expect(spec.findEvent("transfer")?.params()[0].name().toString()).toBe(
+      "amount",
+    );
+    expect(spec.findEvent("transfer", 0)?.params()[0].name().toString()).toBe(
+      "amount",
+    );
+    expect(spec.findEvent("transfer", 1)?.params()[0].name().toString()).toBe(
+      "count",
+    );
+
+    // Past the last declaration is a miss, not an error — same as an
+    // undeclared name.
+    expect(spec.findEvent("transfer", 2)).toBeUndefined();
+
+    // A nonsensical occurrence is a caller bug, so it throws rather than
+    // quietly returning undefined.
+    expect(() => spec.findEvent("transfer", -1)).toThrow(/invalid occurrence/);
+    expect(() => spec.findEvent("transfer", 1.5)).toThrow(/invalid occurrence/);
+  });
+
   it("parses singleValue data format events, round-tripping natives", () => {
     const event = new xdr.ScSpecEventV0({
       doc: "",