feat(facade): unified Tx3ClientBuilder for §3.3/§3.6 parity#13
Merged
Conversation
….6 parity
Adds Tx3ClientBuilder with the two seeding entry points (Protocol.client()
for the dynamic flow and Tx3ClientBuilder.from_parts(...) for the codegen
flow), the mandatory trp/trp_endpoint setters, optional with_profile /
with_party / with_parties / with_party_unchecked / with_header /
with_env_value, and a single build() terminal that raises
MissingTrpEndpointError, UnknownProfileError, or UnknownPartyError.
New BuilderError class family under Tx3Error makes the builder errors
discriminable. Removes with_profile from the built Tx3Client (profile
selection is builder-only per §3.6); Tx3Client.tx(name) raises UnknownTxError
at the call site instead of deferring to resolve().
TxBuilder is now source-agnostic: holds the TIR envelope, env, parties, and
args directly so the dynamic and codegen flows drive an identical resolve()
path.
Codegen template wraps Tx3ClientBuilder.from_parts(...) instead of
re-implementing client state. Generated Client adds only the typed per-tx
Params dataclasses, per-tx methods, per-party setters (routing through
with_party_unchecked), embedded TIR / SdkProfile constants, and (when
profiles are declared) a typed Profile str-Enum.
Builder exposes an internal _trp_client(client) escape hatch for tests to
inject mock TRP clients without going through ClientOptions — not part of
the public API.
Top-level re-exports add Tx3ClientBuilder, Profile, BuilderError,
MissingTrpEndpointError, ClientOptions.
Existing tests (test_add_witness, test_errors) migrated to the builder API;
test_facade rewritten with 17 new tests covering the builder contract.
46/46 unit tests pass.
Spec: sdks/sdk-spec/api-surface/facade.md §3.3, §3.4, §3.6;
sdks/sdk-spec/codegen/generated-surface.md §C.3a–d.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Updates the quick-start example to use protocol.client()...build() instead of Tx3Client(protocol, trp). Expands the concepts table with Tx3ClientBuilder, Profile, and BuilderError. Adds a from_parts walkthrough under "Skipping the runtime .tii (codegen flow)". sdk/README.md is a symlink to the root README, so both stay in sync. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The e2e harness still constructed Tx3Client directly via the removed `Tx3Client(protocol, trp).with_profile(...)` shape. Routes through `protocol.client().trp_endpoint(...).with_profile(...).with_header(...).build()` instead; `dmtr-api-key` is now attached via the builder's `with_header` setter rather than a separately-constructed TrpClient (the builder now owns TRP client construction and lifetime). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 24, 2026
scarmuega
added a commit
that referenced
this pull request
May 24, 2026
Aligns the python-sdk package version with the fleet's 0.12 release train (rust-sdk workspace is already at 0.12.0). The unified Tx3ClientBuilder landed in #13 and is a breaking change — per sdks/sdk-spec/release-policy.md any change to MAJOR or MINOR must be coordinated across all SDKs. Bumps both pyproject.toml `version` and the runtime `__version__` constant in tx3_sdk/__init__.py. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ports the unified-builder pattern from
rust-sdkinto python-sdk so the §3.3/§3.6 facade rows ofsdks/parity-matrix.mdflip ❌→✅.Tx3ClientBuilder(withProtocol.client()+from_parts(...)seeders,trp/trp_endpoint/with_header/with_profile/with_party/with_parties/with_party_unchecked/with_env_valuesetters, singlebuild()terminal).Tx3Clientnow owns the deconstructed protocol parts;with_profileis builder-only (removed from the built client per §3.6);tx(name)raisesUnknownTxErrorat call site.TxBuilderis source-agnostic — both dynamic and codegen flows drive the sameresolve()path.BuilderErrorfamily +MissingTrpEndpointError;UnknownPartyErrorre-parented fromResolutionError→BuilderError(both still extendTx3Error)..trix/client-lib/__init__.py.hbs) wrapsTx3ClientBuilder.from_parts(...); per-party setters route throughwith_party_unchecked; profiles emitted as individualSdkProfileconsts with a typedProfilestr-Enum.Tx3ClientBuilder,Profile,BuilderError,MissingTrpEndpointError,ClientOptions.Spec references:
sdks/sdk-spec/api-surface/facade.md§3.3, §3.4, §3.6;sdks/sdk-spec/codegen/generated-surface.md§C.3a–d.Breaking changes
Tx3Client(protocol, trp, ...)direct construction is gone — useprotocol.client()...build()instead.Tx3Client.with_profile(name)removed — callwith_profileon the builder.tx(name)raisesUnknownTxErrorat call site instead of deferring toresolve().UnknownPartyError's parent class changed (ResolutionError→BuilderError).Notes
Tx3ClientBuilder._trp_client(client)is an internal test escape hatch (not part of the public API) — lets unit tests inject a mock TRP client without going throughClientOptions. Documented inline.test_add_witness.pyandtest_errors.pyto the new builder API.test_facade.pyrewritten with 17 builder-focused tests.Test plan
py_compilecleanpytest tests/ --ignore=tests/e2e— 46/46 passtx3c codegenagainstsdk/tests/fixtures/transfer.tiirenders cleanly and the rendered__init__.pysyntax-compilescodegen-check.shwill fail in CI until this lands on PyPI — the script installstx3-sdkfrom PyPI, which is still v0.11.0 withoutTx3ClientBuilder. Expected for a template flip.🤖 Generated with Claude Code