sui-effect 0.1.0

package/README.md

@@ -0,0 +1,300 @@
+# sui-effect
+
+An opinionated [Effect](https://effect.website) v4 layer over
+[`@mysten/sui`](https://www.npmjs.com/package/@mysten/sui) for building safe
+TypeScript applications and on-demand agent scripts on Sui.
+
+The SDK keeps doing BCS, transaction building, signing and transport.
+sui-effect owns the shape of the program around it: two client tiers, closed
+error unions on every function, the transaction lifecycle as functions with
+typed outcomes, crash-safe submission, and time, retry and interruption through
+Effect so tests can drive them.
+
+## Install
+
+```bash
+bun add sui-effect
+bun add -d effect@4.0.0-rc.112 @mysten/sui@2.30.0
+```
+
+`effect` and `@mysten/sui` are peer dependencies: one copy of each per process,
+or `Context.Service` identities and `instanceof` checks stop matching. The
+`effect` peer is pinned **exactly** to `4.0.0-rc.112`, because rc.113 renamed
+`Config.nonEmptyString`, `Config.string` and `Config.redacted` to
+`Config.NonEmptyString`, `Config.String` and `Config.Redacted`, and neighbouring
+release candidates are not interchangeable.
+
+A **library** built on sui-effect puts all three in its own
+`peerDependencies` **and** `devDependencies`, never in `dependencies`; see
+`examples/extension-template/README.md`.
+
+## A complete script
+
+```ts
+import { bcs } from "@mysten/sui/bcs"
+import { Config, Console, Effect } from "effect"
+import { ObjectId, SuiSchema } from "sui-effect"
+import { Script } from "sui-effect/script"
+import { Tx } from "sui-effect/tx"
+
+const PKG = "0x…"
+
+const Escrow = SuiSchema.bcs(
+  bcs.struct("Escrow", { id: bcs.Address, amount: bcs.u64() }),
+  `${PKG}::escrow::Escrow`
+)
+
+export const program = Effect.gen(function*() {
+  const { signer, sui } = yield* Script
+  const id = yield* Config.schema(ObjectId, "ESCROW_ID")
+  const escrow = yield* sui.getObject(id, { schema: Escrow })
+  const executed = yield* Tx.run((tx) => {
+    tx.moveCall({
+      target: `${PKG}::escrow::claim`,
+      arguments: [tx.object(id), tx.pure.u64(escrow.content.amount)]
+    })
+  }, { signer })
+  const receipt = yield* executed.expectCreated(`${PKG}::escrow::Receipt`)
+  yield* Console.log(receipt.id)
+})
+
+if (import.meta.main) {
+  await Script.run(program)
+}
+```
+
+That is `examples/script-claim.ts`, which a test runs against the in-memory
+fake. Every failure it can produce is in the generator's inferred error type and
+has its own exit code, with no handling lines anywhere.
+
+## The two tiers
+
+`SuiCore` is the mechanical tier: a one-to-one Effect wrap of the SDK's
+`ClientWithCoreApi`, with every transport method present, the SDK's `Include`
+generics preserved, every call cancellable through the Effect's `AbortSignal`,
+every failure mapped into one tagged error by one mapper, a span per method, and
+retries on transient transport failures for reads only. Reach for it when you
+need a field or a method the tier above does not expose, and through
+`core.use(client => …)` when an upstream package wants the client object itself.
+
+`Sui` is the opinionated tier over it, and is what application and extension
+code reads through: fixed include sets, BCS content decoded through `Schema`
+with the object's Move type checked first, `Option` where absence is normal,
+batch reads chunked to 50 and checked for missing or duplicated ids — per-item
+`Result` from `getObjects`, first-error-wins from `getObjectsOrFail` — pagination
+as `Stream`, one lock per sender so two transactions from one address cannot
+pick the same gas coin, and the chain's own clock. A Move type with no type
+arguments matches every instantiation of it, wherever a type is compared, so one
+codec covers a generic Move type and the object keeps its own instantiated type. It carries the `SuiCore` it
+was built over as `sui.core`, which is why every `Tx.*` function needs only
+`Sui`.
+
+## The transaction lifecycle
+
+`Tx` is the lifecycle as functions — `build`, `sign`, `cosign`, `sponsored`,
+`submit`, `reconcile`, `run`, `reconcileAll` — each with a closed error union
+and `R = Sui`. `Tx.run` holds the sender lock from build through submit, builds
+(which always simulates before anything is signed — the SDK's resolver does it
+when there is anything to resolve, and `Tx.build` runs one explicitly when
+there is not, so a transaction that would abort never gets signed),
+signs, journals the signed bytes before the first execute, re-sends the
+identical bytes — never a rebuild — on a retryable transport failure or a
+timeout, waits for the execution to be visible to reads before it releases the
+lock, and if it still does not know what happened, reconciles: `Executed`,
+`ExecutionFailed`, `NotApplied { evidence }`, or `SubmissionUnknown` carrying
+the bytes. A `TransportError` never escapes once bytes may have been sent —
+from `submit`, and from `reconcile` and `reconcileAll` too. `Signer` is a
+value, not a service, so one process can hold two credentials; `SubmitConfig`
+and `Journal` are `Context.Reference`s with working defaults, so none of this
+needs wiring, and `sui-effect/journal` swaps the memory journal for a durable
+one over `KeyValueStore`.
+
+**`NotApplied` is hard to earn, on purpose.** Saying a transaction never applied
+tells the documented retry idiom to send the caller's intent again, so there are
+exactly two kinds of evidence and both are checked twice over. `"expired"`
+requires the epoch (or timestamp) bound to be observed as passed, then a
+`getTransaction` miss, then — after `SubmitConfig.reconcileRecheck` — both
+again; a single observation is `SubmissionUnknown`, and
+`SubmitConfig.expiryEvidence: "never"` turns the rule off for a deployment
+behind a mixed-node load balancer. `"inputConsumed"` requires a *different*
+transaction's **own effects** to report that it took a pinned object at exactly
+the version the bytes pinned: reconcile follows the live object's
+`previousTransaction` — which names the latest mutation, not the consumer of the
+version in question — to that transaction and reads `inputVersion` off its
+`changedObjects`. There is no "the object at version `v + 1`" rule, because Sui
+stamps every output with the transaction's **Lamport version**, `max(input
+versions) + 1`, so a coin read alongside a newer gas object jumps from version 4
+to 6,436,928 and version 5 never existed. Every pinned reference — owned inputs
+and gas coins alike — is tried before reconcile gives up.
+
+**In practice that means `SubmissionUnknown`, not `NotApplied`, for almost
+every stuck submission** whose PTB touched a shared object or an owned object
+older than the gas coin. Plan an operator path or a `reconcileAll` at startup;
+do not build a retry loop that expects `NotApplied { inputConsumed }`. Before
+any of this, reconcile compares the chain the bytes were built for with
+`sui.chainId` and refuses to reason across chains.
+
+**A sponsored `Tx.run` needs both signatures.** When the gas owner is not the
+sender, pass `sponsor`: `Tx.run(recipe, { signer, gasOwner, sponsor })`. Without
+it the run fails with `SigningError` before anything is built, because one
+signature on sponsored bytes is something a validator rejects outright. Two
+parties that cannot both sign in one process use `build`, `sign`, `cosign` and
+`submit` directly.
+
+When the recipe sets no expiration, `Tx.build` sets one: `ValidDuring` bounded
+to the current epoch and the next, carrying the chain identifier as a replay
+guard. Two epochs is what the validator rule allows for a transaction with no
+address-owned inputs — a PTB over shared objects, or any sponsored transaction —
+and the chain field is enforced, so bytes signed for testnet cannot land on
+mainnet. There is deliberately no wall-clock bound: every Sui network refuses a
+transaction that carries one today. `SubmitConfig.validFor` adds one for the day
+that changes.
+
+## Extensions
+
+A downstream SDK is an extension: an Effect service built on `Sui` and `Tx`
+whose layer requires `Sui` and nothing it could have built itself, whose
+contributions to a transaction are recipe fragments consumers compose into one
+programmable transaction, whose signers are parameters, and whose Promise face
+is derived — not hand-maintained — by `SuiExtension.fromService`, so a consumer
+with an SDK client writes `client.$extend(escrow(options))` and then plain
+`await`s, with the same tagged error instances on rejection.
+**[`docs/extensions.md`](docs/extensions.md) is the contract**, and
+`examples/extension-template/` is a copyable package that implements it — it
+ships inside the published package, so
+`node_modules/sui-effect/examples/extension-template/` is there to copy without
+a checkout.
+
+Four things an extension author should know before reading the guide. A layer
+may require `Sui | SuiCore` and must provide everything else itself, including
+another extension's service — the guide's "composing extensions" section is that
+pattern. A Promise face's **synchronous** members (recipe builders, a package
+id) are real only once the runtime exists, so either `await client.<name>.$ready()`
+once or register with `warm`; calling one before that fails with
+`ExtensionNotReady` rather than returning a Promise the type does not mention
+(`Effect` and `Stream` members work cold, as Promises and as async iterables).
+Every registration on one client **shares one `Sui`**, and therefore one
+sender-lock map, so two extensions never select gas for the same address at
+once; `$dispose()` releases that shared base only when the last registration on
+the client is disposed, and it is not final — the next call builds a fresh one.
+And `SuiGraphQL` is sui-effect's tag over the SDK's `SuiGraphQLClient` — one
+client shared by every extension that reads GraphQL; sui-effect wraps no GraphQL
+API of its own.
+
+## Errors
+
+Every failure is one of these, every one is a `Schema.TaggedError`, and there is
+no error inheritance to match on.
+
+| Tag | Fields | Means |
+|---|---|---|
+| `TransportError` | `method`, `retryable`, `status?`, `cause` | The request did not reach a usable answer. Inside `Tx.submit` a timed-out `executeTransaction` lands here with `retryable: true` and `status: "DEADLINE_EXCEEDED"`; anywhere else `Effect.timeout` produces Effect's own `TimeoutError`, which is not part of this taxonomy |
+| `ObjectNotFound` / `ObjectDeleted` / `ObjectUnavailable` | `objectId`, `version?` | The three `ObjectError.reason` values |
+| `TransactionNotFound` | `digest` | No transaction with that digest is known |
+| `NetworkMismatch` | `expected`, `actual` | The node is on another chain than the layer was built for |
+| `DecodeError` | `objectId?`, `expectedType?`, `issue` | BCS content or a schema boundary did not decode |
+| `SimulationFailed` | `reason`, `message` | Simulation reported an execution failure. No gas charged |
+| `ExecutionFailed` | `digest`, `reason`, `command?`, `effects` | Applied on chain and failed. Gas charged |
+| `SubmissionUnknown` | `digest`, `signed?`, `cause` | Bytes may have been sent; the outcome is unknown. Carries them, unless it came from reconciling a bare digest |
+| `NotApplied` | `digest`, `evidence: "expired" \| "inputConsumed"` | Provably never applied, and never will be |
+| `SigningError` | `cause` | A signer refused or failed |
+| `BuildError` | `message`, `cause` | The transaction could not be built |
+| `PolicyDenied` | `rule`, `message` | A preflight policy refused it before it was signed |
+| `JournalError` | `cause` | The journal could not be read or written. It escapes `Tx.submit` only from the write that happens **before** the first send; after the network has answered, a failed write is logged and the answer stands |
+| `UnexpectedEffects` | `digest`, `expected`, `found` | The effects did not contain what the caller expected. Outcome `applied` and exit 5: it comes from an `Executed`, so the transaction ran and gas was charged; only the receipt is missing |
+| `GraphQLUnavailable` | `method`, `reason` | The GraphQL endpoint an extension needs is not usable. What `SuiGraphQL.layerUnavailable` rejects every call with |
+| `ExtensionNotReady` | `extension`, `member` | A synchronous member of a Promise face was called before its runtime existed: `await client.<name>.$ready()`, or register with `warm` |
+
+`ExecutionReason` mirrors the SDK's `ExecutionError` variant for variant, with
+`MoveAbort.abortCode` as a `bigint` and clever-error constant names decoded.
+`SuiError.isRetryable`, `SuiError.outcome`, `SuiError.describe` and
+`SuiError.toJson` are the four helpers every repo otherwise hand-rolls;
+`outcome` puts every failure on the `"applied" | "not_applied" | "unknown"`
+axis, and an extension error may declare its own. An error that is neither a tag
+above nor declares an `outcome` is *unclassified*: `outcome` answers `"unknown"`,
+because an unrecognised tag is no evidence that nothing happened, and
+`Script.exitCode` exits 1 rather than 3, because it is no evidence that anything
+was sent either. Declare `outcome` on every error your extension defines.
+
+## Scripts
+
+`Script.layer` reads the environment:
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `SUI_NETWORK` | yes, no default | `mainnet`, `testnet`, `devnet`, `localnet` or your own |
+| `SUI_ALLOW_MAINNET` | only for mainnet | `1` or `true`; a script that means mainnet has to say so twice |
+| `SUI_RPC_URL` | no | The gRPC endpoint; defaulted per known network |
+| `SUI_PRIVATE_KEY` | `Script` only | A Bech32 `suiprivkey1…` key, read through `Config.redacted`. A key that does not decode fails with one fixed sentence and no cause: the Bech32 decoder quotes the whole input it rejected, so nothing derived from it is ever printed |
+
+`Script.layerReadOnly` provides `ScriptReadOnly`, which has no signer at all —
+a separate service key, so a script written to sign cannot silently build over a
+layer that cannot. `Script.run` installs SIGINT and SIGTERM handlers, interrupts
+the root fiber so finalizers run, writes one diagnostic line per failure to
+stderr, and exits. stdout carries only what the script itself printed: the
+logger is bound to stderr for the whole run, so an `Effect.log` anywhere in the
+call tree cannot corrupt the output. On every non-zero exit the unresolved
+entries of the journal the script ran with are printed too, so a script killed
+or failed mid-submit still leaves the digest and the bytes. A second SIGINT is
+ignored on purpose — the first one is what lets the finalizers that record those
+bytes finish.
+
+| Code | Means |
+|---|---|
+| 0 | success |
+| 1 | a defect, or an unclassified failure |
+| 2 | configuration: `ConfigError`, `NetworkMismatch`, `SchemaError`, the mainnet gate |
+| 3 | unknown outcome: reconcile before sending anything else |
+| 4 | nothing applied: safe to retry |
+| 5 | applied on chain: `ExecutionFailed` (gas charged) or `UnexpectedEffects` (it ran; the receipt is missing) |
+| 130 | interrupted, with nothing outstanding in the journal |
+
+A timeout or an interrupt asks the journal: with an unresolved submission in it
+the exit is 3, not 4 or 130, because an `Effect.timeout` wrapped around a
+submission interrupts it from the outside and the bytes may be on the wire.
+
+## Testing
+
+`sui-effect/testing` ships the in-memory `SuiCoreFake`, `layerTest(script)` (the
+real `Sui` over the fake, so tests exercise the production high tier),
+`layerExtensionTest(layer, script)` for an extension's own tests, and `SuiTest`
+for driving the fake's state and reading back what it was sent. No test in this
+repository touches the network, and neither should yours.
+
+## Versions
+
+| Package | Range | Tested against |
+|---|---|---|
+| `effect` | `4.0.0-rc.112` (exact) | `4.0.0-rc.112`, in CI |
+| `@mysten/sui` | `^2.28` (the first version whose BCS and gRPC round-trip `ValidDuring` and `Validity` expirations) | `2.29.0` and `2.30.0`, both in CI; `2.30.0` is the pinned devDependency |
+| `@mysten/bcs` | `^2.1.1` | `2.1.1` |
+| TypeScript | `5.9.x` to build | `5.9.3` |
+| Bun | `1.4.x` | `1.4.2` |
+
+The SDK row is a matrix, not a hope: CI builds, typechecks and runs the suite
+against `@mysten/sui` 2.29.0 and 2.30.0, which are the versions consumers pin
+today. The `effect` row is a matrix of one, and it is exact on purpose: rc.113
+renamed three `Config` constructors this package calls at four sites
+(`Script.ts`, `Signer.ts`, `SuiCore.ts`, `SuiGraphQL.ts`), so widening the range
+means supporting both spellings and proving the wider one in CI.
+
+**Consumers on TypeScript 7 (`tsgo`) are supported.** The shipped `.d.ts` needs
+nothing from the old compiler. The `prepare` script here
+(`effect-language-service patch`) is a library concern — it patches the checker
+this repository develops against — and should not be copied into a consumer or
+an extension package.
+
+`bun run check` is typecheck, build, tests and the extension template's own
+check.
+
+## For agents
+
+`LLMS.md` ships in the package: every public export with its signature and the
+error union its JSDoc states, plus every example verbatim. It is generated by
+`bun run llms` and a test fails when it is stale. `AGENTS.md` is the short list
+of invariants to read before the code, `DESIGN.md` the specification, and
+`docs/extensions.md` the extension contract.
+
+## License
+
+MIT

package/dist/domain/bcs.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The BCS bridge: a `@mysten/bcs` layout becomes an Effect `Schema.Codec` whose
+ * encoded side is the `content` bytes of an object.
+ *
+ * Decoding never reads the transport-varying `json` field of an object, only
+ * `content`, so the same program gives the same answer on gRPC, GraphQL and
+ * JSON-RPC.
+ *
+ * @since 0.1.0
+ */
+import type { BcsType } from "@mysten/bcs";
+import { Effect, Schema } from "effect";
+import { DecodeError } from "./errors.ts";
+import type { ObjectId } from "./schemas.ts";
+/**
+ * Turns a BCS layout into a `Schema.Codec<T, Uint8Array>` tagged with the Move
+ * type it belongs to.
+ *
+ * Decoding fails with a `SchemaError` (which `Sui` maps to `DecodeError`) when
+ * the bytes do not parse; encoding fails the same way when the value does not
+ * serialize. The expected type is normalized with `normalizeStructTag`, so
+ * `Coin<0x2::sui::SUI>` and its padded spelling are the same type, and a tag
+ * with no type arguments matches every instantiation of it (see
+ * {@link typeMatches}).
+ *
+ * **`expectedType` is optional.** A Move *return value* has no struct tag —
+ * `sui.view(recipe, bcs.Address())` reads a `vector<u8>` off a command result —
+ * and inventing one so the bridge has something to compare is worse than saying
+ * there is nothing to compare. A codec built without an expected type carries
+ * none, so nothing checks a tag before it parses: the re-serialize length check
+ * is still what rejects mis-shaped bytes. Give the type whenever the bytes come
+ * from an object, which is every `getObject(id, { schema })` read.
+ */
+export declare const bcs: <T extends Input, Input>(bcsType: BcsType<T, Input>, expectedType?: string) => Schema.Codec<T, Uint8Array>;
+/**
+ * The normalized Move type a codec built by {@link bcs} expects, or `undefined`
+ * for any other codec. `Sui.getObject` compares it with the object's own type
+ * tag before decoding. Composition preserves it: a codec piped into
+ * `Schema.decodeTo(DomainClass, ...)` still reports the type the bytes came
+ * from. Never fails.
+ */
+export declare const expectedTypeOf: <T, E>(schema: Schema.Codec<T, E>) => string | undefined;
+/**
+ * Whether an object's type tag satisfies an expected type.
+ *
+ * One rule, used everywhere a Move type is checked — the BCS bridge, the
+ * `expectedType` option of `Sui.getObject`, `getObjectOption` and `getObjects`,
+ * `SuiSchema.decode`, and the fake's owned-object filter:
+ *
+ * - **An expected tag with no type arguments names the generic itself**, so
+ *   `pkg::m::Composition` matches every instantiation:
+ *   `pkg::m::Composition<0x…::share::Share>` included. Only
+ *   `address::module::name` is compared, with the address normalized. This is
+ *   what a node does when a bare type is used as a filter, and it is what makes
+ *   a generic Move type usable with the bridge at all: a codec is written once
+ *   for `Composition<T>`, and the instantiation lives on the object.
+ * - **An expected tag that carries type arguments is compared in full**, after
+ *   `normalizeStructTag`, so `Coin<0x2::sui::SUI>` and its padded spelling are
+ *   the same type and `Coin<0x2::sui::SUI>` does not match `Coin<0x…::usdc::USDC>`.
+ *
+ * Anything that is not a struct tag — the literal `package`, a primitive — is
+ * compared as a normalized string. The object keeps its own instantiated type
+ * on `SuiObject.type`; this only decides whether the bytes may be decoded.
+ *
+ * **It never throws, which is the reason it is public** as
+ * `SuiSchema.matchesType`. A dynamic field's `name.type` is legally a primitive
+ * — `u64`, `bool`, `address`, `vector<u8>` — and the SDK's own
+ * `normalizeStructTag` throws on every one of them, so the obvious way to
+ * filter a `streamDynamicFields` by key type dies on the first `u64` key.
+ * Comparing tags with this is safe on any string at all.
+ *
+ * Never fails.
+ */
+export declare const typeMatches: (expected: string, actual: string) => boolean;
+/**
+ * Decodes BCS `content` bytes with a codec, turning any schema failure into a
+ * `DecodeError` that names the object and the type that was expected.
+ *
+ * This is what `Sui.getObject(id, { schema })` does after it has checked the
+ * object's type tag, exposed as `SuiSchema.decode` for the places that already
+ * have bytes: a dynamic field's value, an event payload, a `Stream` of
+ * envelopes an extension decodes itself. Without it every caller reinvents the
+ * same `Schema.decodeUnknownEffect(...).pipe(Effect.mapError(...))`, and the
+ * `DecodeError` it produces is worse than this one.
+ *
+ * `expectedType` defaults to the Move type the codec was built with, so passing
+ * it is only needed for a codec that carries none, or to override the recorded
+ * one. `actualType` is the Move type the bytes actually came from, when the
+ * caller knows it — a dynamic field's `name.type`, a stream envelope's `type`:
+ * give it and the same tag check `getObject` does runs here, under the
+ * {@link typeMatches} rule, before a byte is parsed. `objectId` is recorded on
+ * the error so an operator knows which object did not decode.
+ *
+ * Fails with: `DecodeError`.
+ */
+export declare const decodeContent: <T>(schema: Schema.Codec<T, Uint8Array>, content: Uint8Array, context?: {
+    readonly objectId?: ObjectId;
+    readonly expectedType?: string;
+    readonly actualType?: string;
+}) => Effect.Effect<T, DecodeError>;
+//# sourceMappingURL=bcs.d.ts.map

package/dist/domain/bcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bcs.d.ts","sourceRoot":"","sources":["../../src/domain/bcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE1C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAgD,MAAM,QAAQ,CAAA;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAY5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,KAAK,EAAE,KAAK,EACxC,SAAS,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,EAC1B,eAAe,MAAM,KACpB,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAgD5B,CAAA;AAuBD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,GAAG,SAC/C,CAAA;AAU5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,QAAQ,MAAM,KAAG,OAU9D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAC7B,QAAQ,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,EACnC,SAAS,UAAU,EACnB,UAAU;IACR,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,KACA,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,CA0B9B,CAAA"}

package/dist/domain/bcs.js

@@ -0,0 +1,183 @@
+import { normalizeStructTag, parseStructTag } from "@mysten/sui/utils";
+import { Effect, Schema, SchemaAST, SchemaIssue, SchemaTransformation } from "effect";
+import { DecodeError } from "./errors.js";
+const SUI_TYPE_ANNOTATION = "sui-effect/suiType";
+const normalizeSafe = (value) => {
+    try {
+        return normalizeStructTag(value);
+    }
+    catch {
+        return value;
+    }
+};
+/**
+ * Turns a BCS layout into a `Schema.Codec<T, Uint8Array>` tagged with the Move
+ * type it belongs to.
+ *
+ * Decoding fails with a `SchemaError` (which `Sui` maps to `DecodeError`) when
+ * the bytes do not parse; encoding fails the same way when the value does not
+ * serialize. The expected type is normalized with `normalizeStructTag`, so
+ * `Coin<0x2::sui::SUI>` and its padded spelling are the same type, and a tag
+ * with no type arguments matches every instantiation of it (see
+ * {@link typeMatches}).
+ *
+ * **`expectedType` is optional.** A Move *return value* has no struct tag —
+ * `sui.view(recipe, bcs.Address())` reads a `vector<u8>` off a command result —
+ * and inventing one so the bridge has something to compare is worse than saying
+ * there is nothing to compare. A codec built without an expected type carries
+ * none, so nothing checks a tag before it parses: the re-serialize length check
+ * is still what rejects mis-shaped bytes. Give the type whenever the bytes come
+ * from an object, which is every `getObject(id, { schema })` read.
+ */
+export const bcs = (bcsType, expectedType) => {
+    const normalized = expectedType === undefined ? undefined : normalizeSafe(expectedType);
+    // What the failure messages call the layout when it has no Move type of its
+    // own: `bcsType.name` is what `@mysten/bcs` named it (`"Escrow"`, `"vector"`).
+    const label = normalized ?? bcsType.name;
+    // A BCS layout carries no runtime type to test a decoded value against: the
+    // parse below is the validation, so the target schema accepts whatever the
+    // layout produced.
+    const target = Schema.declare((_u) => true);
+    return Schema.Uint8Array.pipe(Schema.decodeTo(target, SchemaTransformation.transformOrFail({
+        decode: (bytes, options) => Effect.try({
+            try: () => {
+                const parsed = bcsType.parse(bytes);
+                // `parse` stops at the end of the layout and ignores whatever
+                // follows, which would silently accept an `objectBcs` envelope
+                // where `content` was expected. Re-serializing costs one pass and
+                // catches both trailing and mis-shaped bytes.
+                if (bcsType.serialize(parsed).toBytes().length !== bytes.length) {
+                    throw new Error(`expected ${bytes.length} bytes of ${label}`);
+                }
+                return parsed;
+            },
+            catch: (cause) => new SchemaIssue.InvalidValue({ message: `Could not parse ${label} from BCS content: ${String(cause)}` }, bytes, options)
+        }),
+        encode: (value, options) => Effect.try({
+            try: () => bcsType.serialize(value).toBytes(),
+            catch: (cause) => new SchemaIssue.InvalidValue({ message: `Could not serialize ${label} to BCS: ${String(cause)}` }, value, options)
+        })
+    }))).annotate(normalized === undefined ? {} : { [SUI_TYPE_ANNOTATION]: normalized });
+};
+const MAX_ENCODING_DEPTH = 32;
+/**
+ * Walks the encoding chain looking for the annotation {@link bcs} leaves
+ * behind. `SuiSchema.bcs(...).pipe(Schema.decodeTo(DomainClass, ...))` puts a
+ * new node on top and keeps the annotated node as the source side of the
+ * transformation, so the tag survives composition.
+ */
+const findSuiType = (ast, depth) => {
+    const annotation = ast.annotations?.[SUI_TYPE_ANNOTATION];
+    if (typeof annotation === "string")
+        return annotation;
+    if (depth >= MAX_ENCODING_DEPTH)
+        return undefined;
+    const encoding = ast.encoding;
+    if (encoding === undefined)
+        return undefined;
+    for (const link of encoding) {
+        const found = findSuiType(link.to, depth + 1);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+};
+/**
+ * The normalized Move type a codec built by {@link bcs} expects, or `undefined`
+ * for any other codec. `Sui.getObject` compares it with the object's own type
+ * tag before decoding. Composition preserves it: a codec piped into
+ * `Schema.decodeTo(DomainClass, ...)` still reports the type the bytes came
+ * from. Never fails.
+ */
+export const expectedTypeOf = (schema) => findSuiType(schema.ast, 0);
+const parseSafe = (value) => {
+    try {
+        return parseStructTag(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Whether an object's type tag satisfies an expected type.
+ *
+ * One rule, used everywhere a Move type is checked — the BCS bridge, the
+ * `expectedType` option of `Sui.getObject`, `getObjectOption` and `getObjects`,
+ * `SuiSchema.decode`, and the fake's owned-object filter:
+ *
+ * - **An expected tag with no type arguments names the generic itself**, so
+ *   `pkg::m::Composition` matches every instantiation:
+ *   `pkg::m::Composition<0x…::share::Share>` included. Only
+ *   `address::module::name` is compared, with the address normalized. This is
+ *   what a node does when a bare type is used as a filter, and it is what makes
+ *   a generic Move type usable with the bridge at all: a codec is written once
+ *   for `Composition<T>`, and the instantiation lives on the object.
+ * - **An expected tag that carries type arguments is compared in full**, after
+ *   `normalizeStructTag`, so `Coin<0x2::sui::SUI>` and its padded spelling are
+ *   the same type and `Coin<0x2::sui::SUI>` does not match `Coin<0x…::usdc::USDC>`.
+ *
+ * Anything that is not a struct tag — the literal `package`, a primitive — is
+ * compared as a normalized string. The object keeps its own instantiated type
+ * on `SuiObject.type`; this only decides whether the bytes may be decoded.
+ *
+ * **It never throws, which is the reason it is public** as
+ * `SuiSchema.matchesType`. A dynamic field's `name.type` is legally a primitive
+ * — `u64`, `bool`, `address`, `vector<u8>` — and the SDK's own
+ * `normalizeStructTag` throws on every one of them, so the obvious way to
+ * filter a `streamDynamicFields` by key type dies on the first `u64` key.
+ * Comparing tags with this is safe on any string at all.
+ *
+ * Never fails.
+ */
+export const typeMatches = (expected, actual) => {
+    const expectedTag = parseSafe(expected);
+    if (expectedTag === undefined || expectedTag.typeParams.length > 0) {
+        return normalizeSafe(expected) === normalizeSafe(actual);
+    }
+    const actualTag = parseSafe(actual);
+    if (actualTag === undefined)
+        return normalizeSafe(expected) === normalizeSafe(actual);
+    return expectedTag.address === actualTag.address &&
+        expectedTag.module === actualTag.module &&
+        expectedTag.name === actualTag.name;
+};
+/**
+ * Decodes BCS `content` bytes with a codec, turning any schema failure into a
+ * `DecodeError` that names the object and the type that was expected.
+ *
+ * This is what `Sui.getObject(id, { schema })` does after it has checked the
+ * object's type tag, exposed as `SuiSchema.decode` for the places that already
+ * have bytes: a dynamic field's value, an event payload, a `Stream` of
+ * envelopes an extension decodes itself. Without it every caller reinvents the
+ * same `Schema.decodeUnknownEffect(...).pipe(Effect.mapError(...))`, and the
+ * `DecodeError` it produces is worse than this one.
+ *
+ * `expectedType` defaults to the Move type the codec was built with, so passing
+ * it is only needed for a codec that carries none, or to override the recorded
+ * one. `actualType` is the Move type the bytes actually came from, when the
+ * caller knows it — a dynamic field's `name.type`, a stream envelope's `type`:
+ * give it and the same tag check `getObject` does runs here, under the
+ * {@link typeMatches} rule, before a byte is parsed. `objectId` is recorded on
+ * the error so an operator knows which object did not decode.
+ *
+ * Fails with: `DecodeError`.
+ */
+export const decodeContent = (schema, content, context) => {
+    const expected = context?.expectedType ?? expectedTypeOf(schema);
+    const withExpected = expected === undefined ? {} : { expectedType: expected };
+    const withObject = context?.objectId === undefined ? {} : { objectId: context.objectId };
+    const actual = context?.actualType;
+    if (expected !== undefined && actual !== undefined && !typeMatches(expected, actual)) {
+        return Effect.fail(new DecodeError({
+            ...withObject,
+            ...withExpected,
+            issue: `${context?.objectId === undefined ? "the bytes have" : `object ${context.objectId} has`} type ${actual}`
+        }));
+    }
+    return Schema.decodeUnknownEffect(schema)(content).pipe(Effect.mapError((error) => new DecodeError({
+        ...withObject,
+        ...withExpected,
+        issue: error.message
+    })));
+};
+//# sourceMappingURL=bcs.js.map

package/dist/domain/bcs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bcs.js","sourceRoot":"","sources":["../../src/domain/bcs.ts"],"names":[],"mappings":"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"}