From cb6addd157f588e1a224f659dce204ac8056fd4b Mon Sep 17 00:00:00 2001 From: jorbuedo Date: Sun, 11 Oct 2026 16:26:43 +0200 Subject: [PATCH] feat: wallet-side capabilities, byte-exactness, and ten packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A wallet needs three things this SDK did not have: the bytes a transaction arrived as, so a signature covers what was displayed; reads beyond the ten a transaction builder makes; and the standards layers around a transaction that every wallet otherwise reimplements. In `packages/evolution`: - **Byte-exactness.** A decoded body, witness set, datum and redeemer replay the bytes they arrived as, scoped to what the schema cannot carry: the `#6.258` input-set tag and integer header widths. `mode: "canonical"` still outranks the record. A body key the schema does not model is refused at decode rather than dropped, which changed the transaction id silently. - **The hex boundary is branded and validated.** Sixteen modules export a `Hex` schema built the way `PaymentAddress` already is, so a transaction hash and a datum hash stop being interchangeable once they leave the typed domain. - **The provider port grows a history tier**, every member optional: what has happened at these addresses, which addresses a stake account has used, the bytes of a transaction, how deep it is, and the batches `getTxsAt` can serve. - **Fees, coin selection, CDDL conformance, COSE, native scripts**: exact Conway fee arithmetic, random-improve as CSL computes it, pool owners as a tagged set, a structurally-keyed COSE header map, and `NativeScripts.fromJSON`. - **Defects fixed**: `type-check` checked an empty program; `getHeader` never found a label that was present; `toJSON` truncated a uint64 slot; a Koios credential went on the wire as `{"0":170,…}`; `writeConstr` refused every constructor tag under a non-minimal option set; `getByUnit` answered `0n` for an asset `fromUnit` had just built. Ten packages: `review` (span-preserving review before signing), `plan` (wallet-side planning), `cips`, `cip30`, `cip113`, `cip139`, `canonical`, `dijkstra`, `hardware-cardano`, `backup-keys`. ⚠️ One breaking change: `TransactionOutput` was a second, parallel output model that the builders and `TransactionBody` rejected. It now re-exports `TxOut`, which is the model they use. Evidence: 2,731 tests passed / 84 skipped across 11 packages; `turbo lint` 14/14; `turbo type-check` 15/15; `changeset status` clean. --- .changeset/assemble-from-encoded-parts.md | 15 + .changeset/asset-unit-two-spellings.md | 9 + .changeset/backup-keys-encrypted-export.md | 13 + .../bip39-passphrase-bytes-and-paths.md | 13 + .changeset/canonical-jcs-and-cip116.md | 11 + .changeset/cbor-builder-and-byte-helpers.md | 11 + .../cddl-conformance-and-reachable-codecs.md | 14 + .changeset/cip113-programmable-tokens.md | 13 + .changeset/cip139-query-layer.md | 11 + .../cip21-multiasset-canonical-order.md | 11 + .changeset/cip30-read-surface.md | 11 + .changeset/cips-companions.md | 11 + .changeset/coin-selection-random-improve.md | 13 + .changeset/cose-header-map-and-sign-data.md | 14 + .changeset/dijkstra-prefork-fields.md | 11 + .changeset/exact-conway-fee-math.md | 11 + .changeset/hardware-cardano-sign-requests.md | 11 + .changeset/hex-boundary-brands.md | 19 + .../koios-chain-parameters-over-the-wire.md | 13 + ...koios-credential-utxos-hex-and-batching.md | 9 + .changeset/koios-history-tier-behaviours.md | 13 + .changeset/koios-multi-id-bodies.md | 14 + .changeset/koios-request-timeout-option.md | 19 + .changeset/koios-token-source.md | 11 + .changeset/native-scripts-json.md | 11 + .../no-credential-on-a-cleartext-wire.md | 11 + .changeset/plan-engine.md | 11 + .../plan-fee-math-one-implementation.md | 13 + .changeset/plutus-data-splicing-and-schema.md | 11 + .changeset/provider-gettip-optional.md | 9 + .changeset/provider-history-tier.md | 11 + .changeset/provider-tx-confirmations.md | 9 + .changeset/request-report-refusal-body.md | 9 + .changeset/review-before-sign.md | 14 + .changeset/set-tag-and-unknown-body-keys.md | 11 + .changeset/tag-102-definite-wrapper.md | 18 + .../transfer-refuses-to-drop-a-datum.md | 13 + .changeset/txs-at-address-batches.md | 11 + docs/content/docs/modules/Address.mdx | 66 +- docs/content/docs/modules/AddressEras.mdx | 75 +- docs/content/docs/modules/AddressTag.mdx | 84 +- docs/content/docs/modules/Anchor.mdx | 1 + docs/content/docs/modules/AssetName.mdx | 53 +- docs/content/docs/modules/Assets.mdx | 1 + docs/content/docs/modules/AuxiliaryData.mdx | 32 +- .../docs/modules/AuxiliaryDataHash.mdx | 75 +- docs/content/docs/modules/BaseAddress.mdx | 1 + docs/content/docs/modules/Bech32.mdx | 1 + docs/content/docs/modules/BigInt.mdx | 1 + docs/content/docs/modules/Bip32PrivateKey.mdx | 93 +- docs/content/docs/modules/Bip32PublicKey.mdx | 80 +- docs/content/docs/modules/Block.mdx | 1 + docs/content/docs/modules/BlockBodyHash.mdx | 1 + docs/content/docs/modules/BlockHeaderHash.mdx | 1 + .../content/docs/modules/BootstrapWitness.mdx | 1 + docs/content/docs/modules/BoundedBytes.mdx | 1 + docs/content/docs/modules/ByronAddress.mdx | 1 + docs/content/docs/modules/Bytes.mdx | 1 + docs/content/docs/modules/Bytes128.mdx | 1 + docs/content/docs/modules/Bytes16.mdx | 1 + docs/content/docs/modules/Bytes29.mdx | 1 + docs/content/docs/modules/Bytes32.mdx | 1 + docs/content/docs/modules/Bytes4.mdx | 1 + docs/content/docs/modules/Bytes448.mdx | 1 + docs/content/docs/modules/Bytes57.mdx | 1 + docs/content/docs/modules/Bytes64.mdx | 1 + docs/content/docs/modules/Bytes80.mdx | 1 + docs/content/docs/modules/Bytes96.mdx | 1 + docs/content/docs/modules/CBOR.mdx | 389 +- docs/content/docs/modules/CBORBuilder.mdx | 534 + docs/content/docs/modules/Certificate.mdx | 55 +- docs/content/docs/modules/Codec.mdx | 3 +- docs/content/docs/modules/Coin.mdx | 3 +- .../docs/modules/CommitteeColdCredential.mdx | 3 +- .../docs/modules/CommitteeHotCredential.mdx | 3 +- docs/content/docs/modules/Constitution.mdx | 12 +- docs/content/docs/modules/CostModel.mdx | 3 +- docs/content/docs/modules/Credential.mdx | 30 +- docs/content/docs/modules/DRep.mdx | 3 +- docs/content/docs/modules/DRepCredential.mdx | 3 +- docs/content/docs/modules/Data.mdx | 184 +- docs/content/docs/modules/DataJson.mdx | 3 +- docs/content/docs/modules/DatumHash.mdx | 69 +- docs/content/docs/modules/DatumOption.mdx | 53 +- docs/content/docs/modules/DnsName.mdx | 3 +- .../content/docs/modules/Ed25519Signature.mdx | 83 +- docs/content/docs/modules/EffectRuntime.mdx | 3 +- .../docs/modules/EnterpriseAddress.mdx | 3 +- docs/content/docs/modules/EpochNo.mdx | 3 +- docs/content/docs/modules/FeeValidation.mdx | 3 +- docs/content/docs/modules/Fees.mdx | 96 + .../content/docs/modules/GovernanceAction.mdx | 30 +- docs/content/docs/modules/Hash28.mdx | 3 +- docs/content/docs/modules/Header.mdx | 3 +- docs/content/docs/modules/HeaderBody.mdx | 3 +- docs/content/docs/modules/IPv4.mdx | 3 +- docs/content/docs/modules/IPv6.mdx | 3 +- docs/content/docs/modules/InlineDatum.mdx | 42 +- docs/content/docs/modules/KESVkey.mdx | 3 +- docs/content/docs/modules/KesSignature.mdx | 3 +- docs/content/docs/modules/KeyHash.mdx | 99 +- docs/content/docs/modules/Label.mdx | 3 +- docs/content/docs/modules/Language.mdx | 3 +- docs/content/docs/modules/Metadata.mdx | 3 +- docs/content/docs/modules/MinAda.mdx | 77 + docs/content/docs/modules/Mint.mdx | 3 +- docs/content/docs/modules/MultiAsset.mdx | 3 +- docs/content/docs/modules/MultiHostName.mdx | 3 +- .../content/docs/modules/NativeScriptJSON.mdx | 3 +- docs/content/docs/modules/NativeScripts.mdx | 28 +- docs/content/docs/modules/Natural.mdx | 3 +- docs/content/docs/modules/Network.mdx | 3 +- docs/content/docs/modules/NetworkId.mdx | 3 +- docs/content/docs/modules/NonZeroInt64.mdx | 3 +- .../docs/modules/NonnegativeInterval.mdx | 54 +- docs/content/docs/modules/Numeric.mdx | 3 +- docs/content/docs/modules/OperationalCert.mdx | 3 +- docs/content/docs/modules/OriginalBytes.mdx | 57 + docs/content/docs/modules/PaymentAddress.mdx | 3 +- docs/content/docs/modules/PlutusV1.mdx | 3 +- docs/content/docs/modules/PlutusV2.mdx | 3 +- docs/content/docs/modules/PlutusV3.mdx | 3 +- docs/content/docs/modules/Pointer.mdx | 3 +- docs/content/docs/modules/PointerAddress.mdx | 5 +- docs/content/docs/modules/PolicyId.mdx | 70 +- docs/content/docs/modules/PoolKeyHash.mdx | 3 +- docs/content/docs/modules/PoolMetadata.mdx | 3 +- docs/content/docs/modules/PoolParams.mdx | 101 +- docs/content/docs/modules/Port.mdx | 3 +- docs/content/docs/modules/PositiveCoin.mdx | 3 +- docs/content/docs/modules/PrivateKey.mdx | 7 +- .../docs/modules/ProposalProcedure.mdx | 13 +- .../docs/modules/ProposalProcedures.mdx | 185 +- .../docs/modules/ProtocolParamUpdate.mdx | 3 +- docs/content/docs/modules/ProtocolVersion.mdx | 3 +- docs/content/docs/modules/Redeemer.mdx | 59 +- docs/content/docs/modules/Redeemers.mdx | 209 +- docs/content/docs/modules/Relay.mdx | 3 +- docs/content/docs/modules/RewardAccount.mdx | 3 +- docs/content/docs/modules/RewardAddress.mdx | 3 +- docs/content/docs/modules/Script.mdx | 32 +- docs/content/docs/modules/ScriptDataHash.mdx | 69 +- docs/content/docs/modules/ScriptHash.mdx | 47 +- docs/content/docs/modules/ScriptRef.mdx | 5 +- docs/content/docs/modules/SingleHostAddr.mdx | 3 +- docs/content/docs/modules/SingleHostName.mdx | 3 +- docs/content/docs/modules/Slot.mdx | 3 +- docs/content/docs/modules/SlotConfig.mdx | 3 +- docs/content/docs/modules/StakeReference.mdx | 3 +- docs/content/docs/modules/TSchema.mdx | 535 - docs/content/docs/modules/Text.mdx | 3 +- docs/content/docs/modules/Text128.mdx | 3 +- docs/content/docs/modules/Time.mdx | 3 +- docs/content/docs/modules/Transaction.mdx | 140 +- docs/content/docs/modules/TransactionBody.mdx | 77 +- docs/content/docs/modules/TransactionHash.mdx | 57 +- .../content/docs/modules/TransactionIndex.mdx | 3 +- .../content/docs/modules/TransactionInput.mdx | 3 +- .../docs/modules/TransactionMetadatum.mdx | 31 +- .../modules/TransactionMetadatumLabels.mdx | 3 +- .../docs/modules/TransactionOutput.mdx | 529 +- .../docs/modules/TransactionWitnessSet.mdx | 143 +- docs/content/docs/modules/TxOut.mdx | 55 +- docs/content/docs/modules/UPLC.mdx | 21 +- docs/content/docs/modules/UTxO.mdx | 3 +- docs/content/docs/modules/Unit.mdx | 3 +- docs/content/docs/modules/UnitInterval.mdx | 65 +- docs/content/docs/modules/UnixTime.mdx | 3 +- docs/content/docs/modules/Url.mdx | 3 +- docs/content/docs/modules/VKey.mdx | 63 +- docs/content/docs/modules/Value.mdx | 32 +- .../content/docs/modules/VotingProcedures.mdx | 81 +- docs/content/docs/modules/VrfCert.mdx | 3 +- docs/content/docs/modules/VrfKeyHash.mdx | 3 +- docs/content/docs/modules/VrfVkey.mdx | 3 +- docs/content/docs/modules/Withdrawals.mdx | 3 +- docs/content/docs/modules/_meta.json | 5 +- .../docs/modules/blueprint/Codegen.mdx | 1 + .../docs/modules/blueprint/CodegenConfig.mdx | 1 + docs/content/docs/modules/blueprint/Types.mdx | 1 + docs/content/docs/modules/cose/Header.mdx | 235 +- docs/content/docs/modules/cose/Key.mdx | 26 +- docs/content/docs/modules/cose/Label.mdx | 3 +- docs/content/docs/modules/cose/Sign.mdx | 3 +- docs/content/docs/modules/cose/Sign1.mdx | 3 +- docs/content/docs/modules/cose/SignData.mdx | 117 +- docs/content/docs/modules/cose/Utils.mdx | 3 +- docs/content/docs/modules/plutus/Address.mdx | 21 +- .../docs/modules/plutus/CIP68Metadata.mdx | 3 +- .../docs/modules/plutus/Credential.mdx | 3 +- .../docs/modules/plutus/OutputReference.mdx | 3 +- docs/content/docs/modules/plutus/Value.mdx | 3 +- .../content/docs/modules/sdk/EvalRedeemer.mdx | 3 +- docs/content/docs/modules/sdk/Type.mdx | 3 +- .../modules/sdk/builders/CoinSelection.mdx | 46 +- .../sdk/builders/EvaluationStateManager.mdx | 3 +- .../modules/sdk/builders/RedeemerBuilder.mdx | 65 +- .../docs/modules/sdk/builders/SignBuilder.mdx | 3 +- .../modules/sdk/builders/SignBuilderImpl.mdx | 3 +- .../modules/sdk/builders/SubmitBuilder.mdx | 3 +- .../sdk/builders/SubmitBuilderImpl.mdx | 3 +- .../sdk/builders/TransactionBuilder.mdx | 144 +- .../sdk/builders/TransactionResult.mdx | 3 +- .../docs/modules/sdk/builders/Unfrack.mdx | 3 +- .../sdk/builders/operations/AddSigner.mdx | 3 +- .../sdk/builders/operations/Attach.mdx | 3 +- .../builders/operations/AttachMetadata.mdx | 3 +- .../sdk/builders/operations/Collect.mdx | 3 +- .../sdk/builders/operations/Governance.mdx | 7 +- .../modules/sdk/builders/operations/Mint.mdx | 3 +- .../sdk/builders/operations/Operations.mdx | 18 +- .../modules/sdk/builders/operations/Pay.mdx | 20 +- .../modules/sdk/builders/operations/Pool.mdx | 5 +- .../sdk/builders/operations/Propose.mdx | 8 +- .../sdk/builders/operations/ReadFrom.mdx | 3 +- .../sdk/builders/operations/SendAll.mdx | 3 +- .../modules/sdk/builders/operations/Stake.mdx | 9 +- .../sdk/builders/operations/Validity.mdx | 3 +- .../modules/sdk/builders/operations/Vote.mdx | 3 +- .../modules/sdk/builders/phases/Balance.mdx | 3 +- .../sdk/builders/phases/ChangeCreation.mdx | 3 +- .../sdk/builders/phases/Collateral.mdx | 3 +- .../sdk/builders/phases/Evaluation.mdx | 5 +- .../modules/sdk/builders/phases/Fallback.mdx | 3 +- .../sdk/builders/phases/FeeCalculation.mdx | 3 +- .../modules/sdk/builders/phases/Selection.mdx | 3 +- .../content/docs/modules/sdk/client/Chain.mdx | 3 +- .../docs/modules/sdk/client/Client.mdx | 22 +- .../docs/modules/sdk/provider/Blockfrost.mdx | 14 +- .../docs/modules/sdk/provider/Koios.mdx | 269 +- .../docs/modules/sdk/provider/Kupmios.mdx | 14 +- .../docs/modules/sdk/provider/Maestro.mdx | 14 +- .../docs/modules/sdk/provider/Mock.mdx | 392 + .../docs/modules/sdk/provider/Provider.mdx | 712 +- .../modules/sdk/provider/RequestBudget.mdx | 304 + .../docs/modules/sdk/wallet/Derivation.mdx | 3 +- .../docs/modules/sdk/wallet/Wallet.mdx | 77 +- packages/backup-keys/README.md | 38 + packages/backup-keys/package.json | 81 + packages/backup-keys/src/EncryptedExport.ts | 202 + packages/backup-keys/src/index.ts | 7 + .../backup-keys/test/EncryptedExport.test.ts | 166 + packages/backup-keys/tsconfig.build.json | 10 + packages/backup-keys/tsconfig.json | 6 + packages/backup-keys/tsconfig.src.json | 11 + packages/backup-keys/tsconfig.test.json | 32 + packages/backup-keys/vitest.config.ts | 9 + packages/canonical/README.md | 58 + packages/canonical/package.json | 78 + packages/canonical/src/Cip116.ts | 180 + packages/canonical/src/Jcs.ts | 167 + packages/canonical/src/index.ts | 7 + packages/canonical/test/Canonical.test.ts | 177 + packages/canonical/tsconfig.build.json | 10 + packages/canonical/tsconfig.json | 6 + packages/canonical/tsconfig.src.json | 11 + packages/canonical/tsconfig.test.json | 32 + packages/canonical/vitest.config.ts | 9 + packages/cip113/README.md | 85 + packages/cip113/harness/blueprint.ts | 165 + packages/cip113/harness/budgets.ts | 430 + packages/cip113/harness/cost-model.ts | 101 + packages/cip113/package.json | 80 + packages/cip113/src/Budgets.ts | 318 + packages/cip113/src/Cip113.ts | 1099 + packages/cip113/src/Classify.ts | 189 + packages/cip113/src/Deployment.ts | 516 + packages/cip113/src/Issuer.ts | 1153 + packages/cip113/src/Query.ts | 424 + packages/cip113/src/Types.ts | 45 + packages/cip113/src/UplcBackend.ts | 181 + packages/cip113/src/Versions.ts | 649 + packages/cip113/src/index.ts | 25 + packages/cip113/src/internal/Effects.ts | 35 + packages/cip113/src/internal/Encode.ts | 154 + packages/cip113/test/Budgets.test.ts | 192 + packages/cip113/test/Cip113Codec.test.ts | 605 + packages/cip113/test/Cip113Order.test.ts | 211 + packages/cip113/test/Classify.test.ts | 220 + packages/cip113/test/Deployment.live.test.ts | 105 + packages/cip113/test/Deployment.test.ts | 124 + packages/cip113/test/IssuerDerive.test.ts | 448 + packages/cip113/test/IssuerTx.test.ts | 471 + packages/cip113/test/Query.test.ts | 370 + packages/cip113/test/TransferTx.test.ts | 555 + packages/cip113/test/UplcBackend.test.ts | 365 + packages/cip113/test/Versions.test.ts | 177 + packages/cip113/test/tx-shape.ts | 130 + packages/cip113/tsconfig.build.json | 10 + packages/cip113/tsconfig.json | 6 + packages/cip113/tsconfig.src.json | 11 + packages/cip113/tsconfig.test.json | 33 + packages/cip113/vitest.config.ts | 9 + packages/cip139/README.md | 89 + packages/cip139/package.json | 79 + packages/cip139/src/QueryLayer.ts | 592 + packages/cip139/src/Types.ts | 118 + packages/cip139/src/index.ts | 11 + packages/cip139/test/QueryLayer.test.ts | 254 + packages/cip139/tsconfig.build.json | 10 + packages/cip139/tsconfig.json | 6 + packages/cip139/tsconfig.src.json | 11 + packages/cip139/tsconfig.test.json | 32 + packages/cip139/vitest.config.ts | 9 + packages/cip30/README.md | 60 + packages/cip30/package.json | 78 + packages/cip30/src/Account.ts | 97 + packages/cip30/src/Connector.ts | 208 + packages/cip30/src/Consent.ts | 96 + packages/cip30/src/ReferenceSigning.ts | 90 + packages/cip30/src/index.ts | 9 + packages/cip30/test/Connector.test.ts | 138 + packages/cip30/tsconfig.build.json | 10 + packages/cip30/tsconfig.json | 6 + packages/cip30/tsconfig.src.json | 11 + packages/cip30/tsconfig.test.json | 32 + packages/cip30/vitest.config.ts | 9 + packages/cips/README.md | 73 + packages/cips/package.json | 88 + packages/cips/src/Cip102.ts | 53 + packages/cips/src/Cip105.ts | 65 + packages/cips/src/Cip129.ts | 124 + packages/cips/src/Cip14.ts | 25 + packages/cips/src/Cip16.ts | 99 + packages/cips/src/Cip1855.ts | 35 + packages/cips/src/Cip27.ts | 95 + packages/cips/src/Cip4.ts | 57 + packages/cips/src/Cip67.ts | 70 + packages/cips/src/Cip68.ts | 46 + packages/cips/src/Cip88.ts | 194 + packages/cips/src/GovMeta.ts | 270 + packages/cips/src/Uri.ts | 126 + packages/cips/src/index.ts | 18 + packages/cips/src/internal/Bech32.ts | 43 + packages/cips/test/Cip27.test.ts | 127 + packages/cips/test/Cip4.test.ts | 86 + packages/cips/test/Cip88.test.ts | 207 + packages/cips/test/Cips.test.ts | 230 + packages/cips/test/GovMeta.test.ts | 167 + packages/cips/test/Uri.test.ts | 211 + packages/cips/tsconfig.build.json | 10 + packages/cips/tsconfig.json | 6 + packages/cips/tsconfig.src.json | 11 + packages/cips/tsconfig.test.json | 32 + packages/cips/vitest.config.ts | 9 + packages/dijkstra/README.md | 68 + packages/dijkstra/package.json | 76 + packages/dijkstra/src/Body.ts | 330 + packages/dijkstra/src/NativeScript.ts | 105 + packages/dijkstra/src/index.ts | 10 + packages/dijkstra/src/internal/Cbor.ts | 122 + packages/dijkstra/src/internal/Hex.ts | 30 + packages/dijkstra/test/Dijkstra.test.ts | 148 + packages/dijkstra/tsconfig.build.json | 10 + packages/dijkstra/tsconfig.json | 6 + packages/dijkstra/tsconfig.src.json | 11 + packages/dijkstra/tsconfig.test.json | 32 + packages/dijkstra/vitest.config.ts | 9 + packages/evolution/docgen.json | 12 +- packages/evolution/docs/modules/Address.ts.md | 66 +- .../evolution/docs/modules/AddressEras.ts.md | 75 +- .../evolution/docs/modules/AddressTag.ts.md | 84 +- packages/evolution/docs/modules/Anchor.ts.md | 1 + .../evolution/docs/modules/AssetName.ts.md | 53 +- packages/evolution/docs/modules/Assets.ts.md | 1 + .../docs/modules/AuxiliaryData.ts.md | 32 +- .../docs/modules/AuxiliaryDataHash.ts.md | 75 +- .../evolution/docs/modules/BaseAddress.ts.md | 1 + packages/evolution/docs/modules/Bech32.ts.md | 1 + packages/evolution/docs/modules/BigInt.ts.md | 1 + .../docs/modules/Bip32PrivateKey.ts.md | 93 +- .../docs/modules/Bip32PublicKey.ts.md | 80 +- packages/evolution/docs/modules/Block.ts.md | 1 + .../docs/modules/BlockBodyHash.ts.md | 1 + .../docs/modules/BlockHeaderHash.ts.md | 1 + .../docs/modules/BootstrapWitness.ts.md | 1 + .../evolution/docs/modules/BoundedBytes.ts.md | 1 + .../evolution/docs/modules/ByronAddress.ts.md | 1 + packages/evolution/docs/modules/Bytes.ts.md | 1 + .../evolution/docs/modules/Bytes128.ts.md | 1 + packages/evolution/docs/modules/Bytes16.ts.md | 1 + packages/evolution/docs/modules/Bytes29.ts.md | 1 + packages/evolution/docs/modules/Bytes32.ts.md | 1 + packages/evolution/docs/modules/Bytes4.ts.md | 1 + .../evolution/docs/modules/Bytes448.ts.md | 1 + packages/evolution/docs/modules/Bytes57.ts.md | 1 + packages/evolution/docs/modules/Bytes64.ts.md | 1 + packages/evolution/docs/modules/Bytes80.ts.md | 1 + packages/evolution/docs/modules/Bytes96.ts.md | 1 + packages/evolution/docs/modules/CBOR.ts.md | 389 +- .../evolution/docs/modules/CBORBuilder.ts.md | 534 + .../evolution/docs/modules/Certificate.ts.md | 55 +- packages/evolution/docs/modules/Codec.ts.md | 3 +- packages/evolution/docs/modules/Coin.ts.md | 3 +- .../modules/CommitteeColdCredential.ts.md | 3 +- .../docs/modules/CommitteeHotCredential.ts.md | 3 +- .../evolution/docs/modules/Constitution.ts.md | 12 +- .../evolution/docs/modules/CostModel.ts.md | 3 +- .../evolution/docs/modules/Credential.ts.md | 30 +- packages/evolution/docs/modules/DRep.ts.md | 3 +- .../docs/modules/DRepCredential.ts.md | 3 +- packages/evolution/docs/modules/Data.ts.md | 184 +- .../evolution/docs/modules/DataJson.ts.md | 3 +- .../evolution/docs/modules/DatumHash.ts.md | 69 +- .../evolution/docs/modules/DatumOption.ts.md | 53 +- packages/evolution/docs/modules/DnsName.ts.md | 3 +- .../docs/modules/Ed25519Signature.ts.md | 83 +- .../docs/modules/EffectRuntime.ts.md | 3 +- .../docs/modules/EnterpriseAddress.ts.md | 3 +- packages/evolution/docs/modules/EpochNo.ts.md | 3 +- .../docs/modules/FeeValidation.ts.md | 3 +- packages/evolution/docs/modules/Fees.ts.md | 96 + .../docs/modules/GovernanceAction.ts.md | 30 +- packages/evolution/docs/modules/Hash28.ts.md | 3 +- packages/evolution/docs/modules/Header.ts.md | 3 +- .../evolution/docs/modules/HeaderBody.ts.md | 3 +- packages/evolution/docs/modules/IPv4.ts.md | 3 +- packages/evolution/docs/modules/IPv6.ts.md | 3 +- .../evolution/docs/modules/InlineDatum.ts.md | 42 +- packages/evolution/docs/modules/KESVkey.ts.md | 3 +- .../evolution/docs/modules/KesSignature.ts.md | 3 +- packages/evolution/docs/modules/KeyHash.ts.md | 99 +- packages/evolution/docs/modules/Label.ts.md | 3 +- .../evolution/docs/modules/Language.ts.md | 3 +- .../evolution/docs/modules/Metadata.ts.md | 3 +- packages/evolution/docs/modules/MinAda.ts.md | 77 + packages/evolution/docs/modules/Mint.ts.md | 3 +- .../evolution/docs/modules/MultiAsset.ts.md | 3 +- .../docs/modules/MultiHostName.ts.md | 3 +- .../docs/modules/NativeScriptJSON.ts.md | 3 +- .../docs/modules/NativeScripts.ts.md | 28 +- packages/evolution/docs/modules/Natural.ts.md | 3 +- packages/evolution/docs/modules/Network.ts.md | 3 +- .../evolution/docs/modules/NetworkId.ts.md | 3 +- .../evolution/docs/modules/NonZeroInt64.ts.md | 3 +- .../docs/modules/NonnegativeInterval.ts.md | 54 +- packages/evolution/docs/modules/Numeric.ts.md | 3 +- .../docs/modules/OperationalCert.ts.md | 3 +- .../docs/modules/OriginalBytes.ts.md | 57 + .../docs/modules/PaymentAddress.ts.md | 3 +- .../evolution/docs/modules/PlutusV1.ts.md | 3 +- .../evolution/docs/modules/PlutusV2.ts.md | 3 +- .../evolution/docs/modules/PlutusV3.ts.md | 3 +- packages/evolution/docs/modules/Pointer.ts.md | 3 +- .../docs/modules/PointerAddress.ts.md | 5 +- .../evolution/docs/modules/PolicyId.ts.md | 70 +- .../evolution/docs/modules/PoolKeyHash.ts.md | 3 +- .../evolution/docs/modules/PoolMetadata.ts.md | 3 +- .../evolution/docs/modules/PoolParams.ts.md | 101 +- packages/evolution/docs/modules/Port.ts.md | 3 +- .../evolution/docs/modules/PositiveCoin.ts.md | 3 +- .../evolution/docs/modules/PrivateKey.ts.md | 7 +- .../docs/modules/ProposalProcedure.ts.md | 13 +- .../docs/modules/ProposalProcedures.ts.md | 185 +- .../docs/modules/ProtocolParamUpdate.ts.md | 3 +- .../docs/modules/ProtocolVersion.ts.md | 3 +- .../evolution/docs/modules/Redeemer.ts.md | 59 +- .../evolution/docs/modules/Redeemers.ts.md | 209 +- packages/evolution/docs/modules/Relay.ts.md | 3 +- .../docs/modules/RewardAccount.ts.md | 3 +- .../docs/modules/RewardAddress.ts.md | 3 +- packages/evolution/docs/modules/Script.ts.md | 32 +- .../docs/modules/ScriptDataHash.ts.md | 69 +- .../evolution/docs/modules/ScriptHash.ts.md | 47 +- .../evolution/docs/modules/ScriptRef.ts.md | 5 +- .../docs/modules/SingleHostAddr.ts.md | 3 +- .../docs/modules/SingleHostName.ts.md | 3 +- packages/evolution/docs/modules/Slot.ts.md | 3 +- .../evolution/docs/modules/SlotConfig.ts.md | 3 +- .../docs/modules/StakeReference.ts.md | 3 +- packages/evolution/docs/modules/TSchema.ts.md | 535 - packages/evolution/docs/modules/Text.ts.md | 3 +- packages/evolution/docs/modules/Text128.ts.md | 3 +- packages/evolution/docs/modules/Time.ts.md | 3 +- .../evolution/docs/modules/Transaction.ts.md | 140 +- .../docs/modules/TransactionBody.ts.md | 77 +- .../docs/modules/TransactionHash.ts.md | 57 +- .../docs/modules/TransactionIndex.ts.md | 3 +- .../docs/modules/TransactionInput.ts.md | 3 +- .../docs/modules/TransactionMetadatum.ts.md | 31 +- .../modules/TransactionMetadatumLabels.ts.md | 3 +- .../docs/modules/TransactionOutput.ts.md | 529 +- .../docs/modules/TransactionWitnessSet.ts.md | 143 +- packages/evolution/docs/modules/TxOut.ts.md | 55 +- packages/evolution/docs/modules/UPLC.ts.md | 21 +- packages/evolution/docs/modules/UTxO.ts.md | 3 +- packages/evolution/docs/modules/Unit.ts.md | 3 +- .../evolution/docs/modules/UnitInterval.ts.md | 65 +- .../evolution/docs/modules/UnixTime.ts.md | 3 +- packages/evolution/docs/modules/Url.ts.md | 3 +- packages/evolution/docs/modules/VKey.ts.md | 63 +- packages/evolution/docs/modules/Value.ts.md | 32 +- .../docs/modules/VotingProcedures.ts.md | 81 +- packages/evolution/docs/modules/VrfCert.ts.md | 3 +- .../evolution/docs/modules/VrfKeyHash.ts.md | 3 +- packages/evolution/docs/modules/VrfVkey.ts.md | 3 +- .../evolution/docs/modules/Withdrawals.ts.md | 3 +- .../docs/modules/blueprint/Codegen.ts.md | 1 + .../modules/blueprint/CodegenConfig.ts.md | 1 + .../docs/modules/blueprint/Types.ts.md | 1 + .../evolution/docs/modules/cose/Header.ts.md | 235 +- .../evolution/docs/modules/cose/Key.ts.md | 26 +- .../evolution/docs/modules/cose/Label.ts.md | 3 +- .../evolution/docs/modules/cose/Sign.ts.md | 3 +- .../evolution/docs/modules/cose/Sign1.ts.md | 3 +- .../docs/modules/cose/SignData.ts.md | 117 +- .../evolution/docs/modules/cose/Utils.ts.md | 3 +- .../docs/modules/plutus/Address.ts.md | 21 +- .../docs/modules/plutus/CIP68Metadata.ts.md | 3 +- .../docs/modules/plutus/Credential.ts.md | 3 +- .../docs/modules/plutus/OutputReference.ts.md | 3 +- .../evolution/docs/modules/plutus/Value.ts.md | 3 +- .../docs/modules/sdk/EvalRedeemer.ts.md | 3 +- .../evolution/docs/modules/sdk/Type.ts.md | 3 +- .../modules/sdk/builders/CoinSelection.ts.md | 46 +- .../sdk/builders/EvaluationStateManager.ts.md | 3 +- .../sdk/builders/RedeemerBuilder.ts.md | 65 +- .../modules/sdk/builders/SignBuilder.ts.md | 3 +- .../sdk/builders/SignBuilderImpl.ts.md | 3 +- .../modules/sdk/builders/SubmitBuilder.ts.md | 3 +- .../sdk/builders/SubmitBuilderImpl.ts.md | 3 +- .../sdk/builders/TransactionBuilder.ts.md | 144 +- .../sdk/builders/TransactionResult.ts.md | 3 +- .../docs/modules/sdk/builders/Unfrack.ts.md | 3 +- .../sdk/builders/operations/AddSigner.ts.md | 3 +- .../sdk/builders/operations/Attach.ts.md | 3 +- .../builders/operations/AttachMetadata.ts.md | 3 +- .../sdk/builders/operations/Collect.ts.md | 3 +- .../sdk/builders/operations/Governance.ts.md | 7 +- .../sdk/builders/operations/Mint.ts.md | 3 +- .../sdk/builders/operations/Operations.ts.md | 18 +- .../modules/sdk/builders/operations/Pay.ts.md | 20 +- .../sdk/builders/operations/Pool.ts.md | 5 +- .../sdk/builders/operations/Propose.ts.md | 8 +- .../sdk/builders/operations/ReadFrom.ts.md | 3 +- .../sdk/builders/operations/SendAll.ts.md | 3 +- .../sdk/builders/operations/Stake.ts.md | 9 +- .../sdk/builders/operations/Validity.ts.md | 3 +- .../sdk/builders/operations/Vote.ts.md | 3 +- .../modules/sdk/builders/phases/Balance.ts.md | 3 +- .../sdk/builders/phases/ChangeCreation.ts.md | 3 +- .../sdk/builders/phases/Collateral.ts.md | 3 +- .../sdk/builders/phases/Evaluation.ts.md | 5 +- .../sdk/builders/phases/Fallback.ts.md | 3 +- .../sdk/builders/phases/FeeCalculation.ts.md | 3 +- .../sdk/builders/phases/Selection.ts.md | 3 +- .../docs/modules/sdk/client/Chain.ts.md | 3 +- .../docs/modules/sdk/client/Client.ts.md | 22 +- .../modules/sdk/provider/Blockfrost.ts.md | 14 +- .../docs/modules/sdk/provider/Koios.ts.md | 269 +- .../docs/modules/sdk/provider/Kupmios.ts.md | 14 +- .../docs/modules/sdk/provider/Maestro.ts.md | 14 +- .../docs/modules/sdk/provider/Mock.ts.md | 392 + .../docs/modules/sdk/provider/Provider.ts.md | 712 +- .../modules/sdk/provider/RequestBudget.ts.md | 304 + .../docs/modules/sdk/wallet/Derivation.ts.md | 3 +- .../docs/modules/sdk/wallet/Wallet.ts.md | 77 +- packages/evolution/package.json | 3 +- packages/evolution/src/Address.ts | 46 +- packages/evolution/src/AddressTag.ts | 156 +- packages/evolution/src/AssetName.ts | 19 +- packages/evolution/src/Assets.ts | 36 +- packages/evolution/src/AuxiliaryData.ts | 29 + packages/evolution/src/AuxiliaryDataHash.ts | 23 +- packages/evolution/src/Bip32PrivateKey.ts | 79 +- packages/evolution/src/Bip32PublicKey.ts | 64 +- packages/evolution/src/CBOR.ts | 681 +- packages/evolution/src/CBORBuilder.ts | 598 + packages/evolution/src/Certificate.ts | 20 +- packages/evolution/src/Constitution.ts | 5 +- packages/evolution/src/Data.ts | 290 +- packages/evolution/src/DatumHash.ts | 24 +- packages/evolution/src/Ed25519Signature.ts | 25 +- packages/evolution/src/Fees.ts | 118 + packages/evolution/src/GovernanceAction.ts | 19 + packages/evolution/src/InlineDatum.ts | 30 + packages/evolution/src/KeyHash.ts | 24 +- packages/evolution/src/Label.ts | 7 + packages/evolution/src/Metadata.ts | 5 +- packages/evolution/src/MinAda.ts | 63 + packages/evolution/src/Mint.ts | 6 +- packages/evolution/src/MultiAsset.ts | 6 +- packages/evolution/src/NativeScripts.ts | 62 +- packages/evolution/src/NonnegativeInterval.ts | 66 + packages/evolution/src/PolicyId.ts | 24 +- packages/evolution/src/PoolParams.ts | 41 +- packages/evolution/src/ProposalProcedures.ts | 24 +- packages/evolution/src/Redeemer.ts | 7 +- packages/evolution/src/Redeemers.ts | 115 +- packages/evolution/src/Script.ts | 19 + packages/evolution/src/ScriptDataHash.ts | 23 +- packages/evolution/src/TSchema.ts | 41 +- packages/evolution/src/Time.ts | 32 + packages/evolution/src/Transaction.ts | 114 +- packages/evolution/src/TransactionBody.ts | 162 +- packages/evolution/src/TransactionHash.ts | 25 +- .../evolution/src/TransactionMetadatum.ts | 22 +- packages/evolution/src/TransactionOutput.ts | 377 +- .../evolution/src/TransactionWitnessSet.ts | 114 +- packages/evolution/src/TxOut.ts | 24 +- packages/evolution/src/UnitInterval.ts | 43 +- packages/evolution/src/VKey.ts | 24 +- packages/evolution/src/Value.ts | 25 +- packages/evolution/src/VotingProcedures.ts | 50 + packages/evolution/src/cose/Header.ts | 24 +- packages/evolution/src/cose/Key.ts | 19 + packages/evolution/src/cose/SignData.ts | 194 +- packages/evolution/src/index.ts | 14 + .../src/sdk/builders/CoinSelection.ts | 81 +- .../src/sdk/builders/TransactionBuilder.ts | 19 + .../src/sdk/builders/internal/Cip2.ts | 296 + .../src/sdk/builders/internal/build.ts | 7 +- .../src/sdk/builders/internal/txBuilder.ts | 364 +- .../src/sdk/builders/phases/Selection.ts | 20 +- packages/evolution/src/sdk/client/Client.ts | 9 + .../src/sdk/client/internal/Client.ts | 3 + .../src/sdk/client/internal/Wallets.ts | 28 +- .../evolution/src/sdk/provider/Blockfrost.ts | 37 +- packages/evolution/src/sdk/provider/Koios.ts | 201 +- .../evolution/src/sdk/provider/Kupmios.ts | 7 +- .../evolution/src/sdk/provider/Maestro.ts | 7 +- packages/evolution/src/sdk/provider/Mock.ts | 589 + .../evolution/src/sdk/provider/Provider.ts | 640 + .../src/sdk/provider/RequestBudget.ts | 283 + .../src/sdk/provider/internal/Blockfrost.ts | 20 +- .../sdk/provider/internal/BlockfrostEffect.ts | 105 +- .../sdk/provider/internal/BlockfrostQuery.ts | 749 + .../src/sdk/provider/internal/HttpUtils.ts | 161 +- .../src/sdk/provider/internal/Koios.ts | 259 +- .../src/sdk/provider/internal/KoiosEffect.ts | 413 +- .../src/sdk/provider/internal/KoiosQuery.ts | 1229 + .../sdk/provider/internal/KupmiosEffects.ts | 56 +- .../src/sdk/provider/internal/Maestro.ts | 19 +- .../sdk/provider/internal/MaestroEffect.ts | 22 + .../src/sdk/provider/internal/Ogmios.ts | 9 + packages/evolution/test/AddressTag.test.ts | 97 + .../evolution/test/AssetsUnitSpelling.test.ts | 62 + .../evolution/test/Bip39Passphrase.test.ts | 38 + packages/evolution/test/CBOR.test.ts | 26 + packages/evolution/test/CBORBuilder.test.ts | 283 + .../evolution/test/COSEKey.publicKey.test.ts | 67 + .../test/CardanoPathDerivation.test.ts | 82 + .../evolution/test/CborHeaderSize.test.ts | 46 + .../test/Certificate.PoolOwners.test.ts | 100 + packages/evolution/test/Cip2.test.ts | 140 + .../test/Cip21CanonicalOrder.test.ts | 59 + packages/evolution/test/Cip30GetUtxos.test.ts | 24 +- .../evolution/test/ClientWithProvider.test.ts | 47 + packages/evolution/test/CoinSelection.test.ts | 71 +- packages/evolution/test/Data.golden.test.ts | 82 +- packages/evolution/test/Data.test.ts | 10 + .../test/DatumOption.OriginalBytes.test.ts | 49 +- packages/evolution/test/FromEncoded.test.ts | 336 + .../test/HeaderMap.structural.test.ts | 53 + packages/evolution/test/HexBrands.test.ts | 76 + .../test/HexCodecComposition.test.ts | 42 + .../test/InlineDatum.TxCodecOptions.test.ts | 11 - .../test/InlineDatumOriginalBytes.test.ts | 55 + .../test/KoiosEffect.timeout.test.ts | 136 + .../test/KoiosQuery.addressBatches.test.ts | 83 + .../evolution/test/KoiosQuery.history.test.ts | 725 + .../evolution/test/KoiosQuery.mapping.test.ts | 329 + packages/evolution/test/Label.test.ts | 69 + packages/evolution/test/MinAda.test.ts | 59 + packages/evolution/test/MockProvider.test.ts | 310 + .../evolution/test/NativeScripts.JSON.test.ts | 144 + .../evolution/test/NoGlobalShadowing.test.ts | 66 + .../NonnegativeInterval.fromDecimal.test.ts | 61 + .../test/ProposalProcedures.CML.test.ts | 23 + packages/evolution/test/Provenance.test.ts | 204 + .../test/Provider64BitAmounts.test.ts | 20 +- packages/evolution/test/ProviderTip.test.ts | 171 + .../evolution/test/PublicCodecSurface.test.ts | 55 + packages/evolution/test/RequestBudget.test.ts | 205 + packages/evolution/test/SignData.test.ts | 33 + .../evolution/test/SignDataAssemble.test.ts | 109 + packages/evolution/test/SignDataKeyId.test.ts | 41 + packages/evolution/test/TimeDomain.test.ts | 52 + .../test/Transaction.BareInputSet.test.ts | 57 + .../Transaction.UnmodelledBodyKey.test.ts | 47 + .../test/TransactionMetadatumInt.test.ts | 86 + .../test/TxBuilder.CodecOptions.test.ts | 118 + .../test/TxBuilder.FeeCalculation.test.ts | 98 + .../test/TxOutEncodingFormat.test.ts | 53 + .../test/UnitInterval.fromBigDecimal.test.ts | 36 + packages/evolution/test/UtilsHash.CML.test.ts | 28 + .../evolution/test/golden/constr.golden.json | 29958 ++++++++-------- .../evolution/test/golden/data.golden.json | 14072 ++++---- .../evolution/test/golden/list.golden.json | 23523 ++++++------ .../evolution/test/golden/map.golden.json | 14011 ++++---- .../test/provider/Blockfrost.test.ts | 74 +- .../test/provider/BlockfrostQuery.test.ts | 492 + .../test/provider/KoiosParamsCache.test.ts | 103 + .../test/provider/KoiosRegistration.test.ts | 62 + .../evolution/test/provider/Kupmios.test.ts | 19 + .../evolution/test/provider/Maestro.test.ts | 26 + .../fixtures/koios/cli_protocol_params.json | 1083 + packages/hardware-cardano/README.md | 53 + packages/hardware-cardano/package.json | 79 + packages/hardware-cardano/src/Ledger.ts | 546 + packages/hardware-cardano/src/LedgerTypes.ts | 413 + packages/hardware-cardano/src/Trezor.ts | 466 + packages/hardware-cardano/src/TrezorTypes.ts | 433 + packages/hardware-cardano/src/index.ts | 9 + packages/hardware-cardano/src/internal/Hex.ts | 30 + .../hardware-cardano/src/internal/Path.ts | 44 + .../hardware-cardano/test/Converters.test.ts | 99 + packages/hardware-cardano/tsconfig.build.json | 10 + packages/hardware-cardano/tsconfig.json | 6 + packages/hardware-cardano/tsconfig.src.json | 11 + packages/hardware-cardano/tsconfig.test.json | 32 + packages/hardware-cardano/vitest.config.ts | 9 + packages/plan/README.md | 57 + packages/plan/package.json | 78 + packages/plan/src/ExUnits.ts | 166 + packages/plan/src/Plan.ts | 1504 + packages/plan/src/index.ts | 7 + packages/plan/src/internal/Encode.ts | 229 + packages/plan/test/Params.test.ts | 102 + packages/plan/test/Plan.test.ts | 199 + packages/plan/tsconfig.build.json | 10 + packages/plan/tsconfig.json | 6 + packages/plan/tsconfig.src.json | 11 + packages/plan/tsconfig.test.json | 32 + packages/plan/vitest.config.ts | 9 + packages/review/README.md | 62 + packages/review/package.json | 77 + packages/review/src/Analyze.ts | 328 + packages/review/src/Brands.ts | 188 + packages/review/src/Cose.ts | 192 + packages/review/src/Decode.ts | 71 + packages/review/src/Errors.ts | 14 + packages/review/src/Inspect.ts | 957 + packages/review/src/Phase1.ts | 408 + packages/review/src/Types.ts | 167 + packages/review/src/index.ts | 17 + packages/review/src/internal/Cursor.ts | 217 + .../review/src/internal/EvolutionDecode.ts | 472 + packages/review/src/internal/Hex.ts | 30 + packages/review/test/Cose.test.ts | 144 + packages/review/test/Inspect.test.ts | 89 + packages/review/test/fixtures.ts | 27 + packages/review/tsconfig.build.json | 10 + packages/review/tsconfig.json | 6 + packages/review/tsconfig.src.json | 11 + packages/review/tsconfig.test.json | 32 + packages/review/vitest.config.ts | 9 + pnpm-lock.yaml | 202 + 748 files changed, 93094 insertions(+), 46634 deletions(-) create mode 100644 .changeset/assemble-from-encoded-parts.md create mode 100644 .changeset/asset-unit-two-spellings.md create mode 100644 .changeset/backup-keys-encrypted-export.md create mode 100644 .changeset/bip39-passphrase-bytes-and-paths.md create mode 100644 .changeset/canonical-jcs-and-cip116.md create mode 100644 .changeset/cbor-builder-and-byte-helpers.md create mode 100644 .changeset/cddl-conformance-and-reachable-codecs.md create mode 100644 .changeset/cip113-programmable-tokens.md create mode 100644 .changeset/cip139-query-layer.md create mode 100644 .changeset/cip21-multiasset-canonical-order.md create mode 100644 .changeset/cip30-read-surface.md create mode 100644 .changeset/cips-companions.md create mode 100644 .changeset/coin-selection-random-improve.md create mode 100644 .changeset/cose-header-map-and-sign-data.md create mode 100644 .changeset/dijkstra-prefork-fields.md create mode 100644 .changeset/exact-conway-fee-math.md create mode 100644 .changeset/hardware-cardano-sign-requests.md create mode 100644 .changeset/hex-boundary-brands.md create mode 100644 .changeset/koios-chain-parameters-over-the-wire.md create mode 100644 .changeset/koios-credential-utxos-hex-and-batching.md create mode 100644 .changeset/koios-history-tier-behaviours.md create mode 100644 .changeset/koios-multi-id-bodies.md create mode 100644 .changeset/koios-request-timeout-option.md create mode 100644 .changeset/koios-token-source.md create mode 100644 .changeset/native-scripts-json.md create mode 100644 .changeset/no-credential-on-a-cleartext-wire.md create mode 100644 .changeset/plan-engine.md create mode 100644 .changeset/plan-fee-math-one-implementation.md create mode 100644 .changeset/plutus-data-splicing-and-schema.md create mode 100644 .changeset/provider-gettip-optional.md create mode 100644 .changeset/provider-history-tier.md create mode 100644 .changeset/provider-tx-confirmations.md create mode 100644 .changeset/request-report-refusal-body.md create mode 100644 .changeset/review-before-sign.md create mode 100644 .changeset/set-tag-and-unknown-body-keys.md create mode 100644 .changeset/tag-102-definite-wrapper.md create mode 100644 .changeset/transfer-refuses-to-drop-a-datum.md create mode 100644 .changeset/txs-at-address-batches.md create mode 100644 docs/content/docs/modules/CBORBuilder.mdx create mode 100644 docs/content/docs/modules/Fees.mdx create mode 100644 docs/content/docs/modules/MinAda.mdx create mode 100644 docs/content/docs/modules/OriginalBytes.mdx delete mode 100644 docs/content/docs/modules/TSchema.mdx create mode 100644 docs/content/docs/modules/sdk/provider/Mock.mdx create mode 100644 docs/content/docs/modules/sdk/provider/RequestBudget.mdx create mode 100644 packages/backup-keys/README.md create mode 100644 packages/backup-keys/package.json create mode 100644 packages/backup-keys/src/EncryptedExport.ts create mode 100644 packages/backup-keys/src/index.ts create mode 100644 packages/backup-keys/test/EncryptedExport.test.ts create mode 100644 packages/backup-keys/tsconfig.build.json create mode 100644 packages/backup-keys/tsconfig.json create mode 100644 packages/backup-keys/tsconfig.src.json create mode 100644 packages/backup-keys/tsconfig.test.json create mode 100644 packages/backup-keys/vitest.config.ts create mode 100644 packages/canonical/README.md create mode 100644 packages/canonical/package.json create mode 100644 packages/canonical/src/Cip116.ts create mode 100644 packages/canonical/src/Jcs.ts create mode 100644 packages/canonical/src/index.ts create mode 100644 packages/canonical/test/Canonical.test.ts create mode 100644 packages/canonical/tsconfig.build.json create mode 100644 packages/canonical/tsconfig.json create mode 100644 packages/canonical/tsconfig.src.json create mode 100644 packages/canonical/tsconfig.test.json create mode 100644 packages/canonical/vitest.config.ts create mode 100644 packages/cip113/README.md create mode 100644 packages/cip113/harness/blueprint.ts create mode 100644 packages/cip113/harness/budgets.ts create mode 100644 packages/cip113/harness/cost-model.ts create mode 100644 packages/cip113/package.json create mode 100644 packages/cip113/src/Budgets.ts create mode 100644 packages/cip113/src/Cip113.ts create mode 100644 packages/cip113/src/Classify.ts create mode 100644 packages/cip113/src/Deployment.ts create mode 100644 packages/cip113/src/Issuer.ts create mode 100644 packages/cip113/src/Query.ts create mode 100644 packages/cip113/src/Types.ts create mode 100644 packages/cip113/src/UplcBackend.ts create mode 100644 packages/cip113/src/Versions.ts create mode 100644 packages/cip113/src/index.ts create mode 100644 packages/cip113/src/internal/Effects.ts create mode 100644 packages/cip113/src/internal/Encode.ts create mode 100644 packages/cip113/test/Budgets.test.ts create mode 100644 packages/cip113/test/Cip113Codec.test.ts create mode 100644 packages/cip113/test/Cip113Order.test.ts create mode 100644 packages/cip113/test/Classify.test.ts create mode 100644 packages/cip113/test/Deployment.live.test.ts create mode 100644 packages/cip113/test/Deployment.test.ts create mode 100644 packages/cip113/test/IssuerDerive.test.ts create mode 100644 packages/cip113/test/IssuerTx.test.ts create mode 100644 packages/cip113/test/Query.test.ts create mode 100644 packages/cip113/test/TransferTx.test.ts create mode 100644 packages/cip113/test/UplcBackend.test.ts create mode 100644 packages/cip113/test/Versions.test.ts create mode 100644 packages/cip113/test/tx-shape.ts create mode 100644 packages/cip113/tsconfig.build.json create mode 100644 packages/cip113/tsconfig.json create mode 100644 packages/cip113/tsconfig.src.json create mode 100644 packages/cip113/tsconfig.test.json create mode 100644 packages/cip113/vitest.config.ts create mode 100644 packages/cip139/README.md create mode 100644 packages/cip139/package.json create mode 100644 packages/cip139/src/QueryLayer.ts create mode 100644 packages/cip139/src/Types.ts create mode 100644 packages/cip139/src/index.ts create mode 100644 packages/cip139/test/QueryLayer.test.ts create mode 100644 packages/cip139/tsconfig.build.json create mode 100644 packages/cip139/tsconfig.json create mode 100644 packages/cip139/tsconfig.src.json create mode 100644 packages/cip139/tsconfig.test.json create mode 100644 packages/cip139/vitest.config.ts create mode 100644 packages/cip30/README.md create mode 100644 packages/cip30/package.json create mode 100644 packages/cip30/src/Account.ts create mode 100644 packages/cip30/src/Connector.ts create mode 100644 packages/cip30/src/Consent.ts create mode 100644 packages/cip30/src/ReferenceSigning.ts create mode 100644 packages/cip30/src/index.ts create mode 100644 packages/cip30/test/Connector.test.ts create mode 100644 packages/cip30/tsconfig.build.json create mode 100644 packages/cip30/tsconfig.json create mode 100644 packages/cip30/tsconfig.src.json create mode 100644 packages/cip30/tsconfig.test.json create mode 100644 packages/cip30/vitest.config.ts create mode 100644 packages/cips/README.md create mode 100644 packages/cips/package.json create mode 100644 packages/cips/src/Cip102.ts create mode 100644 packages/cips/src/Cip105.ts create mode 100644 packages/cips/src/Cip129.ts create mode 100644 packages/cips/src/Cip14.ts create mode 100644 packages/cips/src/Cip16.ts create mode 100644 packages/cips/src/Cip1855.ts create mode 100644 packages/cips/src/Cip27.ts create mode 100644 packages/cips/src/Cip4.ts create mode 100644 packages/cips/src/Cip67.ts create mode 100644 packages/cips/src/Cip68.ts create mode 100644 packages/cips/src/Cip88.ts create mode 100644 packages/cips/src/GovMeta.ts create mode 100644 packages/cips/src/Uri.ts create mode 100644 packages/cips/src/index.ts create mode 100644 packages/cips/src/internal/Bech32.ts create mode 100644 packages/cips/test/Cip27.test.ts create mode 100644 packages/cips/test/Cip4.test.ts create mode 100644 packages/cips/test/Cip88.test.ts create mode 100644 packages/cips/test/Cips.test.ts create mode 100644 packages/cips/test/GovMeta.test.ts create mode 100644 packages/cips/test/Uri.test.ts create mode 100644 packages/cips/tsconfig.build.json create mode 100644 packages/cips/tsconfig.json create mode 100644 packages/cips/tsconfig.src.json create mode 100644 packages/cips/tsconfig.test.json create mode 100644 packages/cips/vitest.config.ts create mode 100644 packages/dijkstra/README.md create mode 100644 packages/dijkstra/package.json create mode 100644 packages/dijkstra/src/Body.ts create mode 100644 packages/dijkstra/src/NativeScript.ts create mode 100644 packages/dijkstra/src/index.ts create mode 100644 packages/dijkstra/src/internal/Cbor.ts create mode 100644 packages/dijkstra/src/internal/Hex.ts create mode 100644 packages/dijkstra/test/Dijkstra.test.ts create mode 100644 packages/dijkstra/tsconfig.build.json create mode 100644 packages/dijkstra/tsconfig.json create mode 100644 packages/dijkstra/tsconfig.src.json create mode 100644 packages/dijkstra/tsconfig.test.json create mode 100644 packages/dijkstra/vitest.config.ts create mode 100644 packages/evolution/docs/modules/CBORBuilder.ts.md create mode 100644 packages/evolution/docs/modules/Fees.ts.md create mode 100644 packages/evolution/docs/modules/MinAda.ts.md create mode 100644 packages/evolution/docs/modules/OriginalBytes.ts.md delete mode 100644 packages/evolution/docs/modules/TSchema.ts.md create mode 100644 packages/evolution/docs/modules/sdk/provider/Mock.ts.md create mode 100644 packages/evolution/docs/modules/sdk/provider/RequestBudget.ts.md create mode 100644 packages/evolution/src/CBORBuilder.ts create mode 100644 packages/evolution/src/Fees.ts create mode 100644 packages/evolution/src/MinAda.ts create mode 100644 packages/evolution/src/sdk/builders/internal/Cip2.ts create mode 100644 packages/evolution/src/sdk/provider/Mock.ts create mode 100644 packages/evolution/src/sdk/provider/RequestBudget.ts create mode 100644 packages/evolution/src/sdk/provider/internal/BlockfrostQuery.ts create mode 100644 packages/evolution/src/sdk/provider/internal/KoiosQuery.ts create mode 100644 packages/evolution/test/AddressTag.test.ts create mode 100644 packages/evolution/test/AssetsUnitSpelling.test.ts create mode 100644 packages/evolution/test/Bip39Passphrase.test.ts create mode 100644 packages/evolution/test/CBORBuilder.test.ts create mode 100644 packages/evolution/test/COSEKey.publicKey.test.ts create mode 100644 packages/evolution/test/CardanoPathDerivation.test.ts create mode 100644 packages/evolution/test/CborHeaderSize.test.ts create mode 100644 packages/evolution/test/Certificate.PoolOwners.test.ts create mode 100644 packages/evolution/test/Cip2.test.ts create mode 100644 packages/evolution/test/Cip21CanonicalOrder.test.ts create mode 100644 packages/evolution/test/ClientWithProvider.test.ts create mode 100644 packages/evolution/test/FromEncoded.test.ts create mode 100644 packages/evolution/test/HeaderMap.structural.test.ts create mode 100644 packages/evolution/test/HexBrands.test.ts create mode 100644 packages/evolution/test/HexCodecComposition.test.ts create mode 100644 packages/evolution/test/InlineDatumOriginalBytes.test.ts create mode 100644 packages/evolution/test/KoiosEffect.timeout.test.ts create mode 100644 packages/evolution/test/KoiosQuery.addressBatches.test.ts create mode 100644 packages/evolution/test/KoiosQuery.history.test.ts create mode 100644 packages/evolution/test/KoiosQuery.mapping.test.ts create mode 100644 packages/evolution/test/Label.test.ts create mode 100644 packages/evolution/test/MinAda.test.ts create mode 100644 packages/evolution/test/MockProvider.test.ts create mode 100644 packages/evolution/test/NativeScripts.JSON.test.ts create mode 100644 packages/evolution/test/NoGlobalShadowing.test.ts create mode 100644 packages/evolution/test/NonnegativeInterval.fromDecimal.test.ts create mode 100644 packages/evolution/test/Provenance.test.ts create mode 100644 packages/evolution/test/ProviderTip.test.ts create mode 100644 packages/evolution/test/PublicCodecSurface.test.ts create mode 100644 packages/evolution/test/RequestBudget.test.ts create mode 100644 packages/evolution/test/SignDataAssemble.test.ts create mode 100644 packages/evolution/test/SignDataKeyId.test.ts create mode 100644 packages/evolution/test/TimeDomain.test.ts create mode 100644 packages/evolution/test/Transaction.BareInputSet.test.ts create mode 100644 packages/evolution/test/Transaction.UnmodelledBodyKey.test.ts create mode 100644 packages/evolution/test/TransactionMetadatumInt.test.ts create mode 100644 packages/evolution/test/TxBuilder.CodecOptions.test.ts create mode 100644 packages/evolution/test/TxOutEncodingFormat.test.ts create mode 100644 packages/evolution/test/UnitInterval.fromBigDecimal.test.ts create mode 100644 packages/evolution/test/provider/BlockfrostQuery.test.ts create mode 100644 packages/evolution/test/provider/KoiosParamsCache.test.ts create mode 100644 packages/evolution/test/provider/KoiosRegistration.test.ts create mode 100644 packages/evolution/test/provider/fixtures/koios/cli_protocol_params.json create mode 100644 packages/hardware-cardano/README.md create mode 100644 packages/hardware-cardano/package.json create mode 100644 packages/hardware-cardano/src/Ledger.ts create mode 100644 packages/hardware-cardano/src/LedgerTypes.ts create mode 100644 packages/hardware-cardano/src/Trezor.ts create mode 100644 packages/hardware-cardano/src/TrezorTypes.ts create mode 100644 packages/hardware-cardano/src/index.ts create mode 100644 packages/hardware-cardano/src/internal/Hex.ts create mode 100644 packages/hardware-cardano/src/internal/Path.ts create mode 100644 packages/hardware-cardano/test/Converters.test.ts create mode 100644 packages/hardware-cardano/tsconfig.build.json create mode 100644 packages/hardware-cardano/tsconfig.json create mode 100644 packages/hardware-cardano/tsconfig.src.json create mode 100644 packages/hardware-cardano/tsconfig.test.json create mode 100644 packages/hardware-cardano/vitest.config.ts create mode 100644 packages/plan/README.md create mode 100644 packages/plan/package.json create mode 100644 packages/plan/src/ExUnits.ts create mode 100644 packages/plan/src/Plan.ts create mode 100644 packages/plan/src/index.ts create mode 100644 packages/plan/src/internal/Encode.ts create mode 100644 packages/plan/test/Params.test.ts create mode 100644 packages/plan/test/Plan.test.ts create mode 100644 packages/plan/tsconfig.build.json create mode 100644 packages/plan/tsconfig.json create mode 100644 packages/plan/tsconfig.src.json create mode 100644 packages/plan/tsconfig.test.json create mode 100644 packages/plan/vitest.config.ts create mode 100644 packages/review/README.md create mode 100644 packages/review/package.json create mode 100644 packages/review/src/Analyze.ts create mode 100644 packages/review/src/Brands.ts create mode 100644 packages/review/src/Cose.ts create mode 100644 packages/review/src/Decode.ts create mode 100644 packages/review/src/Errors.ts create mode 100644 packages/review/src/Inspect.ts create mode 100644 packages/review/src/Phase1.ts create mode 100644 packages/review/src/Types.ts create mode 100644 packages/review/src/index.ts create mode 100644 packages/review/src/internal/Cursor.ts create mode 100644 packages/review/src/internal/EvolutionDecode.ts create mode 100644 packages/review/src/internal/Hex.ts create mode 100644 packages/review/test/Cose.test.ts create mode 100644 packages/review/test/Inspect.test.ts create mode 100644 packages/review/test/fixtures.ts create mode 100644 packages/review/tsconfig.build.json create mode 100644 packages/review/tsconfig.json create mode 100644 packages/review/tsconfig.src.json create mode 100644 packages/review/tsconfig.test.json create mode 100644 packages/review/vitest.config.ts diff --git a/.changeset/assemble-from-encoded-parts.md b/.changeset/assemble-from-encoded-parts.md new file mode 100644 index 00000000..227eb4ce --- /dev/null +++ b/.changeset/assemble-from-encoded-parts.md @@ -0,0 +1,15 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A transaction, body, witness set or auxiliary data can be assembled from parts that are already encoded. + +`Transaction.fromEncoded`, `TransactionBody.fromEncoded`, `TransactionWitnessSet.fromEncoded` and `AuxiliaryData.fromEncoded` take the bytes of each part and frame them, rather than taking values and encoding them. A caller that holds a body it must not re-encode — because its hash is already committed to, or because a signer displayed exactly those bytes — can now assemble around it. + +`Redeemers.keepDataBytes`, `Redeemers.spliceMap` and `Redeemers.toScriptDataHashFromEncoded` are the same idea for the script-data hash: the hash is taken over the bytes as they arrived, not over a re-encode that happens to look equivalent. + +`Transaction.cborHeaderSize` reports the header width at an offset, which is what makes a part addressable: a caller slicing one element out of an array needs to know where the element starts, and a re-encode cannot promise the same bytes. + +`Transaction.setIntendedCodecOptions` / `getIntendedCodecOptions` record which options a transaction is meant to be encoded under, so a builder's choice reaches the hash computations taken during the build instead of each one defaulting independently. + +`TransactionBody` also gains the `WithFormat` pair (`fromCBORBytesWithFormat`, `fromCBORHexWithFormat`, `toCBORBytesWithFormat`, `toCBORHexWithFormat`) that the other codecs in this package already have, plus `toCBORBytes` taking `CodecOptions`. diff --git a/.changeset/asset-unit-two-spellings.md b/.changeset/asset-unit-two-spellings.md new file mode 100644 index 00000000..321bee5a --- /dev/null +++ b/.changeset/asset-unit-two-spellings.md @@ -0,0 +1,9 @@ +--- +"@evolution-sdk/evolution": patch +--- + +An asset unit is spelled two ways, and both now mean the same asset everywhere. + +The canonical spelling is the concatenation `policyId(56) + assetName`, which `getUnits` emits. `fromUnit` has always also accepted `policyId.assetName`, and a dot cannot occur in hex, so the form is unambiguous. + +The two disagreed: `fromUnit(".", 42n)` built the asset, and `getByUnit` with that **same string** answered `0n`, because it sliced the dotted text at 56. Zero is a plausible answer — it reads as "this asset is not here" — so the disagreement was silent, and silent is how it reaches a balance. One `splitUnit` now serves `fromUnit`, `fromRecord` and `getByUnit`. diff --git a/.changeset/backup-keys-encrypted-export.md b/.changeset/backup-keys-encrypted-export.md new file mode 100644 index 00000000..844b66c9 --- /dev/null +++ b/.changeset/backup-keys-encrypted-export.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/backup-keys": minor +--- + +New package: a password-encrypted, authenticated envelope for moving a wallet secret between applications, with a JSON-file, `web+cardano:` link and QR binding. + +⚠️ **Not a ratified CIP.** It implements a draft submitted for a number; until one is assigned, nothing in the package claims a CIP it does not hold. + +`EncryptedExport` is Argon2id over the password and XChaCha20-Poly1305 over the payload, in a self-describing envelope. What it is careful about: + +- **One KDF profile, pinned at the import boundary.** The Argon2id cost travels inside the envelope, so `parse` / `parseLink` require the single v1 profile exactly: an absurd memory cost is a denial of service rather than a backup, and a *weaker* one would lower the format's floor to whatever an exporter felt like paying. `decrypt` takes an already-typed envelope and enforces the ceiling rather than the equality, so a cheaper profile a caller hands it deliberately is still honoured. +- **A password is bytes.** It is hashed as the UTF-8 it was given — no trim, no case-fold, no Unicode normalisation, because whitespace is content and a trimmed password derives a different key. An empty password is refused outright. +- **The derivation is async**, because 256 MiB of Argon2id blocks a single-threaded host for seconds. diff --git a/.changeset/bip39-passphrase-bytes-and-paths.md b/.changeset/bip39-passphrase-bytes-and-paths.md new file mode 100644 index 00000000..361b9494 --- /dev/null +++ b/.changeset/bip39-passphrase-bytes-and-paths.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A BIP-39 passphrase is bytes, CIP-1854 and the DRep role are expressible, and a public key can be derived along a path. + +`Bip32PrivateKey.fromBip39Entropy` took a `string` only, so a caller holding raw passphrase bytes had to decode them as UTF-8 first. Bytes that are not valid UTF-8 do not survive that: they decode to U+FFFD, and the key derived from the mangled passphrase is a different key — a different wallet, with nothing anywhere to say so. It now takes `Uint8Array | string`, and the two agree whenever the text is the bytes. + +`CardanoPath.indices` hardcoded purpose 1852 and typed `role` as `0 | 2`, so neither CIP-1854 (shared wallets) nor role 3 (DRep) could be expressed. `PURPOSE_CIP1852` and `PURPOSE_CIP1854` are exported and the role is open. + +`Bip32PublicKey.derivePath` is the path form of the single-step `deriveChild` it already had. Deriving addresses from a co-signer's account xpub — no seed, no signing ceremony — needs exactly that. + +`AddressTag` reads an address's parts straight from its bytes: `fromHeader`, `fromBytes`, `networkId`, `paymentCredential` and `stakeCredential`, each answering `undefined` rather than guessing when the header says the address has no such part. diff --git a/.changeset/canonical-jcs-and-cip116.md b/.changeset/canonical-jcs-and-cip116.md new file mode 100644 index 00000000..d855ae10 --- /dev/null +++ b/.changeset/canonical-jcs-and-cip116.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/canonical": minor +--- + +New package: RFC 8785 JSON canonicalization (`Jcs`) and the CIP-116 JSON shape (`Cip116`). + +Both exist because something takes a **digest** over their output. A byte that differs from whoever computed the original digest is a rejected payment or a failed signature check, so "looks right" is not a standard either can be held to. + +`Jcs` is a leaf — no imports, nothing Cardano-specific: keys sorted by UTF-16 code unit, shortest escapes, ECMAScript number formatting. Two things it is explicit about: **DEL (0x7f) is not escaped**, because RFC 8785 defers to RFC 8259 which requires escaping only below 0x20, and escaping it would produce a digest nobody else computes; and it is **not** JSON-LD / RDF-Dataset canonicalization (URDNA2015), which is what governance metadata uses and which needs a full JSON-LD to N-Quads stack. + +Values with no canonical form — `undefined`, `NaN`, infinities, `bigint`, functions, symbols — are refused rather than coerced. Guessing one produces a digest that is wrong rather than one that is missing. diff --git a/.changeset/cbor-builder-and-byte-helpers.md b/.changeset/cbor-builder-and-byte-helpers.md new file mode 100644 index 00000000..f326f576 --- /dev/null +++ b/.changeset/cbor-builder-and-byte-helpers.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`CBORBuilder` offers the append-as-you-go shape over `CBOR`, and `CBOR` gains the byte helpers a splicing caller needs. + +Some callers describe a document as they walk it rather than constructing the whole value first. `CBORBuilder.Serializer` gives them that shape while **the bytes are still produced by `CBOR`'s encoder** — writes accumulate a value and its `CBORFormat`, and `finalize()` encodes through `toCBORBytesWithFormat`. It is deliberately not a second encoder: two encoders in one library that must agree byte for byte is a drift hazard. The declared length drives the structure, so an unfinished container is a `finalize()` error rather than malformed bytes a node rejects later. `Deserializer` is the read side, lenient as a CBOR reader should be: non-minimal heads and indefinite containers are accepted, and whole-item skips delegate to `CBOR.decodeItemWithOffsetAndFormat`. + +Nothing here streams, and the module says so: `finalize()` needs the whole document and `Deserializer` reads a buffer already in memory. + +`CBOR` also exports what a caller splicing pre-encoded children needs: `encodeMapAsDefinite`, `DefiniteArray`, `Raw`, `compareByteKeys` and `sortByteKeyedMap`. The two comparison helpers are the canonical byte-key order in one place, rather than re-derived per call site. diff --git a/.changeset/cddl-conformance-and-reachable-codecs.md b/.changeset/cddl-conformance-and-reachable-codecs.md new file mode 100644 index 00000000..fe790105 --- /dev/null +++ b/.changeset/cddl-conformance-and-reachable-codecs.md @@ -0,0 +1,14 @@ +--- +"@evolution-sdk/evolution": minor +--- + +CDDL conformance for four types, and the codec pairs their siblings already had. + +- `pool_params.pool_owners` is `set`, which the chain and CML both write `#6.258`. `PoolParams.PoolOwnersCDDL` writes the tag, and `poolOwnersArray` reads either form. +- `UnitInterval` gains the four-member codec pair (`fromCBORBytes`, `fromCBORHex`, `toCBORBytes`, `toCBORHex`) that every sibling type has, and CML agrees on its bytes. +- `VotingProcedures` exports codecs for `Voter` on its own (`voterToCBORBytes` / `voterToCBORHex` / `voterFromCBORBytes` / `voterFromCBORHex`): a governance UI reads a voter out of a body one at a time, not only as part of the whole map. +- `CostModel` is exported from the package entry point, so cost models can be built without a subpath import. + +`MinAda` is new: `MinAda.forOutput(output, coinsPerUtxoByte)` computes the minimum lovelace an output must carry, including the 160-byte UTxO entry overhead the ledger adds, and iterates because raising the coin can lengthen its own encoding. + +`NonnegativeInterval.fromDecimal` parses a protocol parameter written as a decimal (`"0.0577"`) into the exact rational the ledger uses, instead of a float; `ceilDiv` sits beside the other exact-rational helpers. `Time` gains the slot/POSIX conversions a TTL needs, and `Label`, `Metadata`, `TransactionMetadatum` and `Certificate` get the conformance fixes their CDDL demands. diff --git a/.changeset/cip113-programmable-tokens.md b/.changeset/cip113-programmable-tokens.md new file mode 100644 index 00000000..f0a7d25a --- /dev/null +++ b/.changeset/cip113-programmable-tokens.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/cip113": minor +--- + +New package: CIP-113 programmable tokens — the consumer transfer path, the registry codecs, the deployment records and the issuer derivation. + +`Cip113` is what a holder needs: the registry and params codecs, the withdraw-zero redeemers, the smart-wallet address, and `buildTransferTx`, which assembles the unsigned transfer. `Query` fetches the chain state a transfer needs, `Classify` answers what a UTxO is, and `Budgets` carries measured ex-units for the framework scripts. + +**Everything is parameterised by a descriptor rather than branching on a version id.** That is not future-proofing: the on-chain shapes moved four times inside one audit window, and a codec that branches on an id has to be edited for each move while one that reads a descriptor does not. + +`Deployment` says *where* an instance lives. Script hashes are deploy-time data, never constants — an instance deployed from a different compilation has different hashes, and a constant would send a transfer to a script that does not exist. Where a chain has more than one record, resolution is the consumer's to make explicit: guessing points every holder's smart-wallet address at the wrong protocol. + +The ex-units in `Budgets` are re-derivable: `harness/budgets.ts` rebuilds a deployment from the reference blueprint, prices the framework scripts on a local Plutus VM through `@evolution-sdk/aiken-uplc`, and **fails if the recorded presets no longer reproduce** — so an upstream cost change surfaces as a failing check rather than as a rejected transaction. Without a blueprint clone it skips loudly rather than passing quietly. diff --git a/.changeset/cip139-query-layer.md b/.changeset/cip139-query-layer.md new file mode 100644 index 00000000..47802769 --- /dev/null +++ b/.changeset/cip139-query-layer.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/cip139": minor +--- + +New package: the CIP-139 Universal Query Layer — the read surface that turns an own-data wallet into a full-data one. + +CIP-30 serves the user's own addresses and UTxOs, which leaves a dApp with two sources of truth, its own query layer and the wallet's. When they disagree the wallet may refuse to sign a transaction spending a UTxO it has not seen. CIP-139 lets the wallet answer for arbitrary chain data instead. + +Method names are the operation names from `cip-0144.md` verbatim (`cip139_getUtxosByAddress`), so a JSON-RPC transport can use them unmodified rather than maintaining a mapping that drifts from the spec. + +It is built over the provider port and `@evolution-sdk/review`'s decode seam, so the same query layer works against any backend that implements the port — and a read the backend cannot answer surfaces as an absence rather than as an empty result presented as fact. diff --git a/.changeset/cip21-multiasset-canonical-order.md b/.changeset/cip21-multiasset-canonical-order.md new file mode 100644 index 00000000..099b39fe --- /dev/null +++ b/.changeset/cip21-multiasset-canonical-order.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`multiasset` and `mint` maps are written in CIP-21 canonical key order. + +CIP-21 (Category: Wallets, Status: Active) requires canonical CBOR map-key order in the transaction body: shorter keys first, then lexicographic. It matters because a hardware wallet hashes the body in chunks and the client has to reconstruct those exact bytes. An insertion-ordered multiasset is accepted by a node and cannot be reliably signed by a device; for a mint it is also a transaction-id divergence, because the mint field lives in the body. + +The sort is applied **by the encoder that owns the map** — `MultiAsset.FromCDDL` and `Mint.FromCDDL` — and deliberately not through a global codec option, because the same option would also reorder Plutus map keys, which must keep the order they were given. This is narrower than the default-encode-path sorting in the closed #584: nothing outside these two maps changes order. + +⚠️ CML 6.2.0 is not an oracle here — it writes multiasset keys in insertion order, so it reproduces whatever order it was handed. The expected bytes in `Cip21CanonicalOrder.test.ts` come from cardano-serialization-lib 15.0.3, which sorts. diff --git a/.changeset/cip30-read-surface.md b/.changeset/cip30-read-surface.md new file mode 100644 index 00000000..7a3c45fc --- /dev/null +++ b/.changeset/cip30-read-surface.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/cip30": minor +--- + +New package: the CIP-30 wallet read surface over a provider and an account, returning the exact wire encodings — plus CIP-95 governance keys, CIP-103, CIP-104 and CIP-142. + +The scope is deliberately the **read** surface. It does not carry `signTx` / `signTxs` / `signData`: a signing method reachable straight off a connector is a footgun for anyone embedding it, and this package owns byte-exactness, not authorization. A wallet answers signing requests with a sentinel its host catches and then runs its own review and key-custody ceremony. The signing *encodings* live in `ReferenceSigning`, separate and labelled unsafe, so they can be tested without being reachable by accident. + +`getAccountPublicKey` is consent-gated. It reveals every address a wallet has used and its whole history, and CIP-30 treats it as a transparent read, so nothing else in a wallet's flow would prompt for it. The method *requires* a `ConsentTag`, which makes it type-level impossible to serve without the embedding app's approval implementation. + +The returned shapes are the wire's, not a convenience: `getChangeAddress` answers raw address bytes as hex rather than bech32, and `getUtxos` / `getBalance` answer `TransactionUnspentOutput` and `Value` hex, because a dApp compares those strings against what it built. diff --git a/.changeset/cips-companions.md b/.changeset/cips-companions.md new file mode 100644 index 00000000..c2e234a2 --- /dev/null +++ b/.changeset/cips-companions.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/cips": minor +--- + +New package: thirteen small CIP companions, built on the core types rather than beside them. + +`Cip4` (wallet checksum), `Cip14` (the `asset1…` fingerprint), `Uri` (the `web+cardano:` scheme, CIP-13 plus 134 and 162), `Cip27` (royalty metadata), `Cip16` (key serialisation layouts and their CIP-5 prefixes), `Cip67` (the asset-name label registry), `Cip68` (datum metadata), `Cip88` (token policy registration, signed by the policy key), `GovMeta` (the off-chain governance document an anchor points at, CIP-100/108/119/136), `Cip102` (royalty datum), `Cip105` (Conway DRep / CC-cold / CC-hot key chains), `Cip129` (governance identifiers) and `Cip1855` (forging policy keys). The three CIPs still **proposed** say so in the module and in the README. + +Each is driven by an oracle outside this library, not by its own output: `Cip4` against the `@emurgo/cip4-js` reference implementation, `Cip27` and `Cip88` against cardano-multiplatform-lib 6.2 for the metadata bytes and the policy-key signature, and `GovMeta` against coreutils `b2sum -l 256` for the anchor hash. `Cip4` also documents its one divergence from the reference: this strips a `0x` prefix and the reference does not, so the same key yields two different plates. + +The CIP-13 grammar for the URI amount and delegation fields is `*digit [ "." *digit ]`, which `""` and `"."` satisfy. `web+cardano:addr1…?amount=` parsed to `{ amount: "" }` and `?amount=.` to `{ amount: "." }`; a consumer reading either gets `NaN`, and an empty amount is not the same fact as no amount at all. Both are a `UriError` now, and the digit forms the grammar allows (`10`, `0.5`, `1.`, `.5`) still parse. diff --git a/.changeset/coin-selection-random-improve.md b/.changeset/coin-selection-random-improve.md new file mode 100644 index 00000000..c668a5c9 --- /dev/null +++ b/.changeset/coin-selection-random-improve.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`randomImproveSelection` is implemented. It was declared and never defined. + +`CoinSelection` exported `randomImproveSelection` and `optimalSelection` as `export declare const`, so both were `undefined` at runtime, and `phases/Selection.ts` refused the matching algorithm names with "not yet implemented". A caller who set `coinSelectionAlgorithm: "random-improve"` got an error, and one who imported `randomImproveSelection` directly got `undefined`. + +Random-improve is now a faithful port of CSL's `cip2_random_improve_by`: phase 1 selects at random until the target is covered, phase 2 swaps a chosen input for a remaining one when that moves the per-input contribution closer to twice the target without exceeding three times it. It is asset-aware — a target naming native assets covers each asset before the coin, then tops up for fees — and `largestFirstSelection` gains the same multi-asset path through the shared core. + +Randomness defaults to `crypto.getRandomValues` and **throws rather than falling back** to a predictable PRNG when WebCrypto is absent, because an observer being unable to predict which UTxOs a wallet combines is the entire point of the strategy. `randomImproveSelectionWith({ seed })` exists for tests and examples; the deterministic strategies never construct an RNG at all, so largest-first keeps working where no WebCrypto exists. + +`optimalSelection` and the `"optimal"` member of `CoinSelectionAlgorithm` are removed. Neither was implemented, and a declared export that is `undefined` at runtime fails later and less clearly than a name that does not resolve. diff --git a/.changeset/cose-header-map-and-sign-data.md b/.changeset/cose-header-map-and-sign-data.md new file mode 100644 index 00000000..0ba31cd2 --- /dev/null +++ b/.changeset/cose-header-map-and-sign-data.md @@ -0,0 +1,14 @@ +--- +"@evolution-sdk/evolution": minor +--- + +The COSE header map is keyed structurally, and CIP-8 sign-data gets the surface a wallet and a device need. + +`HeaderMap` holds a `Map` keyed by the Label **object**, and every `labelFromInt(n)` / `labelFromText(s)` call builds a fresh one — so both accessors answered by identity, which no caller can satisfy: `getHeader` never found a label that was present, and `setHeader` appended rather than replaced, leaving a COSE header map with a duplicate key whose two values both encode and whose reader takes whichever it reaches first. + +On top of that: + +- `SignData.signData` and `assembleSignData` produce a CIP-8 `COSESign1` — assembling separately from signing is what a hardware wallet needs, because the device returns a signature over bytes the caller must then frame. +- `SignData.verifyMessage` verifies one, and `SignData.addressSignerCredential` reports which credential a protected `address` header claims, or `undefined` when it claims none. A verifier that checks the signature alone accepts a perfectly valid signature over an address the key has nothing to do with; CIP-8's first check is what makes that false, and it needs the claimed credential to run. +- `COSEKey.publicKey` reads the verification key out of a `COSE_Key`, which is what a verifier is handed in the CIP-30 flow. +- The `kid` (label 4) carries the signing public key through the protected headers. It is optional in CIP-8 and CIP-30 wallets differ, so a verifier holding only the signed message needs it present when the signer chose to include it, and must not depend on it when they did not. diff --git a/.changeset/dijkstra-prefork-fields.md b/.changeset/dijkstra-prefork-fields.md new file mode 100644 index 00000000..3e07905c --- /dev/null +++ b/.changeset/dijkstra-prefork-fields.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/dijkstra": minor +--- + +New package: typed reads of the Dijkstra (pv12) pre-fork `transaction_body` keys, plus the `script_require_guard` native-script variant. + +⚠️ **Pre-fork.** It is grounded against the draft ledger CDDL only — no library ships Dijkstra, and the draft has already moved once: field 27 was added, and 26 was re-keyed from a credential to a reward account and gained a third, bare-`coin` arm. Every shape needs re-verifying before it is relied on against a live chain, and the package says so in its README and module docs. + +What it reads: `guards` (14, which replaces `required_signers` and is a key-hash set **or** a credential oset), `sub_transactions` (23, as raw sub-transaction CBOR), `required_top_level_guards` (24), `direct_deposits` (25), `account_balance_intervals` (26) and `starting_account_balance_intervals` (27). + +The byte layer already survives these: an unrecognised body key is preserved verbatim, so a Dijkstra transaction passes through a Conway-era codec untouched. What was missing is a *reading* of them, which is what a review surface and an analyzer need in order to say what such a transaction does rather than showing a reviewer an opaque key. diff --git a/.changeset/exact-conway-fee-math.md b/.changeset/exact-conway-fee-math.md new file mode 100644 index 00000000..0e6f556b --- /dev/null +++ b/.changeset/exact-conway-fee-math.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +The Conway fee components are computed in exact rational arithmetic, and the execution fee is charged the way the ledger charges it. + +`NonnegativeInterval.fromDecimal` is the new constructor behind it: a protocol parameter that is a rational in the ledger arrives as a decimal over JSON, and `0.0577`, `0.0000721` and `1.2` are none of them representable in binary floating point. It reads a `number` through its shortest round-tripping decimal, so `1.2` becomes six fifths rather than the dyadic expansion of the nearest double, and `0.0577` becomes `577/10000`. `NonnegativeInterval.ceilDiv` comes with it. + +**`tierRefScriptFee` keeps its signature and its rounding, and loses the doubles.** From the third tier on, the per-byte price stops being an integer (44 × 1.2 × 1.2 = 63.36), and a `number` accumulation drifts off the exact rational. At the cost-per-byte this module falls back to when the protocol parameter is absent — 44 — the drift put the fee **one lovelace below** the exact figure at 51 of the 204,800 permitted sizes, and below a fee minimum is a rejected transaction. Reproduced at `totalSize = 102_525` (6,057,920 exact against 6,057,919) and pinned as a test vector, along with two more at other cost-per-byte values. The single `floor` of the accumulated total is unchanged — that is what the ledger does, and the existing vectors still hold. + +**The script-execution fee is now one ceiling over the transaction's total execution units**, which is what the ledger's `txscriptfee` computes. It was a ceiling applied to each price term of each redeemer separately, in floating point: for a three-redeemer transaction that came out four lovelace above the ledger's figure — money a caller pays for rounding the chain never asked for. `scriptExecutionFee` is exported for callers that need the component on its own. diff --git a/.changeset/hardware-cardano-sign-requests.md b/.changeset/hardware-cardano-sign-requests.md new file mode 100644 index 00000000..76e5c0a0 --- /dev/null +++ b/.changeset/hardware-cardano-sign-requests.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/hardware-cardano": minor +--- + +New package: build a Ledger or Trezor Cardano sign request from a reviewed transaction body. + +It takes `@evolution-sdk/review`'s `Inspect.TxBodyView` and produces the parameter shape each device expects. No vendor SDK, no transport, no WebUSB/HID environment — the request is data, and this package only builds it, so it can be tested without a device attached. + +**Anything unrepresentable is refused, by name.** The device recomputes the body hash from the request it is handed, so a converter that silently dropped a field it could not represent would obtain a signature over a different transaction than the one the user approved. Refused: a body-map key the review tier cannot name, and proposal procedures, on both devices; voting procedures, treasury and donation fields, Byron outputs and governance certificates beyond vote delegation, on Trezor; pool, combined staking-plus-governance, and deprecated certificates, on Ledger. + +Whether the input set arrived `#6.258` or bare travels into the request for the same reason: it changes the bytes the device re-emits, and therefore the hash. diff --git a/.changeset/hex-boundary-brands.md b/.changeset/hex-boundary-brands.md new file mode 100644 index 00000000..a5f6079c --- /dev/null +++ b/.changeset/hex-boundary-brands.md @@ -0,0 +1,19 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`TransactionHash`, `Bip32PublicKey` and `Bip32PrivateKey` carry a branded, validated hex type, and `toHex` returns it. + +The hex boundary discarded what a value was. `BytesFromHex` is `Schema.Uint8ArrayFromHex` plus a length filter, so `TransactionHash.toHex()` handed back a bare `string` and from that point a transaction hash, a datum hash and a key were interchangeable — the type system had nothing left to object to. + +Each of the three now exports a `Hex` schema built the way `PaymentAddress`, `RewardAddress` and `DnsName` already are: `Schema.String` with a pattern, branded. `toHex` returns it, so the kind survives leaving the typed domain, and `Hex.make` *checks* the claim rather than asserting it. + +The extended key pair is the reason this is worth doing beyond tidiness. A 64-byte extended public key and a 96-byte extended private key are both "hex", and confusing them is unrecoverable in one direction: publishing where a private key was expected is merely wrong, while signing with what you believed was public is a leaked key. They now have different brands and different lengths, so the swap is refused twice over. + +Additive: `fromHex` still accepts a plain `string`, so no caller has to change. + +The same treatment now covers `KeyHash`, `PolicyId`, `AssetName`, `DatumHash`, `ScriptDataHash`, `AuxiliaryDataHash`, `VKey`, `Ed25519Signature`, `Address` (hex *and* bech32, branded apart from each other), and the CBOR-hex forms of `Value`, `Script` and `Data`. + +Two of these exist for a specific confusion rather than for symmetry. `VKey.Hex` is the 32-byte verification key, not the 64-byte extended form a verifier would fail on. `Ed25519Signature.Hex` is branded apart from it because a `vkeywitness` holds exactly those two in that order, and transposing them yields a witness that is structurally valid and verifies against nothing. `AssetName.Hex` admits the empty string deliberately: a policy's unnamed asset is spelled exactly that way. + +The *shaped* brands — hashes, keys, addresses — validate on construction. The *opaque* ones (`Value`, `Script`, `Data` CBOR hex) stay casts: the only check available for arbitrary-length CBOR is "even number of hex digits", which rejects almost nothing real while breaking test doubles that carry a readable stand-in rather than a genuine encoding. diff --git a/.changeset/koios-chain-parameters-over-the-wire.md b/.changeset/koios-chain-parameters-over-the-wire.md new file mode 100644 index 00000000..c31e5402 --- /dev/null +++ b/.changeset/koios-chain-parameters-over-the-wire.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/evolution": patch +--- + +`getChainParameters` works against a live Koios, and a Koios failure says what went wrong. + +Three defects, found by driving the provider against preprod rather than against a stubbed `fetch`: + +**The integer fields arrive as strings.** `HttpUtils` parses every response with a reviver that hands each number to the schema as the exact text the server wrote, so a `uint64` amount survives at any size. The chain-parameter mapping read them with a helper that insisted on `typeof value === "number"` — so it rejected every populated document and accepted only hand-built fixtures that never went through the reviver. `committeeMinSize` is `"3"` on the wire and `3` in a test, and the test was the only thing that ever matched the code. The mapping is now covered by a test driven through `HttpUtils` against a **real preprod `/cli_protocol_params` document**, so the wire shape is what the assertion sees. + +**The rationals arrive in exponent notation, and reading them back through `toFixed` re-introduced the error exactness exists to remove.** Koios serves `priceMemory` as `5.77e-2` and `monetaryExpansion` as `3.0e-3`; `(7.21e-5).toFixed(20)` is `"0.00000007210000000000"`-adjacent only in the lucky cases — for `1e-7` it is `"0.00000009999999999999"`, a twenty-digit fraction whose denominator (5e19) does not even fit a `uint64`. The decode failed outright on the document the endpoint actually serves. There is now one implementation of decimal → exact rational, `NonnegativeInterval.fromDecimal`, which expands the exponent from the text; this module delegates to it. + +**A failure named the operation and dropped the reason.** `Koios getChainParameters failed` was the whole message, with the cause only in a field that re-wrapping layers discard. The cause is now in the message too, because that is what survives being wrapped. diff --git a/.changeset/koios-credential-utxos-hex-and-batching.md b/.changeset/koios-credential-utxos-hex-and-batching.md new file mode 100644 index 00000000..6a1cf659 --- /dev/null +++ b/.changeset/koios-credential-utxos-hex-and-batching.md @@ -0,0 +1,9 @@ +--- +"@evolution-sdk/evolution": patch +--- + +`getUtxosByPaymentCredential(s)` sends the credential as hex, and splits a long list by body size. + +A `Credential`'s `hash` is a `Uint8Array`, and the request body was built from it directly — so `JSON.stringify` wrote `{"0":170,"1":170,…}` where Koios expects `"aaaa…"`. The query could not have worked for any real credential. The tests that covered it built their credentials by hand as `{_tag: "KeyHash", hash} as never`, which put a *string* in the fixture: the only thing that ever matched the code was the test. + +Koios also refuses a request body over 5120 bytes with a 413, and a wallet asking about its whole signable set passes that at around 90 credentials — measured, 664 of them come to 39,219 bytes in one body. The list is now chunked by serialized length, in order, the way the DRep and pool id lists already were. diff --git a/.changeset/koios-history-tier-behaviours.md b/.changeset/koios-history-tier-behaviours.md new file mode 100644 index 00000000..207a62d0 --- /dev/null +++ b/.changeset/koios-history-tier-behaviours.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/evolution": minor +--- + +Four measured behaviours in the Koios history tier, each of which a wallet hits on its first real account. + +**`getAddressesSeen` batches by serialized bytes.** Koios refuses a request body over 5120 bytes with a 413 — measured: 48 mainnet base addresses come to 5104 and are served, 50 come to 5316 and are not. A gap-limit scan asks about more addresses than that in one call, so the single body failed at exactly the sizes this member exists for. It also asks `?select=address` now, which drops `utxo_set` from the response: the row wanted here is the address string alone, and the rest was the whole cost of the call. + +**`getAccountTxs` can bound a window from above, and can order ascending.** `beforeBlock` is a PostgREST column filter rather than an RPC argument, and without it every window returns the newest rows above `afterBlock`, so a downward walk through an account's history never descends. `order: 'asc'` with `limit: 1` finds the account's oldest transaction in one call, rather than by descending into empty history to discover it is empty. + +**`getAccountUtxos` takes `offset` and `limit`.** They bound the answer, not the work: spent rows are dropped after the walk, so a window asked of the backend would over- or under-fill. + +**`getAccountAddresses` answers what it promises for a spent-down account.** Without Koios's `_empty` flag the endpoint reports only where a UTxO currently sits, so a registered, delegated account spent to zero enumerated to nothing — contradicting the member's own contract. With the flag, a real mainnet key holding value at four addresses and having derived ~490,000 answers 51,465,168 bytes (843 without), and `offset` cannot bound it because the addresses are nested inside one row per stake key. So the cheap question is asked first and the full enumeration is paid for only when it answers nothing. ⚠️ For a funded account the result is therefore the addresses holding value, not every address ever used; the member's documentation now says so, and points a caller tracking activity at the stake-keyed `getAccountUtxos` / `getAccountTxs` instead. The flat `{stake_address, address}` row shape some deployments answer with is now accepted alongside the nested one. diff --git a/.changeset/koios-multi-id-bodies.md b/.changeset/koios-multi-id-bodies.md new file mode 100644 index 00000000..efb13401 --- /dev/null +++ b/.changeset/koios-multi-id-bodies.md @@ -0,0 +1,14 @@ +--- +"@evolution-sdk/evolution": minor +--- + +The three remaining multi-id Koios bodies respect the 5120-byte limit — two by splitting, one by splitting and saying what it will not pretend to do. + +`getTxInfo` and `getTxCbor` are chunked by serialized length. A transaction hash is 64 characters, so the limit arrives at about seventy-six of them, and a history hydrate asks about more. Their answers are keyed by hash and carry no order, so the chunks concatenate with nothing to reconcile. + +`getTxsAt` is the interesting one, and two measurements decided its shape. A single multi-address request returns a transaction that touches two of the requested addresses **once**, so a split request must dedupe by hash or a split answer differs from an unsplit one by exactly the transactions that involve the wallet twice. And each chunk is newest-first only within itself, so the pages must be merged by block height — with a `limit`, concatenating returns the wrong rows rather than the right rows in the wrong order. Ties break on the transaction hash, which makes the merged order a function of chain state alone: without it the order follows the caller's address order, and a caller comparing "the newest transaction" against the last one it saw would watch it change while the chain did not. + +Two requests it refuses instead of answering wrongly, both before spending a request: + +- **an `offset` across a split.** A global window over several address streams is only knowable by reading the first `offset + limit` rows of every chunk, which makes a walk that steps the offset quadratic — and re-interpreting the offset per chunk would answer a different question than the caller asked. A caller paging deeply should split the addresses and page each stream, which is what a history walk wants anyway. One request's worth of addresses still honours every option exactly as before. +- **a `limit` above `MAX_ROWS_PER_RESPONSE` (1000).** Measured: `/address_txs` answers 1000 rows for `limit=1001` and for `limit=1500` alike, so the ceiling cannot be exceeded per chunk and the merge's correctness argument stops holding at the point the answer would be wrong. `getAccountTxs` refuses the same thing for the same reason: a truncated answer reads exactly like a complete one. diff --git a/.changeset/koios-request-timeout-option.md b/.changeset/koios-request-timeout-option.md new file mode 100644 index 00000000..2effbad9 --- /dev/null +++ b/.changeset/koios-request-timeout-option.md @@ -0,0 +1,19 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A Koios client's per-request timeout is a caller's choice, it is applied PER REQUEST rather than per operation, and the query tier has one at all for the first time. + +`new Koios(baseUrl, token, { requestTimeoutMs })` sets the ceiling every read on that client races each of its requests against. `DEFAULT_REQUEST_TIMEOUT_MS` is exported from the provider module so a caller raising it can name what it is raising it from. + +**Two defects this fixes, neither of them the configurability.** + +⚠️ **The ceiling was around the operation, so it bounded a paged walk.** `getUtxos` over a *credential* reads `/credential_utxos`, which pages: a credential holding three pages of UTxOs spent one 10-second budget across three requests and was refused for being **large** rather than slow. The timeout now sits at the HTTP boundary, inside `pageAll`'s page function, so every page gets the full ceiling and a long walk is not cut off for being long. + +⚠️ **The query tier had no timeout whatsoever.** The eleven `KoiosEffect` reads carried 10 s; the twenty-seven `KoiosQuery` reads — `getAccountUtxos`, `getUtxosByPaymentCredential(s)`, `getAccountTxs`, `getTxsAt`, `getTxInfo`, `getTxCbor`, the governance and pool reads — carried none, so they could hang on a stalled connection indefinitely. They are bounded now, which is a **behaviour change**: a read that previously waited forever fails as a `ProviderError` after the ceiling. For a wallet that is the better default — an unbounded read on a slow link is a sync that never finishes and never fails — but it is a new way for those reads to fail, and a consumer that relied on unbounded waits should set `requestTimeoutMs` high. + +Ten seconds was written against a desktop on a fixed link. `/address_info` for a busy address measured 764 KB, which needs ~76 KB/s sustained to finish inside the window. + +`awaitTx` now takes **both**: `timeoutMs` bounds each poll's request, its existing `timeout` argument bounds the whole wait across polls. They are not interchangeable — folding one into the other would either cap a confirmation wait at a single request's worth, reporting an unconfirmed transaction as a provider failure, or leave each poll able to hang for the entire wait. + +`HttpUtils`'s new `timeoutMs` parameter is **optional with no default**, deliberately: that module is shared by Blockfrost, Maestro, Kupmios and Ogmios, and a default there would silently put a ceiling on four providers that never asked for one. Each opts in by threading its own value down; only Koios does today. diff --git a/.changeset/koios-token-source.md b/.changeset/koios-token-source.md new file mode 100644 index 00000000..9c3043bd --- /dev/null +++ b/.changeset/koios-token-source.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`Koios` accepts a bearer token **or a function returning one**. + +`new Koios(url, token)` captured the token once at construction, so a credential refreshed or re-issued while the provider lived was never picked up — the only remedy was to rebuild the provider, which a long-lived consumer has no natural moment to do. + +`token` is now `string | (() => string | undefined)`. A function is resolved at each request; a plain string behaves exactly as before. The resolution happens where the header is built, so no call path changed: `TokenSource`, `resolveToken` and `authHeader` are exported from the Koios internals and the inline `Authorization` ternaries now route through the one helper. + +A getter that currently returns `undefined` sends no `Authorization` header at all, rather than `Bearer undefined`. diff --git a/.changeset/native-scripts-json.md b/.changeset/native-scripts-json.md new file mode 100644 index 00000000..4fe29dbb --- /dev/null +++ b/.changeset/native-scripts-json.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`NativeScripts.fromJSON` converts the cardano-cli JSON form back into a native script, and `NativeScripts.toJSON` no longer truncates a slot the JSON form cannot carry. + +`toJSON` was declared `any` and converted `slot` and `required` with `Number(bigint)`. The cardano-cli form writes both as JSON numbers, so a CDDL uint64 above `Number.MAX_SAFE_INTEGER` came back as a different value with no error: `InvalidBefore(2n ** 53n)` and `InvalidBefore(2n ** 53n + 1n)` both produced `{ type: "after", slot: 9007199254740992 }`. A native script decoded from the chain may legitimately carry any uint64, so this was reachable on read and not only on authoring. `toJSON` now returns `NativeScriptJSON.NativeJSON` and throws for a value the form cannot represent exactly, rather than returning one that looks ordinary. + +`fromJSON` is the inverse, and the direction the library did not have. Every node is built through the smart constructors, so `keyHash` is validated as a 28-byte hash instead of being taken on trust. The JSON form's slot names are the opposite way round from the CDDL's — `before` is `InvalidHereafter` and `after` is `InvalidBefore` — and `fromJSON` follows the JSON form. + +`NativeScript[Hash.symbol]` no longer routes through `toJSON`. It hashed `JSON.stringify(toJSON(script))`, which inherited the truncation: the two scripts above hashed equal. With `toJSON` strict it would instead have thrown from inside a `HashSet`. It now hashes the variant itself with bigints stringified, so the hash number of every native script changes; `Equal` is implemented separately on the variant and decides membership, so this changes bucketing only. diff --git a/.changeset/no-credential-on-a-cleartext-wire.md b/.changeset/no-credential-on-a-cleartext-wire.md new file mode 100644 index 00000000..68f1e106 --- /dev/null +++ b/.changeset/no-credential-on-a-cleartext-wire.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A provider request carrying a credential is refused when the endpoint is plain http. + +A bearer token, a Blockfrost `project_id` and a Maestro `api-key` are all readable by every hop they cross on an unencrypted connection, and each one is a user's paid tier — or, in a wallet, an identity. The endpoint being misconfigured is not a reason to put it on the wire. + +The check lives in the one place that sees both the url and the headers, so it covers every HTTP-backed provider rather than being re-implemented per backend. The request is never issued, so it fails as an `HttpRequestError`, in the error channel. The message names the header, never its value. + +⚠️ **Behaviour change.** A provider configured against `http://` with a token now fails instead of sending it. Loopback (`localhost`, `127.0.0.1`, `[::1]`) is exempt, because there is no wire to intercept — a local devnet or a tunnelled indexer keeps working. A LAN address or a plain hostname is not exempt: an indexer one hop away on a shared network is exactly where a token is captured. A provider with no credential is unaffected over any scheme. diff --git a/.changeset/plan-engine.md b/.changeset/plan-engine.md new file mode 100644 index 00000000..598f0e06 --- /dev/null +++ b/.changeset/plan-engine.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/plan": minor +--- + +New package: wallet-side transaction planning — a plan says what a transaction should do, and the engine converges fee, change and collateral until it balances. + +`Plan.buildUnsigned` takes a plan and returns the body bytes, the inputs it chose, the change it emitted and a `FeeBreakdown`. It reaches no network and holds no key, and it encodes through `@evolution-sdk/evolution` directly rather than through a seam of its own. + +`ExUnits` is where a redeemer's execution units come from, as a swappable service with three backends: supplied by the caller (cached or measured), taken from a preset table with a margin (no network, no VM — the only option where WASM cannot run), or evaluated by a provider. Declared ex-units are not in the script context, so a build → evaluate → rebuild loop is stable; the only question is what backs the numbers. + +⚠️ Outputs are built with `encodingFormat: "babbage"`. Conway accepts both the Shelley array and the Babbage map, a node takes either, and they are **different bytes** — a different transaction id, a different min-ada, and a different body for a hardware wallet to reconstruct. The engine says which one it means rather than inheriting a default that varies with whether an inline datum happens to be present. diff --git a/.changeset/plan-fee-math-one-implementation.md b/.changeset/plan-fee-math-one-implementation.md new file mode 100644 index 00000000..6da7f4f2 --- /dev/null +++ b/.changeset/plan-fee-math-one-implementation.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/evolution": minor +--- + +The Conway fee components live here as `Fees`, in one implementation, computed in exact rational arithmetic. + +The plan engine carried its own `scriptExecutionFee` and `refScriptFee` — exact rational arithmetic, independently written, against a builder that computed the same two numbers in floating point. Holding them against each other decided which half of each survived rather than which file did: + +- the **execution fee** takes the plan engine's shape, one ceiling over the transaction's total execution units, because that is what the ledger's `txscriptfee` computes. The per-redeemer, per-term ceilings here came out four lovelace high on three redeemers. +- the **reference-script fee** keeps this package's rounding, a single `floor` of the accumulated total, because that is what the ledger's `tierRefScriptFee` does — the plan engine rounded up, which is one lovelace above the node's figure wherever a tier price stops being an integer. It also keeps this package's bound: the real Conway `maxRefScriptSizePerTx` of 204,800 bytes, in place of the plan engine's 64-tier (1.6 MB) guess, now enforced in the fee function itself rather than only in one caller. +- the arithmetic is exact on both, which was the plan engine's contribution: double accumulation here landed a lovelace *below* the exact figure at 51 of the 204,800 permitted sizes. + +`ceilDiv` lives on `NonnegativeInterval`, where the other exact-rational helpers are. diff --git a/.changeset/plutus-data-splicing-and-schema.md b/.changeset/plutus-data-splicing-and-schema.md new file mode 100644 index 00000000..9ad0c581 --- /dev/null +++ b/.changeset/plutus-data-splicing-and-schema.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A `Data` can be spliced from children that are already encoded, and it has a schema that does not copy it. + +`Data.spliceList`, `spliceConstr` and `spliceMap` assemble a parent from children whose bytes a caller already holds. That is what keeps a datum hash stable across a layer that only reframes a parent: re-encoding the children would recompute their bytes, and any framing difference in a child changes the hash of everything above it. + +`Data.DataValue` is a `Schema.declare` over the variant, with `Data.isData` beside it. A `Schema.Class` validation **copies** the value, and a copy is a different object identity — which silently breaks a `WeakMap` keyed on the decoded value, the mechanism that carries a decoded node's arrival bytes. Declaring the schema validates in place instead. + +`plutusDataToCBORValue` takes `CodecOptions` and `cborValueToPlutusData` takes a `CBORFormat`, so a caller that decoded with one set of options can re-encode under the same ones. `InlineDatum.fromCBORHex` / `fromCBORBytes` are the inverse of its existing encoders, which the module did not have. diff --git a/.changeset/provider-gettip-optional.md b/.changeset/provider-gettip-optional.md new file mode 100644 index 00000000..5ba22255 --- /dev/null +++ b/.changeset/provider-gettip-optional.md @@ -0,0 +1,9 @@ +--- +"@evolution-sdk/evolution": patch +--- + +`Provider.getTip` and `ProviderEffect.getTip` are optional. + +Every provider in this package implements `getTip`, and the five shipped classes type their own `effect` field as the new `ProviderEffectWithTip` so they still call it directly. The interface is implemented outside this repository too, and a required member retires those implementations at a minor version — the reads added alongside `getTip` are all optional for the same reason. + +A caller that needs the tip should check for it and report the absence, rather than the type system promising something a third-party backend never agreed to. diff --git a/.changeset/provider-history-tier.md b/.changeset/provider-history-tier.md new file mode 100644 index 00000000..22936742 --- /dev/null +++ b/.changeset/provider-history-tier.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`ProviderEffect` gains the history and discovery tier: `getTxsAt`, `getAccountTxs`, `getAccountAddresses`, `getAddressesSeen`, `getTxInfo`, `getTxCbor`, `getScriptByHash`, `getUtxosByPaymentCredential` and `getUtxosByPaymentCredentials`. + +A transaction builder never asks these; a wallet or an explorer cannot work without them. What has happened to these addresses, which addresses a stake account has ever used (including ones it has emptied, which UTxOs alone cannot tell you), whether the chain has seen an address at all, and the bytes of a transaction rather than an indexer's reading of them. + +All nine are optional, so an implementation that cannot answer omits the member and a caller can say "history unavailable" instead of showing an empty list as a fact. Koios implements all of them. `getScriptByHash` returns `undefined` for a hash the chain has not seen — a different answer from a failed lookup — and refuses to report a Plutus version it does not recognise rather than defaulting to V1, because the version decides how the bytes are run. + +`IndexedTxRef`, `IndexedTx`, `IndexedTxIO`, `IndexedTxCert` and `IndexedTxCbor` are the result types. `IndexedTx` is documented as the indexer's reading of a transaction rather than the transaction: it cannot be re-encoded to the bytes that were signed, and `IndexedTxCbor` is what to use when the bytes matter. diff --git a/.changeset/provider-tx-confirmations.md b/.changeset/provider-tx-confirmations.md new file mode 100644 index 00000000..a8616757 --- /dev/null +++ b/.changeset/provider-tx-confirmations.md @@ -0,0 +1,9 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`ProviderEffect` gains `getTxConfirmations`: how many blocks deep the chain considers a transaction, or `null` when it has not seen it. + +`awaitTx` answers presence, which is a weaker question than the one a wallet has to ask. Cardano's finality is probabilistic, so a one-deep transaction can still be rolled back, and a flow that must not act twice on the same funds needs depth rather than inclusion. Answering a request for depth with an inclusion fact is the dangerous kind of wrong. + +The block containing a transaction counts as the first confirmation, so a freshly included transaction answers `1`. An unseen one answers `null` rather than `0`: zero deep is not a state a transaction on chain is ever in, and conflating the two would make "never submitted" and "just included" the same answer. Optional, like the rest of the tier — Koios implements it from `/tx_status`; a backend that cannot report depth omits it, so a caller can say the count is unavailable instead of inventing one. diff --git a/.changeset/request-report-refusal-body.md b/.changeset/request-report-refusal-body.md new file mode 100644 index 00000000..12a7204c --- /dev/null +++ b/.changeset/request-report-refusal-body.md @@ -0,0 +1,9 @@ +--- +"@evolution-sdk/evolution": minor +--- + +`RequestBudget.RequestReport` carries the refusal's body. + +A status is not an identification. Koios answers `429` both for one credential over its own window, whose body reads `Exceeded Burst Limit, count was N`, and for an instance shedding load by source IP, whose body is an HAProxy page. A report that names only the status cannot tell a caller which of those happened, so it cannot say whether to slow down or to try another endpoint. + +`refusalBody` is present only for a non-2xx response, and it is read from a clone of the response, so the caller still receives an unread body to fail with. A body that cannot be read leaves the field **absent** rather than reporting an empty string the server never sent. diff --git a/.changeset/review-before-sign.md b/.changeset/review-before-sign.md new file mode 100644 index 00000000..a692a1e9 --- /dev/null +++ b/.changeset/review-before-sign.md @@ -0,0 +1,14 @@ +--- +"@evolution-sdk/review": minor +--- + +New package: a span-preserving review of a transaction — what it does, and whether the ledger would refuse it. + +A wallet showing a user what they are about to sign, a co-signer deciding whether to add a witness, and a hardware sign-request builder all need the transaction exactly as it arrived, decoded without anything quietly dropped. Decoding into a value tree and re-encoding loses two things a review surface cannot do without: + +- **The exact bytes.** `Inspect.txBodyFromTx` returns the body's original span rather than a re-encode. A span that differs by one byte is a different transaction id, so "close enough" does not exist here; the package pins this against a real preprod transaction's published id. +- **What the decoder did not recognise.** `Inspect.txBody` reports `unknownKeys` — body-map keys it does not model — and `inputsSetTagged`, whether the input set arrived `#6.258` or bare. Both are silently discarded by a decoder built to accept valid known shapes, and a body that shows a reviewer one thing and a downstream decoder another is what review-before-sign exists to prevent. A duplicate body key is rejected rather than resolved last-wins. + +`Analyze` says what the transaction does (certificates, mint, governance, scripts, redeemers) over a swappable `Decode` service; `Phase1` says whether the ledger would refuse the bytes, as far as provider data can prove it. + +`OriginalBytes` and this package are complements: `OriginalBytes` answers "write back exactly what I read" for a value you hold, `Inspect` answers "show me exactly what I am about to sign", including the parts the schema does not model. diff --git a/.changeset/set-tag-and-unknown-body-keys.md b/.changeset/set-tag-and-unknown-body-keys.md new file mode 100644 index 00000000..55c1ca2a --- /dev/null +++ b/.changeset/set-tag-and-unknown-body-keys.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +Two ways a transaction's id could change out from under a signer, both closed. + +**A bare input set stays bare.** Conway writes a transaction's input set as `#6.258([...])`; Babbage wrote a bare array and the ledger still accepts it. `TransactionBody` decoded both and encoded only the tagged form, so a body that arrived bare came back three bytes longer with a different transaction id — and in `addVKeyWitnesses` the signature was already attached to it. A wallet co-signing someone else's transaction does not get to choose the form it is handed. The format-preserving encoder now replays a `#6.258` wrapper exactly as it arrived: where the captured format says there was no tag at that position and the value carries one, the set is emitted bare. Scoped to tag 258 — the one tag whose presence is a matter of form rather than of meaning — so any other disagreement between a value and a format still resolves in favour of the value. + +**An unmodelled body key is refused instead of dropped.** The body's fields are read by key, so a key the decoder does not read was absent from the result and missing from the re-encode: measured, a body with one extra key went in at 1213 bytes and came out at 1209, a different transaction id, with nothing raised. This schema models the whole of Conway's `transaction_body` (0–5, 7–9, 11, 13–22), so an unmodelled key is either a pre-Conway field it cannot represent or a field from a newer era — and decoding now fails, naming the key. + +⚠️ Preserving such a key would not have been better: it would let a wallet sign a field it could not display, which is the thing a review step exists to prevent. Refusing is the forward-compatible behaviour that is also the safe one. diff --git a/.changeset/tag-102-definite-wrapper.md b/.changeset/tag-102-definite-wrapper.md new file mode 100644 index 00000000..20de4589 --- /dev/null +++ b/.changeset/tag-102-definite-wrapper.md @@ -0,0 +1,18 @@ +--- +"@evolution-sdk/evolution": patch +--- + +The tag-102 constructor wrapper is now written as a definite two-element array. + +`Data` encodes a constructor whose index is outside the compact ranges as `#6.102([index, fields])`. The wrapper array was written with indefinite-length framing, so `Constr(999999, [42])` encoded as `d8669f1a000f423f9f182affff`. The fields array inside it is indefinite, and the wrapper is not. + +Two independent implementations write the definite form, and disagree with each other about the fields framing while agreeing about the wrapper: + +- `cardano-serialization-lib` 15.0.3 writes `d866821a000f423f9f182aff` +- `cardano-multiplatform-lib` 6.2 writes `d866821a000f423f81182a` + +Both write `d866821a000f423f80` when there are no fields, which this library already matched. + +Framing is pinned on the node rather than taken from the codec options, because the wrapper is definite while the fields array one level in is indefinite, and a single option cannot say both. `CBOR.DefiniteArray` is the node, alongside the existing `CBOR.BoundedBytes`; it threads the decoded format to its items, so anything nested inside still replays the framing it arrived with. + +This changes the bytes of any transaction carrying a constructor with an index above 127, and therefore its datum hash and its transaction id. The golden corpora move for exactly those values. diff --git a/.changeset/transfer-refuses-to-drop-a-datum.md b/.changeset/transfer-refuses-to-drop-a-datum.md new file mode 100644 index 00000000..7a60ea67 --- /dev/null +++ b/.changeset/transfer-refuses-to-drop-a-datum.md @@ -0,0 +1,13 @@ +--- +"@evolution-sdk/cip113": minor +--- + +A transfer refuses an input carrying a non-void inline datum, rather than leaving it behind. + +A programmable output may carry an inline datum of any content within `max_inline_datum_bytes`, and the protocol names CIP-68 reference tokens as the legitimate large case. `buildTransferTx` writes only the datums a caller supplies, so it cannot overwrite one — but it could do the quieter version of the same damage: move such an input, emit the output with no datum, and the metadata is gone from the live UTxO set just as permanently. + +⚠️ This is a measured failure class, not a hypothetical. The reference SDK was asked to transfer a CIP-68 (100) reference token: it built the transaction, the **ledger accepted it**, and the output's datum came out as `d87980` where the metadata had been — leaving the reference NFT at an address its issuer no longer controlled. Nothing failed: not the build, not the evaluation, not the submission, not its suite. Two independent implementations have since added a guard; this is the third. + +Refusing rather than carrying the datum forward is deliberate: whether the on-chain transfer validator accepts a non-void datum on a programmable output is untested here, so a carry-forward would trade silent data loss for a submission failure nobody can read. The refusal is the part provable offline, and a caller who means to move metadata says so by supplying the output's datum explicitly. + +The void datum (`d87980`) and no datum at all both build as before. diff --git a/.changeset/txs-at-address-batches.md b/.changeset/txs-at-address-batches.md new file mode 100644 index 00000000..e40d1d1a --- /dev/null +++ b/.changeset/txs-at-address-batches.md @@ -0,0 +1,11 @@ +--- +"@evolution-sdk/evolution": minor +--- + +A provider that bounds its request body publishes the batches `getTxsAt` can serve. + +`getTxsAt` refuses an `offset` across a split body, and that is the only correct answer: the global rows `[offset, offset + limit)` over several address streams are knowable only by reading the first `offset + limit` of every one of them. But a caller that pages has to batch under the same budget, and the budget is the implementation's arithmetic — a count restated beside the caller is a count that drifts, because what fits at one address length splits at another. + +`ProviderEffect.splitAddressesForTxsAt` is that arithmetic, published. Optional, like the rest of the history tier, and **absent means unbounded**: the whole list is one batch, which is what a backend with no body limit should say. It is pure, because it is arithmetic over the serialized length and reaches nothing. Koios implements it with the chunker `getTxsAt` itself uses, so the batches it hands back are exactly the ones that go out as one request each — asserted both ways, including that the next address over the line is still refused. + +This is not hypothetical: a consuming wallet sized its batches from the 5120-byte limit Koios enforces rather than from the 4096-byte budget this client holds itself to, and every history window it walked was refused in a few milliseconds, before a request went out, with the stored list left standing. diff --git a/docs/content/docs/modules/Address.mdx b/docs/content/docs/modules/Address.mdx index ee546f39..cf2ac926 100644 --- a/docs/content/docs/modules/Address.mdx +++ b/docs/content/docs/modules/Address.mdx @@ -1,4 +1,5 @@ --- + title: Address.ts nav_order: 1 parent: Modules @@ -37,8 +38,14 @@ Added in v2.0.0 - [getStakingCredential](#getstakingcredential) - [hasStakingCredential](#hasstakingcredential) - [isEnterprise](#isenterprise) +- [model](#model-1) + - [Bech32 (type alias)](#bech32-type-alias) + - [Hex (type alias)](#hex-type-alias) - [predicates](#predicates) - [isScript](#isscript) +- [schemas](#schemas) + - [Bech32](#bech32) + - [Hex](#hex) - [utils](#utils-1) - [fromBytes](#frombytes-1) - [fromHex](#fromhex-1) @@ -336,6 +343,28 @@ export declare const isEnterprise: (address: Address) => boolean Added in v2.0.0 +# model + +## Bech32 (type alias) + +**Signature** + +```ts +export type Bech32 = typeof Bech32.Type +``` + +Added in v2.4.0 + +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + # predicates ## isScript @@ -350,6 +379,39 @@ export declare const isScript: (address: Address) => boolean Added in v2.0.0 +# schemas + +## Bech32 + +A bech32-encoded address, as a user sees it. + +⚠️ Branded apart from {@link Hex}: both are strings and they are not interchangeable. Handing +bech32 where raw hex belongs is a decode failure at best and a wrong address at worst. + +**Signature** + +```ts +export declare const Bech32: Schema.brand, "AddressBech32"> +``` + +Added in v2.4.0 + +## Hex + +An address as raw hex — NOT bech32. See {@link Bech32} for the human-facing form. + +Length is deliberately not pinned: an enterprise or reward address is 29 bytes, a base address +57, and a pointer address varies. What is checked is that it is non-empty whole bytes, and what +is branded is that it is an address rather than some other hex. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "AddressHex"> +``` + +Added in v2.4.0 + # utils ## fromBytes @@ -373,7 +435,7 @@ export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Add **Signature** ```ts -export declare const toBech32: (a: Address, overrideOptions?: ParseOptions) => string +export declare const toBech32: (value: Parameters[0]) => Bech32 ``` ## toBytes @@ -389,5 +451,5 @@ export declare const toBytes: (a: Address, overrideOptions?: ParseOptions) => Ui **Signature** ```ts -export declare const toHex: (a: Address, overrideOptions?: ParseOptions) => string +export declare const toHex: (value: Parameters[0]) => Hex ``` diff --git a/docs/content/docs/modules/AddressEras.mdx b/docs/content/docs/modules/AddressEras.mdx index 4999cd7a..6e77208c 100644 --- a/docs/content/docs/modules/AddressEras.mdx +++ b/docs/content/docs/modules/AddressEras.mdx @@ -1,4 +1,5 @@ --- + title: AddressEras.ts nav_order: 2 parent: Modules @@ -43,9 +44,9 @@ FastCheck arbitrary for Address instances. ```ts export declare const arbitrary: FastCheck.Arbitrary< | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress + | EnterpriseAddress.EnterpriseAddress + | BaseAddress.BaseAddress > ``` @@ -63,10 +64,10 @@ Convert an Address to Bech32 string. export declare const toBech32: ( a: | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, overrideOptions?: ParseOptions ) => string ``` @@ -83,10 +84,10 @@ Convert an Address to bytes. export declare const toBytes: ( a: | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, overrideOptions?: ParseOptions ) => any ``` @@ -103,10 +104,10 @@ Convert an Address to hex string. export declare const toHex: ( a: | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, overrideOptions?: ParseOptions ) => string ``` @@ -161,10 +162,10 @@ export declare const fromBech32: ( overrideOptions?: ParseOptions ) => | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress + | EnterpriseAddress.EnterpriseAddress | ByronAddress.ByronAddress + | BaseAddress.BaseAddress ``` Added in v2.0.0 @@ -181,10 +182,10 @@ export declare const fromBytes: ( overrideOptions?: ParseOptions ) => | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress + | EnterpriseAddress.EnterpriseAddress | ByronAddress.ByronAddress + | BaseAddress.BaseAddress ``` Added in v2.0.0 @@ -201,10 +202,10 @@ export declare const fromHex: ( overrideOptions?: ParseOptions ) => | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress + | EnterpriseAddress.EnterpriseAddress | ByronAddress.ByronAddress + | BaseAddress.BaseAddress ``` Added in v2.0.0 @@ -222,15 +223,15 @@ export declare const FromBech32: Schema.transformOrFail< typeof Schema.String, Schema.SchemaClass< | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, - | RewardAccount.RewardAccount - | BaseAddress.BaseAddress | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, + | RewardAccount.RewardAccount | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, never >, never @@ -250,15 +251,15 @@ export declare const FromBytes: Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, Schema.SchemaClass< | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, - | RewardAccount.RewardAccount - | BaseAddress.BaseAddress | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, + | RewardAccount.RewardAccount | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, never >, never @@ -280,15 +281,15 @@ export declare const FromHex: Schema.transform< typeof Schema.Uint8ArrayFromSelf, Schema.SchemaClass< | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, - | RewardAccount.RewardAccount - | BaseAddress.BaseAddress | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, + | RewardAccount.RewardAccount | PointerAddress.PointerAddress - | ByronAddress.ByronAddress, + | EnterpriseAddress.EnterpriseAddress + | ByronAddress.ByronAddress + | BaseAddress.BaseAddress, never >, never @@ -310,8 +311,8 @@ export declare const isAddress: ( overrideOptions?: ParseOptions | number ) => u is | RewardAccount.RewardAccount - | BaseAddress.BaseAddress - | EnterpriseAddress.EnterpriseAddress | PointerAddress.PointerAddress + | EnterpriseAddress.EnterpriseAddress | ByronAddress.ByronAddress + | BaseAddress.BaseAddress ``` diff --git a/docs/content/docs/modules/AddressTag.mdx b/docs/content/docs/modules/AddressTag.mdx index a0d86808..3a6612ba 100644 --- a/docs/content/docs/modules/AddressTag.mdx +++ b/docs/content/docs/modules/AddressTag.mdx @@ -1,4 +1,5 @@ --- + title: AddressTag.ts nav_order: 3 parent: Modules @@ -15,22 +16,93 @@ Added in v2.0.0

Table of contents

-- [model](#model) +- [transformation](#transformation) + - [fromBytes](#frombytes) + - [fromHeader](#fromheader) + - [networkId](#networkid) + - [paymentCredential](#paymentcredential) + - [stakeCredential](#stakecredential) +- [utils](#utils) - [AddressTag (type alias)](#addresstag-type-alias) --- -# model +# transformation -## AddressTag (type alias) +## fromBytes -Address header kind - used to determine the type of address from its header -Following CIP-0019 address types +The address kind these bytes declare, or `undefined` when they are empty or carry an undefined +header kind. **Signature** ```ts -export type AddressTag = "Base" | "Enterprise" | "Pointer" | "Reward" | "Byron" +export declare const fromBytes: (bytes: Uint8Array) => AddressTag | undefined +``` + +Added in v2.0.0 + +## fromHeader + +The address kind a header byte declares, or `undefined` for one CIP-19 does not define +(`1001`-`1101`, reserved for future formats). + +**Signature** + +```ts +export declare const fromHeader: (header: number) => AddressTag | undefined ``` Added in v2.0.0 + +## networkId + +The network id in the header's low nibble (CIP-19 bits 3-0), or `undefined` for empty bytes. + +⚠️ Byron addresses carry no network nibble — the low bits are part of the CBOR, not a network — +so this answers `undefined` for them rather than a number that means nothing. + +**Signature** + +```ts +export declare const networkId: (bytes: Uint8Array) => number | undefined +``` + +Added in v2.0.0 + +## paymentCredential + +The payment credential, for the kinds that carry one (base, pointer, enterprise). `undefined` +for a reward or Byron address, and for bytes too short to hold it. + +**Signature** + +```ts +export declare const paymentCredential: (bytes: Uint8Array) => Credential.Credential | undefined +``` + +Added in v2.0.0 + +## stakeCredential + +The staking credential, for the kinds that carry one: a base address holds it after the payment +credential, a reward address directly after the header. `undefined` for every other kind, and +for bytes too short to hold it. + +**Signature** + +```ts +export declare const stakeCredential: (bytes: Uint8Array) => Credential.Credential | undefined +``` + +Added in v2.0.0 + +# utils + +## AddressTag (type alias) + +**Signature** + +```ts +export type AddressTag = "Base" | "Enterprise" | "Pointer" | "Reward" | "Byron" +``` diff --git a/docs/content/docs/modules/Anchor.mdx b/docs/content/docs/modules/Anchor.mdx index d722260b..9fbea539 100644 --- a/docs/content/docs/modules/Anchor.mdx +++ b/docs/content/docs/modules/Anchor.mdx @@ -1,4 +1,5 @@ --- + title: Anchor.ts nav_order: 4 parent: Modules diff --git a/docs/content/docs/modules/AssetName.mdx b/docs/content/docs/modules/AssetName.mdx index 9dd3bb5c..5e7e2f19 100644 --- a/docs/content/docs/modules/AssetName.mdx +++ b/docs/content/docs/modules/AssetName.mdx @@ -1,4 +1,5 @@ --- + title: AssetName.ts nav_order: 5 parent: Modules @@ -14,7 +15,6 @@ parent: Modules - [arbitrary](#arbitrary-1) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) - [AssetName (class)](#assetname-class) - [toJSON (method)](#tojson-method) @@ -22,6 +22,7 @@ parent: Modules - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - [fromHex](#fromhex) @@ -30,6 +31,9 @@ parent: Modules - [schemas](#schemas) - [FromBytes](#frombytes-1) - [FromHex](#fromhex-1) + - [Hex](#hex) +- [utils](#utils) + - [toHex](#tohex) --- @@ -61,18 +65,6 @@ export declare const toBytes: (assetName: AssetName) => Uint8Array Added in v2.0.0 -## toHex - -Encode AssetName to hex string. - -**Signature** - -```ts -export declare const toHex: (assetName: AssetName) => string -``` - -Added in v2.0.0 - # model ## AssetName (class) @@ -148,6 +140,16 @@ Content-based hash for optimization of Equal.equals. Added in v2.0.0 +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + # parsing ## fromBytes @@ -219,3 +221,28 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +## Hex + +An asset name as hex, 0 to 32 bytes. + +⚠️ The EMPTY string is a valid asset name, not a missing one — a policy's unnamed asset is +spelled exactly that way — so the pattern admits it deliberately. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "AssetNameHex"> +``` + +Added in v2.4.0 + +# utils + +## toHex + +**Signature** + +```ts +export declare const toHex: (assetName: AssetName) => Hex +``` diff --git a/docs/content/docs/modules/Assets.mdx b/docs/content/docs/modules/Assets.mdx index d8f6e4f8..fe27b6b6 100644 --- a/docs/content/docs/modules/Assets.mdx +++ b/docs/content/docs/modules/Assets.mdx @@ -1,4 +1,5 @@ --- + title: Assets.ts nav_order: 6 parent: Modules diff --git a/docs/content/docs/modules/AuxiliaryData.mdx b/docs/content/docs/modules/AuxiliaryData.mdx index 449fe435..02c2a2ba 100644 --- a/docs/content/docs/modules/AuxiliaryData.mdx +++ b/docs/content/docs/modules/AuxiliaryData.mdx @@ -1,4 +1,5 @@ --- + title: AuxiliaryData.ts nav_order: 7 parent: Modules @@ -16,6 +17,7 @@ parent: Modules - [constructors](#constructors) - [conway](#conway) - [emptyConwayAuxiliaryData](#emptyconwayauxiliarydata) + - [fromEncoded](#fromencoded) - [shelley](#shelley) - [shelleyMA](#shelleyma) - [encoding](#encoding) @@ -119,6 +121,30 @@ export declare const emptyConwayAuxiliaryData: () => AuxiliaryData Added in v2.0.0 +## fromEncoded + +Build `auxiliary_data` from a metadata map and native scripts that are already encoded, +choosing the era form the way the chain's other producers do. + +⚠️ **The era form is part of the hash.** Bare metadata stays Shelley; anything carrying scripts +becomes Conway (`#6.259`). Always writing Conway would change `auxiliary_data_hash`, and +therefore the transaction id, for every metadata-only transaction -- which is most of them. +`cardano-multiplatform-lib` makes the same choice. + +⚠️ A Shelley `auxiliary_data` IS its metadata map, so there is nothing to build without one. +Passing neither throws rather than producing an `auxiliary_data` whose hash covers no metadata. + +**Signature** + +```ts +export declare const fromEncoded: (input: { + readonly metadata?: Uint8Array + readonly nativeScripts?: ReadonlyArray +}) => AuxiliaryData +``` + +Added in v2.8.0 + ## shelley Create a Shelley-era AuxiliaryData instance. @@ -178,10 +204,14 @@ Added in v2.0.0 Compute hash of auxiliary data (tag 259) per ledger rules. +Pass the same codec options used to serialize the transaction's auxiliary +data. Set the resulting body commitment before signing; changing encoding +afterward can invalidate the commitment and existing signatures. + **Signature** ```ts -export declare const toHash: (aux: AuxiliaryData) => AuxiliaryDataHash.AuxiliaryDataHash +export declare const toHash: (aux: AuxiliaryData, options?: CBOR.CodecOptions) => AuxiliaryDataHash.AuxiliaryDataHash ``` Added in v2.0.0 diff --git a/docs/content/docs/modules/AuxiliaryDataHash.mdx b/docs/content/docs/modules/AuxiliaryDataHash.mdx index 243e5884..3d09d660 100644 --- a/docs/content/docs/modules/AuxiliaryDataHash.mdx +++ b/docs/content/docs/modules/AuxiliaryDataHash.mdx @@ -1,4 +1,5 @@ --- + title: AuxiliaryDataHash.ts nav_order: 8 parent: Modules @@ -21,7 +22,6 @@ Added in v2.0.0 - [arbitrary](#arbitrary-1) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) - [AuxiliaryDataHash (class)](#auxiliarydatahash-class) - [toJSON (method)](#tojson-method) @@ -29,16 +29,20 @@ Added in v2.0.0 - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isAuxiliaryDataHash](#isauxiliarydatahash) +- [schemas](#schemas) + - [Hex](#hex) - [utils](#utils) - [BytesSchema](#bytesschema) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) - [HexSchema](#hexschema) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -70,18 +74,6 @@ export declare const toBytes: (a: AuxiliaryDataHash, overrideOptions?: ParseOpti Added in v2.0.0 -## toHex - -Encode AuxiliaryDataHash to hex string. - -**Signature** - -```ts -export declare const toHex: (a: AuxiliaryDataHash, overrideOptions?: ParseOptions) => string -``` - -Added in v2.0.0 - # model ## AuxiliaryDataHash (class) @@ -137,28 +129,26 @@ toString(): string [Hash.symbol](): number ``` -# parsing - -## fromBytes - -Parse AuxiliaryDataHash from bytes. +## Hex (type alias) **Signature** ```ts -export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => AuxiliaryDataHash +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 -## fromHex +# parsing + +## fromBytes -Parse AuxiliaryDataHash from hex string. +Parse AuxiliaryDataHash from bytes. **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => AuxiliaryDataHash +export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => AuxiliaryDataHash ``` Added in v2.0.0 @@ -180,6 +170,25 @@ export declare const isAuxiliaryDataHash: ( Added in v2.0.0 +# schemas + +## Hex + +An auxiliary-data hash as hex. + +Validated as well as branded: a 32-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Same shape as a transaction hash and a datum hash. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "AuxiliaryDataHashHex"> +``` + +Added in v2.4.0 + # utils ## BytesSchema @@ -231,3 +240,19 @@ export declare const HexSchema: Schema.transform< > > ``` + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => AuxiliaryDataHash +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/BaseAddress.mdx b/docs/content/docs/modules/BaseAddress.mdx index 9bac98eb..8d71f1cf 100644 --- a/docs/content/docs/modules/BaseAddress.mdx +++ b/docs/content/docs/modules/BaseAddress.mdx @@ -1,4 +1,5 @@ --- + title: BaseAddress.ts nav_order: 9 parent: Modules diff --git a/docs/content/docs/modules/Bech32.mdx b/docs/content/docs/modules/Bech32.mdx index b034a6ff..892e354e 100644 --- a/docs/content/docs/modules/Bech32.mdx +++ b/docs/content/docs/modules/Bech32.mdx @@ -1,4 +1,5 @@ --- + title: Bech32.ts nav_order: 10 parent: Modules diff --git a/docs/content/docs/modules/BigInt.mdx b/docs/content/docs/modules/BigInt.mdx index e780c704..fb8aa2d9 100644 --- a/docs/content/docs/modules/BigInt.mdx +++ b/docs/content/docs/modules/BigInt.mdx @@ -1,4 +1,5 @@ --- + title: BigInt.ts nav_order: 11 parent: Modules diff --git a/docs/content/docs/modules/Bip32PrivateKey.mdx b/docs/content/docs/modules/Bip32PrivateKey.mdx index c1d39e72..0fcbbf92 100644 --- a/docs/content/docs/modules/Bip32PrivateKey.mdx +++ b/docs/content/docs/modules/Bip32PrivateKey.mdx @@ -1,4 +1,5 @@ --- + title: Bip32PrivateKey.ts nav_order: 12 parent: Modules @@ -19,6 +20,9 @@ parent: Modules - [cml-compatibility](#cml-compatibility) - [from128XPRV](#from128xprv) - [to128XPRV](#to128xprv) +- [constants](#constants) + - [PURPOSE_CIP1852](#purpose_cip1852) + - [PURPOSE_CIP1854](#purpose_cip1854) - [conversion](#conversion) - [toPrivateKey](#toprivatekey) - [cryptography](#cryptography) @@ -28,9 +32,10 @@ parent: Modules - [toHex](#tohex) - [errors](#errors) - [Bip32PrivateKeyError (class)](#bip32privatekeyerror-class) +- [model](#model) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [schemas](#schemas) - [Bip32PrivateKey (class)](#bip32privatekey-class) - [toJSON (method)](#tojson-method) @@ -39,11 +44,13 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) - [utils](#utils) - [CardanoPath](#cardanopath) - [Either (namespace)](#either-namespace) - [arbitrary](#arbitrary) + - [fromHex](#fromhex-1) --- @@ -96,7 +103,7 @@ Create a Bip32PrivateKey from BIP39 entropy with PBKDF2 key stretching. **Signature** ```ts -export declare const fromBip39Entropy: (entropy: Uint8Array, password?: string) => Bip32PrivateKey +export declare const fromBip39Entropy: (entropy: Uint8Array, password?: Uint8Array | string) => Bip32PrivateKey ``` Added in v2.0.0 @@ -127,6 +134,32 @@ export declare const to128XPRV: (bip32PrivateKey: Bip32PrivateKey) => Uint8Array Added in v2.0.0 +# constants + +## PURPOSE_CIP1852 + +CIP-1852, the ordinary wallet purpose. + +**Signature** + +```ts +export declare const PURPOSE_CIP1852: 1852 +``` + +Added in v2.0.0 + +## PURPOSE_CIP1854 + +CIP-1854, the multi-signature purpose: same shape, different keys, never interchangeable. + +**Signature** + +```ts +export declare const PURPOSE_CIP1854: 1854 +``` + +Added in v2.0.0 + # conversion ## toPrivateKey @@ -176,7 +209,7 @@ Convert a Bip32PrivateKey to hex string. **Signature** ```ts -export declare const toHex: (a: Bip32PrivateKey, overrideOptions?: ParseOptions) => string +export declare const toHex: (value: Parameters[0]) => Hex ``` Added in v2.0.0 @@ -195,28 +228,28 @@ export declare class Bip32PrivateKeyError Added in v2.0.0 -# parsing - -## fromBytes +# model -Parse a Bip32PrivateKey from raw bytes. +## Hex (type alias) **Signature** ```ts -export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => Bip32PrivateKey +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 -## fromHex +# parsing -Parse a Bip32PrivateKey from hex string. +## fromBytes + +Parse a Bip32PrivateKey from raw bytes. **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Bip32PrivateKey +export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => Bip32PrivateKey ``` Added in v2.0.0 @@ -310,21 +343,39 @@ export declare const FromHex: Schema.transform< Added in v2.0.0 +## Hex + +A BIP32-Ed25519 extended PRIVATE key as hex (96 bytes: scalar, IV and chain code). + +Validated as well as branded: a 96-byte lowercase or uppercase hex string. {@link toHex} +returns this type, so the kind of a hex string survives leaving the typed domain — upstream of +this, every hash and key was an unmarked `string` once encoded. + +⚠️ See {@link Bip32PublicKey.Hex} for why these two carry different brands. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "Bip32PrivateKeyHex"> +``` + +Added in v2.4.0 + # utils ## CardanoPath -Utility functions to build Cardano BIP44 derivation indices. -Standard path: m/1852'/1815'/account'/role/index - **Signature** ```ts export declare const CardanoPath: { harden: (n: number) => number - indices: (account?: number, role?: 0 | 2, index?: number) => Array + indices: (account?: number, role?: number, index?: number, purpose?: number) => Array paymentIndices: (account?: number, index?: number) => Array stakeIndices: (account?: number, index?: number) => Array + drepIndices: (account?: number, index?: number) => Array + multisigPaymentIndices: (account?: number, index?: number) => Array + multisigStakeIndices: (account?: number, index?: number) => Array } ``` @@ -337,3 +388,11 @@ export declare const CardanoPath: { ```ts export declare const arbitrary: FastCheck.Arbitrary ``` + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Bip32PrivateKey +``` diff --git a/docs/content/docs/modules/Bip32PublicKey.mdx b/docs/content/docs/modules/Bip32PublicKey.mdx index 0ad7c516..d38b36d2 100644 --- a/docs/content/docs/modules/Bip32PublicKey.mdx +++ b/docs/content/docs/modules/Bip32PublicKey.mdx @@ -1,4 +1,5 @@ --- + title: Bip32PublicKey.ts nav_order: 13 parent: Modules @@ -17,6 +18,7 @@ parent: Modules - [arbitrary](#arbitrary-1) - [derivation](#derivation) - [deriveChild](#derivechild) + - [derivePath](#derivepath) - [either](#either) - [Either (namespace)](#either-namespace) - [encoding](#encoding) @@ -25,9 +27,10 @@ parent: Modules - [toRawBytes](#torawbytes) - [errors](#errors) - [Bip32PublicKeyError (class)](#bip32publickeyerror-class) +- [model](#model) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [schemas](#schemas) - [Bip32PublicKey (class)](#bip32publickey-class) - [toJSON (method)](#tojson-method) @@ -36,7 +39,10 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) +- [utils](#utils) + - [fromHex](#fromhex-1) --- @@ -94,6 +100,26 @@ export declare const deriveChild: (bip32PublicKey: Bip32PublicKey, index: number Added in v2.0.0 +## derivePath + +Derive a child public key down a path of indices (soft derivation only). + +This is what lets a wallet derive addresses from a co-signer's account xpub — no seed, no +signing ceremony — which is the whole basis of a shared wallet. + +⚠️ **Throws on any hardened index.** `deriveChild` takes a plain `number`, so a caller who +passes `0x80000000 + n` by habit (every private-side path is written that way) would otherwise +get a key silently derived from the wrong index. The account level and above are hardened by +construction, so the mistake is an easy one; failing loudly is the only safe answer. + +**Signature** + +```ts +export declare const derivePath: (bip32PublicKey: Bip32PublicKey, indices: ReadonlyArray) => Bip32PublicKey +``` + +Added in v2.0.0 + # either ## Either (namespace) @@ -123,7 +149,7 @@ Convert a Bip32PublicKey to hex string. **Signature** ```ts -export declare const toHex: (a: Bip32PublicKey, overrideOptions?: ParseOptions) => string +export declare const toHex: (value: Parameters[0]) => Hex ``` Added in v2.0.0 @@ -154,28 +180,28 @@ export declare class Bip32PublicKeyError Added in v2.0.0 -# parsing - -## fromBytes +# model -Create a BIP32 public key from public key and chain code bytes. +## Hex (type alias) **Signature** ```ts -export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => Bip32PublicKey +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 -## fromHex +# parsing + +## fromBytes -Parse Bip32PublicKey from hex string. +Create a BIP32 public key from public key and chain code bytes. **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Bip32PublicKey +export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => Bip32PublicKey ``` Added in v2.0.0 @@ -269,3 +295,33 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +## Hex + +A BIP32-Ed25519 extended PUBLIC key as hex (64 bytes: 32-byte key + 32-byte chain code). + +Validated as well as branded: a 64-byte lowercase or uppercase hex string. {@link toHex} +returns this type, so the kind of a hex string survives leaving the typed domain — upstream of +this, every hash and key was an unmarked `string` once encoded. + +⚠️ Branded apart from {@link Bip32PrivateKey.Hex} deliberately. The two are the same shape and +confusing them is unrecoverable in one direction: publishing where a private key was expected is +merely wrong, while signing with what you believed was public is a leaked key. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "Bip32PublicKeyHex"> +``` + +Added in v2.4.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Bip32PublicKey +``` diff --git a/docs/content/docs/modules/Block.mdx b/docs/content/docs/modules/Block.mdx index b6c164df..c8698760 100644 --- a/docs/content/docs/modules/Block.mdx +++ b/docs/content/docs/modules/Block.mdx @@ -1,4 +1,5 @@ --- + title: Block.ts nav_order: 14 parent: Modules diff --git a/docs/content/docs/modules/BlockBodyHash.mdx b/docs/content/docs/modules/BlockBodyHash.mdx index 25ba1b3a..a59a8456 100644 --- a/docs/content/docs/modules/BlockBodyHash.mdx +++ b/docs/content/docs/modules/BlockBodyHash.mdx @@ -1,4 +1,5 @@ --- + title: BlockBodyHash.ts nav_order: 15 parent: Modules diff --git a/docs/content/docs/modules/BlockHeaderHash.mdx b/docs/content/docs/modules/BlockHeaderHash.mdx index 7941fdad..90b3dd1a 100644 --- a/docs/content/docs/modules/BlockHeaderHash.mdx +++ b/docs/content/docs/modules/BlockHeaderHash.mdx @@ -1,4 +1,5 @@ --- + title: BlockHeaderHash.ts nav_order: 16 parent: Modules diff --git a/docs/content/docs/modules/BootstrapWitness.mdx b/docs/content/docs/modules/BootstrapWitness.mdx index 0981bfeb..a3567da3 100644 --- a/docs/content/docs/modules/BootstrapWitness.mdx +++ b/docs/content/docs/modules/BootstrapWitness.mdx @@ -1,4 +1,5 @@ --- + title: BootstrapWitness.ts nav_order: 20 parent: Modules diff --git a/docs/content/docs/modules/BoundedBytes.mdx b/docs/content/docs/modules/BoundedBytes.mdx index d5862a28..f53b8c9e 100644 --- a/docs/content/docs/modules/BoundedBytes.mdx +++ b/docs/content/docs/modules/BoundedBytes.mdx @@ -1,4 +1,5 @@ --- + title: BoundedBytes.ts nav_order: 21 parent: Modules diff --git a/docs/content/docs/modules/ByronAddress.mdx b/docs/content/docs/modules/ByronAddress.mdx index 28ea359f..c27b7d41 100644 --- a/docs/content/docs/modules/ByronAddress.mdx +++ b/docs/content/docs/modules/ByronAddress.mdx @@ -1,4 +1,5 @@ --- + title: ByronAddress.ts nav_order: 22 parent: Modules diff --git a/docs/content/docs/modules/Bytes.mdx b/docs/content/docs/modules/Bytes.mdx index 33ef93a8..1bd42e5f 100644 --- a/docs/content/docs/modules/Bytes.mdx +++ b/docs/content/docs/modules/Bytes.mdx @@ -1,4 +1,5 @@ --- + title: Bytes.ts nav_order: 23 parent: Modules diff --git a/docs/content/docs/modules/Bytes128.mdx b/docs/content/docs/modules/Bytes128.mdx index a141c8cb..d5a713d8 100644 --- a/docs/content/docs/modules/Bytes128.mdx +++ b/docs/content/docs/modules/Bytes128.mdx @@ -1,4 +1,5 @@ --- + title: Bytes128.ts nav_order: 24 parent: Modules diff --git a/docs/content/docs/modules/Bytes16.mdx b/docs/content/docs/modules/Bytes16.mdx index 0dc01148..456e0bc1 100644 --- a/docs/content/docs/modules/Bytes16.mdx +++ b/docs/content/docs/modules/Bytes16.mdx @@ -1,4 +1,5 @@ --- + title: Bytes16.ts nav_order: 25 parent: Modules diff --git a/docs/content/docs/modules/Bytes29.mdx b/docs/content/docs/modules/Bytes29.mdx index e724dbba..2d76ab63 100644 --- a/docs/content/docs/modules/Bytes29.mdx +++ b/docs/content/docs/modules/Bytes29.mdx @@ -1,4 +1,5 @@ --- + title: Bytes29.ts nav_order: 26 parent: Modules diff --git a/docs/content/docs/modules/Bytes32.mdx b/docs/content/docs/modules/Bytes32.mdx index 7fb8f076..7f547efa 100644 --- a/docs/content/docs/modules/Bytes32.mdx +++ b/docs/content/docs/modules/Bytes32.mdx @@ -1,4 +1,5 @@ --- + title: Bytes32.ts nav_order: 27 parent: Modules diff --git a/docs/content/docs/modules/Bytes4.mdx b/docs/content/docs/modules/Bytes4.mdx index ea003d84..fafb1cd9 100644 --- a/docs/content/docs/modules/Bytes4.mdx +++ b/docs/content/docs/modules/Bytes4.mdx @@ -1,4 +1,5 @@ --- + title: Bytes4.ts nav_order: 28 parent: Modules diff --git a/docs/content/docs/modules/Bytes448.mdx b/docs/content/docs/modules/Bytes448.mdx index dfb2a3fe..e01b60b3 100644 --- a/docs/content/docs/modules/Bytes448.mdx +++ b/docs/content/docs/modules/Bytes448.mdx @@ -1,4 +1,5 @@ --- + title: Bytes448.ts nav_order: 29 parent: Modules diff --git a/docs/content/docs/modules/Bytes57.mdx b/docs/content/docs/modules/Bytes57.mdx index e5fa3674..1f240640 100644 --- a/docs/content/docs/modules/Bytes57.mdx +++ b/docs/content/docs/modules/Bytes57.mdx @@ -1,4 +1,5 @@ --- + title: Bytes57.ts nav_order: 30 parent: Modules diff --git a/docs/content/docs/modules/Bytes64.mdx b/docs/content/docs/modules/Bytes64.mdx index b11f9c38..b12c0206 100644 --- a/docs/content/docs/modules/Bytes64.mdx +++ b/docs/content/docs/modules/Bytes64.mdx @@ -1,4 +1,5 @@ --- + title: Bytes64.ts nav_order: 31 parent: Modules diff --git a/docs/content/docs/modules/Bytes80.mdx b/docs/content/docs/modules/Bytes80.mdx index 3a3c90e8..28d815d5 100644 --- a/docs/content/docs/modules/Bytes80.mdx +++ b/docs/content/docs/modules/Bytes80.mdx @@ -1,4 +1,5 @@ --- + title: Bytes80.ts nav_order: 32 parent: Modules diff --git a/docs/content/docs/modules/Bytes96.mdx b/docs/content/docs/modules/Bytes96.mdx index 2f41bf6c..93c55f9b 100644 --- a/docs/content/docs/modules/Bytes96.mdx +++ b/docs/content/docs/modules/Bytes96.mdx @@ -1,4 +1,5 @@ --- + title: Bytes96.ts nav_order: 33 parent: Modules diff --git a/docs/content/docs/modules/CBOR.mdx b/docs/content/docs/modules/CBOR.mdx index 0b2ba6a9..d9437a84 100644 --- a/docs/content/docs/modules/CBOR.mdx +++ b/docs/content/docs/modules/CBOR.mdx @@ -1,4 +1,5 @@ --- + title: CBOR.ts nav_order: 34 parent: Modules @@ -11,18 +12,29 @@ parent: Modules

Table of contents

- [constants](#constants) - - [AIKEN_DEFAULT_OPTIONS](#aiken_default_options) + - [~~AIKEN_DEFAULT_OPTIONS~~](#aiken_default_options) - [CANONICAL_OPTIONS](#canonical_options) - - [CARDANO_NODE_DATA_OPTIONS](#cardano_node_data_options) + - [~~CARDANO_NODE_DATA_OPTIONS~~](#cardano_node_data_options) - [CBOR_ADDITIONAL_INFO](#cbor_additional_info) - [CBOR_MAJOR_TYPE](#cbor_major_type) - [CBOR_SIMPLE](#cbor_simple) - - [CML_DATA_DEFAULT_OPTIONS](#cml_data_default_options) + - [~~CML_DATA_DEFAULT_OPTIONS~~](#cml_data_default_options) + - [CML_DATA_DEFINITE_OPTIONS](#cml_data_definite_options) - [CML_DEFAULT_OPTIONS](#cml_default_options) + - [PLUTUS_DATA_OPTIONS](#plutus_data_options) - [STRUCT_FRIENDLY_OPTIONS](#struct_friendly_options) + - [TX_CANONICAL_OPTIONS](#tx_canonical_options) + - [TX_DEFAULT_OPTIONS](#tx_default_options) - [decoding](#decoding) - [decodeItemWithOffset](#decodeitemwithoffset) + - [decodeItemWithOffsetAndFormat](#decodeitemwithoffsetandformat) + - [splitArrayItems](#splitarrayitems) + - [splitMapEntries](#splitmapentries) - [encoding](#encoding) + - [compareByteKeys](#comparebytekeys) + - [encodeMapAsDefinite](#encodemapasdefinite) + - [encodeTaggedSet](#encodetaggedset) + - [sortByteKeyedMap](#sortbytekeyedmap) - [toCBORBytes](#tocborbytes) - [toCBORBytesWithFormat](#tocborbyteswithformat) - [toCBORHex](#tocborhex) @@ -47,8 +59,11 @@ parent: Modules - [UInt (type alias)](#uint-type-alias) - [CodecOptions (type alias)](#codecoptions-type-alias) - [DecodedWithFormat (type alias)](#decodedwithformat-type-alias) + - [DefiniteArray](#definitearray) - [LengthEncoding (type alias)](#lengthencoding-type-alias) + - [Raw](#raw) - [StringEncoding (type alias)](#stringencoding-type-alias) + - [TxCodecOptions (type alias)](#txcodecoptions-type-alias) - [parsing](#parsing) - [fromCBORBytes](#fromcborbytes) - [fromCBORBytesWithFormat](#fromcborbyteswithformat) @@ -61,6 +76,7 @@ parent: Modules - [Integer](#integer) - [transformation](#transformation) - [match](#match) + - [toTxCodecOptions](#totxcodecoptions) - [utils](#utils) - [ArraySchema](#arrayschema) - [ByteArray](#bytearray) @@ -90,19 +106,14 @@ parent: Modules # constants -## AIKEN_DEFAULT_OPTIONS - -Aiken-compatible CBOR encoding options. - -Matches the encoding produced by `cbor.serialise()` in Aiken: +## ~~AIKEN_DEFAULT_OPTIONS~~ -- Indefinite-length arrays (`9f...ff`) -- Maps encoded as arrays of pairs (not CBOR maps) -- Strings as byte arrays (major type 2, not 3) -- Constructor tags: 121–127 for indices 0–6, then 1280+ for 7+ +Aiken `cbor.serialise()` encoding options. Same object as +{@link PLUTUS_DATA_OPTIONS}. -PlutusData byte strings are chunked per the Conway `bounded_bytes` rule -via the `BoundedBytes` CBOR node, independent of these codec options. +Aiken writes data in the node layout: non-empty lists and constructor +fields indefinite, `Pairs` as definite maps. Tuples are lists, so they +encode as indefinite arrays. **Signature** @@ -124,16 +135,13 @@ export declare const CANONICAL_OPTIONS: CodecOptions Added in v1.0.0 -## CARDANO_NODE_DATA_OPTIONS +## ~~CARDANO_NODE_DATA_OPTIONS~~ -Cardano Node compatible CBOR encoding options for PlutusData +Definite-length PlutusData encoding options. Same object as +{@link CML_DATA_DEFINITE_OPTIONS}. -Uses definite-length encoding for arrays and maps, matching the format -produced by CML's `to_cardano_node_format().to_cbor_hex()`. - -Note: The on-chain format uses indefinite-length (AIKEN_DEFAULT_OPTIONS), -but this option is useful for testing compatibility with tools that -expect definite-length encoding. +The name is wrong: the Cardano node writes non-empty lists and constructor +fields indefinite. For the node layout use {@link PLUTUS_DATA_OPTIONS}. **Signature** @@ -194,13 +202,19 @@ export declare const CBOR_SIMPLE: { readonly FALSE: 20; readonly TRUE: 21; reado Added in v1.0.0 -## CML_DATA_DEFAULT_OPTIONS +## ~~CML_DATA_DEFAULT_OPTIONS~~ -Default CBOR encoding options for PlutusData. +CBOR encoding options for PlutusData with non-empty lists, constructor +fields and maps indefinite, map keys in the order given. This was the +`Data` default before {@link PLUTUS_DATA_OPTIONS}. -Uses indefinite-length arrays and maps. The `bounded_bytes` constraint -(Conway CDDL: byte strings ≤ 64 bytes) is enforced at the data-type layer -via the `BoundedBytes` CBOR node, independent of these codec options. +It matches no tool exactly. The node, cardano-cli and Aiken write maps +definite. CML 6.2.0 `PlutusData.to_cardano_node_format()` writes maps +indefinite but also sorts map keys. For a constructor index above 127 the +Plutus data encoder writes the tag 102 `[index, fields]` pair definite +under every preset, including this one. Use it only to reproduce the bytes +and datum hashes the SDK wrote before {@link PLUTUS_DATA_OPTIONS} became +the default. **Signature** @@ -210,6 +224,23 @@ export declare const CML_DATA_DEFAULT_OPTIONS: CodecOptions Added in v1.0.0 +## CML_DATA_DEFINITE_OPTIONS + +CBOR encoding options for PlutusData matching CML `PlutusData.to_cbor_hex()` +on freshly built data. + +Uses definite-length lists, constructor fields, and maps. It differs from +the node layout ({@link PLUTUS_DATA_OPTIONS}) by writing lists and +constructor fields definite. + +**Signature** + +```ts +export declare const CML_DATA_DEFINITE_OPTIONS: CodecOptions +``` + +Added in v2.0.0 + ## CML_DEFAULT_OPTIONS Default CBOR encoding options @@ -222,6 +253,29 @@ export declare const CML_DEFAULT_OPTIONS: CodecOptions Added in v1.0.0 +## PLUTUS_DATA_OPTIONS + +CBOR encoding options for PlutusData in the layout the Cardano node writes. + +- Non-empty lists and constructor fields: indefinite-length (`9f...ff`) +- Maps: definite-length +- Empty list: `80`; empty map: `a0` + +The `Data` default. `Data.toCBORBytes` with these options writes the bytes +the node writes. +The rules that do not depend on options are applied by the Plutus data +encoder under every preset: byte strings over 64 bytes in 64-byte chunks, +bignums only outside -2^64 to 2^64 - 1 with their bytes chunked the same +way, and a definite `[index, fields]` pair under tag 102. + +**Signature** + +```ts +export declare const PLUTUS_DATA_OPTIONS: CodecOptions +``` + +Added in v2.0.0 + ## STRUCT_FRIENDLY_OPTIONS CBOR encoding options that return objects instead of Maps for Schema.Struct compatibility @@ -234,6 +288,38 @@ export declare const STRUCT_FRIENDLY_OPTIONS: CodecOptions Added in v2.0.0 +## TX_CANONICAL_OPTIONS + +Canonical options for a transaction: {@link CANONICAL_OPTIONS} for both +ledger structures and Plutus data. + +**Signature** + +```ts +export declare const TX_CANONICAL_OPTIONS: TxCodecOptions +``` + +Added in v2.0.0 + +## TX_DEFAULT_OPTIONS + +Default options for a transaction. + +- `ledger` is {@link CML_DEFAULT_OPTIONS}, CML's transaction encoding: map + keys in insertion order, definite lengths. +- `plutusData` is {@link PLUTUS_DATA_OPTIONS}, the `Data` default. + +It does not match cardano-cli, which sorts map keys and writes indefinite +lengths above 23 entries. + +**Signature** + +```ts +export declare const TX_DEFAULT_OPTIONS: TxCodecOptions +``` + +Added in v2.0.0 + # decoding ## decodeItemWithOffset @@ -253,8 +339,152 @@ export declare const decodeItemWithOffset: ( Added in v2.0.0 +## decodeItemWithOffsetAndFormat + +Decode one item at `offset`, keeping the per-node encoding metadata. + +The format-blind {@link decodeItemWithOffset} is enough to measure or skip an item; this is for +callers that must re-encode it byte for byte afterwards, where the definite/indefinite framing and +head widths have to survive the round trip. + +**Signature** + +```ts +export declare const decodeItemWithOffsetAndFormat: ( + data: Uint8Array, + offset: number, + options?: CodecOptions +) => { item: CBOR; format: CBORFormat; newOffset: number } +``` + +Added in v2.0.0 + +## splitArrayItems + +Split an encoded CBOR array into the ORIGINAL bytes of each of its items. + +A `#6.258` tag around the array is accepted and stepped over, so a ledger set and a bare array +are both read; the tag itself is not part of any item. + +⚠️ **Use this instead of decoding an array and re-encoding its items.** Decode-then-re-encode +runs every item through an encoder, which means every item comes back in whatever shape the +options in force describe rather than the shape it arrived in. For `plutus_data` that moves +`script_data_hash`; for a certificate or a script it changes the transaction id. This returns +slices of the input, so there is no encoder in the path and nothing to configure wrongly. + +The items are _not_ validated beyond being well-formed CBOR, because the caller is about to +decode each one into whatever it expects. + +**Signature** + +```ts +export declare const splitArrayItems: (bytes: Uint8Array) => ReadonlyArray +``` + +**Example** + +```ts +import * as CBOR from "@evolution-sdk/evolution/CBOR" +import * as Bytes from "@evolution-sdk/evolution/Bytes" + +// An indefinite empty Plutus constructor inside a tagged set keeps its framing. +const items = CBOR.splitArrayItems(Bytes.fromHex("d9010281d8799f182aff")) +// items[0] is d8799f182aff, not d87981182a +``` + +Added in v2.8.0 + +## splitMapEntries + +Split an encoded CBOR map into the ORIGINAL bytes of each of its keys and values. + +The map counterpart of {@link splitArrayItems}, and the same argument applies: decoding a map +and re-encoding its entries runs each one through whatever options are in force, which for a +redeemer map's `plutus_data` moves `script_data_hash`. + +Entries come back in wire order, which for a Plutus map is the order that matters. + +**Signature** + +```ts +export declare const splitMapEntries: (bytes: Uint8Array) => ReadonlyArray +``` + +Added in v2.8.0 + # encoding +## compareByteKeys + +Canonical CBOR map-key order for byte-string keys: shorter keys first, then lexicographic +(RFC 8949 §4.2.1, and CIP-21 for transaction bodies). + +Ledger maps keyed by bytes -- multiassets, mints -- must be written in this order for a client +to reconstruct byte-identically the body a hardware wallet hashed in chunks. It is applied by +the encoders that own those maps rather than by a global codec option, because the same option +would also reorder Plutus map keys, which must keep the order they were given. + +**Signature** + +```ts +export declare const compareByteKeys: (a: Uint8Array, b: Uint8Array) => number +``` + +Added in v2.0.0 + +## encodeMapAsDefinite + +Encode a CBOR definite-length map from already-encoded key and value bytes. + +The sibling of `encodeArrayAsDefinite` for major type 5. Entries are written in the order +given — this is the raw-bytes path, so it imposes no key ordering of its own. + +Together with the array and tag builders this is what lets a caller assemble a structure +around children it must NOT re-encode: anything already in bytes (a received datum, a script, +a redeemer) survives verbatim, where decoding it to a value and re-encoding can change its +framing and therefore its hash. + +**Signature** + +```ts +export declare const encodeMapAsDefinite: (entries: ReadonlyArray) => Uint8Array +``` + +Added in v2.0.0 + +## encodeTaggedSet + +A `#6.258` set over items that are ALREADY encoded, written definite. + +The write direction of {@link splitArrayItems}, and the shape every ledger set takes in Conway: +`inputs`, `certificates`, `collateral_inputs`, `required_signers`, `reference_inputs`, the +witness-set script fields and `plutus_data`. Babbage wrote a bare array and the ledger still +accepts it, so {@link encodeArrayAsDefinite} is the untagged form -- but the two are different +bytes and therefore a different transaction id, which is why neither is a default and a caller +says which it means. + +⚠️ The items are spliced, not re-encoded, for the reason given on {@link splitArrayItems}. + +**Signature** + +```ts +export declare const encodeTaggedSet: (items: ReadonlyArray) => Uint8Array +``` + +Added in v2.8.0 + +## sortByteKeyedMap + +Rebuild a byte-keyed map in canonical CBOR key order. + +**Signature** + +```ts +export declare const sortByteKeyedMap: (map: Map) => Map +``` + +Added in v2.0.0 + ## toCBORBytes Convert a CBOR value to CBOR bytes. @@ -391,7 +621,9 @@ export type CBOR = | null // null value | undefined // undefined value | number // floating point numbers - | { _tag: "BoundedBytes"; bytes: Uint8Array } + | { _tag: "BoundedBytes"; bytes: Uint8Array } // PlutusData bounded byte strings (Conway CDDL bounded_bytes = bytes .size (0..64)) + | { _tag: "DefiniteArray"; items: ReadonlyArray } // an array written definite whatever the codec options say + | { _tag: "Raw"; bytes: Uint8Array } ``` Added in v1.0.0 @@ -526,6 +758,13 @@ export type CodecOptions = | { readonly mode: "canonical" readonly mapsAsObjects?: boolean + /** + * Encode every map as an array of `[key, value]` pairs. + * + * @deprecated This turns a map into a list, which is a different value + * with a different hash. No Plutus data encoder writes maps this way, and + * no option replaces it: leave it unset so maps stay maps. + */ readonly encodeMapAsPairs?: boolean } | { @@ -536,6 +775,13 @@ export type CodecOptions = readonly sortMapKeys: boolean readonly useMinimalEncoding: boolean readonly mapsAsObjects?: boolean + /** + * Encode every map as an array of `[key, value]` pairs. + * + * @deprecated This turns a map into a list, which is a different value + * with a different hash. No Plutus data encoder writes maps this way, and + * no option replaces it: leave it unset so maps stay maps. + */ readonly encodeMapAsPairs?: boolean } ``` @@ -557,6 +803,28 @@ export type DecodedWithFormat = { Added in v2.0.0 +## DefiniteArray + +`DefiniteArray` CBOR node — an array written with definite-length framing whatever the codec +options say. + +Its one consumer is the **tag-102 constructor wrapper** `[index, fields]`, which is definite +while the fields array inside it is indefinite. No single codec option can say both, and the +wrapper's framing is not a preference: `cardano-serialization-lib` 15.0.3 and +`cardano-multiplatform-lib` 6.2 both write `d866 82 …` for `Constr(999999, [42])`, where this +library wrote `d866 9f … ff`. Two independent implementations against one. + +**Signature** + +```ts +export declare const DefiniteArray: { + readonly make: (items: ReadonlyArray) => CBOR + readonly is: (value: CBOR) => value is { _tag: "DefiniteArray"; items: ReadonlyArray } +} +``` + +Added in v2.0.0 + ## LengthEncoding (type alias) Container length encoding style captured during decode. @@ -569,6 +837,36 @@ export type LengthEncoding = { readonly tag: "indefinite" } | { readonly tag: "d Added in v2.0.0 +## Raw + +`Raw` CBOR node — bytes that are already CBOR, written back unchanged. + +Every other node describes a _value_ and leaves the encoder to choose a representation. This +one describes a representation. It exists because the ledger hashes the bytes a value arrived +as, not a fresh encoding of it, and several of those choices are not recoverable from the +decoded value: an empty indefinite array (`9fff`) decodes to the same `[]` as `80`, a +chunked byte string to the same bytes as an unchunked one, a non-minimal integer header to the +same number. Re-deriving any of them changes the hash, and for `plutus_data` inside a redeemer +that changes `script_data_hash` and the transaction is rejected with nothing pointing back here. + +`Data.plutusDataToCBORValue` emits one of these for any node whose arrival bytes were recorded +on the {@link OriginalBytes} channel, so the single encoder below handles provenance and +structure in one pass instead of a caller splicing bytes by hand. + +⚠️ The bytes are not validated. A `Raw` holding something that is not well-formed CBOR produces +a transaction that is not well-formed CBOR. Build it only from bytes a decoder returned. + +**Signature** + +```ts +export declare const Raw: { + readonly make: (bytes: Uint8Array) => CBOR + readonly is: (value: CBOR) => value is { _tag: "Raw"; bytes: Uint8Array } +} +``` + +Added in v2.8.0 + ## StringEncoding (type alias) Byte/text string encoding style captured during decode. @@ -586,6 +884,26 @@ export type StringEncoding = Added in v2.0.0 +## TxCodecOptions (type alias) + +CBOR options for a transaction and the structures in it. + +- `ledger`: the options for ledger structures: the body, the witness set, + and the containers that hold datums and redeemers. +- `plutusData`: the options for Plutus data items: new inline datums, + witness datums and redeemer data. + +**Signature** + +```ts +export type TxCodecOptions = { + readonly ledger: CodecOptions + readonly plutusData: CodecOptions +} +``` + +Added in v2.0.0 + # parsing ## fromCBORBytes @@ -719,6 +1037,21 @@ export declare const match: ( Added in v1.0.0 +## toTxCodecOptions + +Turns plain options into transaction options: `ledger` is the options and +`plutusData` is the options too, except that {@link CML_DEFAULT_OPTIONS} +gives {@link PLUTUS_DATA_OPTIONS}, as {@link TX_DEFAULT_OPTIONS} does. +Transaction options are returned as they are. + +**Signature** + +```ts +export declare const toTxCodecOptions: (options: TxCodecOptions | CodecOptions) => TxCodecOptions +``` + +Added in v2.0.0 + # utils ## ArraySchema diff --git a/docs/content/docs/modules/CBORBuilder.mdx b/docs/content/docs/modules/CBORBuilder.mdx new file mode 100644 index 00000000..b4ab8a5e --- /dev/null +++ b/docs/content/docs/modules/CBORBuilder.mdx @@ -0,0 +1,534 @@ +--- + +title: CBORBuilder.ts +nav_order: 35 +parent: Modules +--- + +## CBORBuilder overview + +An incremental builder and sequential reader over {@link CBOR}. + +`CBOR.toCBORBytes` encodes a value you have already constructed. Some callers instead describe a +document as they walk it — a header, then a field, then a nested container — and constructing the +whole value tree first is awkward for them. `Serializer` gives those callers the append-as-you-go +shape while **the bytes are still produced by `CBOR`'s encoder**: writes accumulate a value and +its `CBORFormat`, and `finalize()` encodes through `toCBORBytesWithFormat`. + +⚠️ This is deliberately **not** a second encoder. Two encoders in one library that must agree byte +for byte is a drift hazard, and the point of this module is to offer the API without taking it on. + +## Not streaming + +Despite the append shape, nothing here streams: `finalize()` needs the whole document, and +`Deserializer` reads a buffer already wholly in memory. Callers that must emit before the value is +known, or consume input that does not fit in memory, need a different design. + +## What this catches that a raw byte emitter does not + +A builder that writes header bytes straight to a buffer cannot tell that `writeArray(len(5))` was +followed by two items — it hands back malformed CBOR without a word. Here the declared length +drives the structure, so an unfinished container is a `finalize()` error rather than bytes a node +will reject later. + +## Read side + +`Deserializer` parses item heads itself, because reading `array()` must report a length without +consuming the children, and `tag()` must report a tag and leave its content. It is lenient, as a +CBOR reader should be: non-minimal heads and indefinite containers are accepted. Whole-item skips +delegate to `CBOR.decodeItemWithOffsetAndFormat`. + +Added in v2.0.0 + +--- + +

Table of contents

+ +- [constants](#constants) + - [INDEFINITE](#indefinite) +- [constructors](#constructors) + - [len](#len) +- [errors](#errors) + - [CBORBuilderError (class)](#cborbuildererror-class) +- [model](#model) + - [Deserializer (class)](#deserializer-class) + - [from (static method)](#from-static-method) + - [byteAt (method)](#byteat-method) + - [head (method)](#head-method) + - [peekMajor (method)](#peekmajor-method) + - [expect (method)](#expect-method) + - [cborType (method)](#cbortype-method) + - [unsignedInteger (method)](#unsignedinteger-method) + - [negativeInteger (method)](#negativeinteger-method) + - [position (method)](#position-method) + - [skip (method)](#skip-method) + - [skipValue (method)](#skipvalue-method) + - [tag (method)](#tag-method) + - [array (method)](#array-method) + - [map (method)](#map-method) + - [special (method)](#special-method) + - [bool (method)](#bool-method) + - [bytes (method)](#bytes-method) + - [text (method)](#text-method) + - [Len (type alias)](#len-type-alias) + - [Serializer (class)](#serializer-class) + - [newVec (static method)](#newvec-static-method) + - [push (method)](#push-method) + - [closeArray (method)](#closearray-method) + - [closeMap (method)](#closemap-method) + - [writeUnsignedInteger (method)](#writeunsignedinteger-method) + - [writeNegativeInteger (method)](#writenegativeinteger-method) + - [writeBytes (method)](#writebytes-method) + - [writeText (method)](#writetext-method) + - [writeArray (method)](#writearray-method) + - [writeMap (method)](#writemap-method) + - [writeTag (method)](#writetag-method) + - [writeSpecial (method)](#writespecial-method) + - [writeRaw (method)](#writeraw-method) + - [finalize (method)](#finalize-method) +- [parsing](#parsing) + - [itemLen](#itemlen) + - [readHead](#readhead) + +--- + +# constants + +## INDEFINITE + +**Signature** + +```ts +export declare const INDEFINITE: Len +``` + +Added in v2.0.0 + +# constructors + +## len + +**Signature** + +```ts +export declare const len: (n: number) => Len +``` + +Added in v2.0.0 + +# errors + +## CBORBuilderError (class) + +Raised for a misuse of the builder or a malformed read. + +**Signature** + +```ts +export declare class CBORBuilderError { + constructor(message: string) +} +``` + +Added in v2.0.0 + +# model + +## Deserializer (class) + +Reads CBOR items in sequence from a buffer. + +Lenient on purpose: non-minimal heads and indefinite containers are accepted, matching what a +CBOR reader is supposed to do with input it did not produce. + +**Signature** + +```ts +export declare class Deserializer { constructor(private readonly buf: Uint8Array) } +``` + +Added in v2.0.0 + +### from (static method) + +**Signature** + +```ts +static from(bytes: Uint8Array): Deserializer +``` + +Added in v2.0.0 + +### byteAt (method) + +**Signature** + +```ts +private byteAt(i: number): number +``` + +### head (method) + +Read a head, returning its major type and argument, and advance past it. + +**Signature** + +```ts +private head(): { major: number; arg: bigint; indefinite: boolean } +``` + +### peekMajor (method) + +**Signature** + +```ts +private peekMajor(): number +``` + +### expect (method) + +**Signature** + +```ts +private expect(major: number, what: string): { arg: bigint; indefinite: boolean } +``` + +### cborType (method) + +**Signature** + +```ts +cborType(): CborType +``` + +Added in v2.0.0 + +### unsignedInteger (method) + +**Signature** + +```ts +unsignedInteger(): bigint +``` + +Added in v2.0.0 + +### negativeInteger (method) + +**Signature** + +```ts +negativeInteger(): bigint +``` + +Added in v2.0.0 + +### position (method) + +**Signature** + +```ts +position(): number +``` + +Added in v2.0.0 + +### skip (method) + +**Signature** + +```ts +skip(n: number): void +``` + +Added in v2.0.0 + +### skipValue (method) + +Skip one complete item, however deeply nested. @since 2.0.0 + +**Signature** + +```ts +skipValue(): void +``` + +### tag (method) + +**Signature** + +```ts +tag(): bigint +``` + +Added in v2.0.0 + +### array (method) + +**Signature** + +```ts +array(): Len +``` + +Added in v2.0.0 + +### map (method) + +**Signature** + +```ts +map(): Len +``` + +Added in v2.0.0 + +### special (method) + +**Signature** + +```ts +special(): Special +``` + +Added in v2.0.0 + +### bool (method) + +**Signature** + +```ts +bool(): boolean +``` + +Added in v2.0.0 + +### bytes (method) + +**Signature** + +```ts +bytes(): Uint8Array +``` + +Added in v2.0.0 + +### text (method) + +**Signature** + +```ts +text(): string +``` + +Added in v2.0.0 + +## Len (type alias) + +Array/map length: a definite element count, or indefinite (`0x9f` / `0xbf`). + +**Signature** + +```ts +export type Len = { readonly definite: number } | "indefinite" +``` + +Added in v2.0.0 + +## Serializer (class) + +Builds a CBOR document by appending items, then encodes it through `CBOR`'s encoder. + +Writes that follow a container header are that container's children, and the container closes +when its declared length is satisfied — so the call sequence reads the way the bytes do. + +**Signature** + +```ts +export declare class Serializer +``` + +Added in v2.0.0 + +### newVec (static method) + +**Signature** + +```ts +static newVec(): Serializer +``` + +Added in v2.0.0 + +### push (method) + +Attach a completed item to the innermost open container, closing any it completes. + +**Signature** + +```ts +private push(value: CBOR.CBOR, format: CBOR.CBORFormat): this +``` + +### closeArray (method) + +**Signature** + +```ts +private closeArray(frame: Extract): Pair +``` + +### closeMap (method) + +**Signature** + +```ts +private closeMap(frame: Extract): Pair +``` + +### writeUnsignedInteger (method) + +**Signature** + +```ts +writeUnsignedInteger(n: bigint | number): this +``` + +Added in v2.0.0 + +### writeNegativeInteger (method) + +`n` is the actual negative value (e.g. -5 → major 1, argument 4). @since 2.0.0 + +**Signature** + +```ts +writeNegativeInteger(n: bigint | number): this +``` + +### writeBytes (method) + +**Signature** + +```ts +writeBytes(b: Uint8Array): this +``` + +Added in v2.0.0 + +### writeText (method) + +**Signature** + +```ts +writeText(s: string): this +``` + +Added in v2.0.0 + +### writeArray (method) + +**Signature** + +```ts +writeArray(l: Len): this +``` + +Added in v2.0.0 + +### writeMap (method) + +**Signature** + +```ts +writeMap(l: Len): this +``` + +Added in v2.0.0 + +### writeTag (method) + +**Signature** + +```ts +writeTag(t: bigint | number): this +``` + +Added in v2.0.0 + +### writeSpecial (method) + +Write a major-7 simple value. `Special.Break` closes the innermost indefinite container, which +is what the `0xff` byte does on the wire. + +**Signature** + +```ts +writeSpecial(s: Special, value?: boolean): this +``` + +Added in v2.0.0 + +### writeRaw (method) + +Append already-encoded CBOR verbatim. The bytes are decoded with their format preserved and +re-encoded from it, so they survive the round trip unchanged while still being structurally +accounted for by any container they land in. + +**Signature** + +```ts +writeRaw(bytes: Uint8Array): this +``` + +Added in v2.0.0 + +### finalize (method) + +Encode everything written so far. + +**Signature** + +```ts +finalize(): Uint8Array +``` + +Added in v2.0.0 + +# parsing + +## itemLen + +Byte length of the single complete item starting at `pos`. + +⚠️ Measured by the **decoder**, not by a second scanner of its own. A span scanner that walks the +bytes independently is a second opinion about where an item ends, and the two disagreeing is a +live bug class: the span is what slices a body that then gets hashed and signed, so a scanner +more permissive than the decoder hands back a region the decoder would have rejected. + +**Signature** + +```ts +export declare const itemLen: (bytes: Uint8Array, pos: number) => number +``` + +Added in v2.0.0 + +## readHead + +Read a definite-length item head at `pos`, without consuming the item. + +Returns `[headLength, argument, majorType]`. Callers that walk a structure by hand — a COSE_Sign1 +parser stepping element by element, say — need the head's own width to advance past it, which a +whole-item decode does not report. + +Indefinite heads are refused: a caller asking for an argument has no use for a container whose +length is not stated. + +**Signature** + +```ts +export declare const readHead: (bytes: Uint8Array, pos: number) => [number, bigint, number] +``` + +Added in v2.0.0 diff --git a/docs/content/docs/modules/Certificate.mdx b/docs/content/docs/modules/Certificate.mdx index b2cd409a..114c07ef 100644 --- a/docs/content/docs/modules/Certificate.mdx +++ b/docs/content/docs/modules/Certificate.mdx @@ -1,6 +1,7 @@ --- + title: Certificate.ts -nav_order: 35 +nav_order: 36 parent: Modules --- @@ -1240,7 +1241,18 @@ export declare const FromCBORBytes: ( } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -1466,7 +1478,18 @@ export declare const FromCBORHex: ( } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -1680,7 +1703,18 @@ export declare const FromCDDL: Schema.transformOrFail< } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -1920,7 +1954,18 @@ export declare const CDDLSchema: Schema.Union< } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], diff --git a/docs/content/docs/modules/Codec.mdx b/docs/content/docs/modules/Codec.mdx index 1083b0f7..3527c954 100644 --- a/docs/content/docs/modules/Codec.mdx +++ b/docs/content/docs/modules/Codec.mdx @@ -1,6 +1,7 @@ --- + title: Codec.ts -nav_order: 36 +nav_order: 37 parent: Modules --- diff --git a/docs/content/docs/modules/Coin.mdx b/docs/content/docs/modules/Coin.mdx index 0e58503c..279ff09c 100644 --- a/docs/content/docs/modules/Coin.mdx +++ b/docs/content/docs/modules/Coin.mdx @@ -1,6 +1,7 @@ --- + title: Coin.ts -nav_order: 37 +nav_order: 38 parent: Modules --- diff --git a/docs/content/docs/modules/CommitteeColdCredential.mdx b/docs/content/docs/modules/CommitteeColdCredential.mdx index d22fca63..d790f654 100644 --- a/docs/content/docs/modules/CommitteeColdCredential.mdx +++ b/docs/content/docs/modules/CommitteeColdCredential.mdx @@ -1,6 +1,7 @@ --- + title: CommitteeColdCredential.ts -nav_order: 38 +nav_order: 39 parent: Modules --- diff --git a/docs/content/docs/modules/CommitteeHotCredential.mdx b/docs/content/docs/modules/CommitteeHotCredential.mdx index b4d7b99c..c7202968 100644 --- a/docs/content/docs/modules/CommitteeHotCredential.mdx +++ b/docs/content/docs/modules/CommitteeHotCredential.mdx @@ -1,6 +1,7 @@ --- + title: CommitteeHotCredential.ts -nav_order: 39 +nav_order: 40 parent: Modules --- diff --git a/docs/content/docs/modules/Constitution.mdx b/docs/content/docs/modules/Constitution.mdx index ac54f058..a50b767c 100644 --- a/docs/content/docs/modules/Constitution.mdx +++ b/docs/content/docs/modules/Constitution.mdx @@ -1,6 +1,7 @@ --- + title: Constitution.ts -nav_order: 40 +nav_order: 41 parent: Modules --- @@ -186,14 +187,7 @@ export declare const FromCBORBytes: ( export declare const FromCBORHex: ( options?: CBOR.CodecOptions ) => Schema.transform< - Schema.transform< - Schema.Schema, - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - > - >, + Schema.Schema, Schema.transform< Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, diff --git a/docs/content/docs/modules/CostModel.mdx b/docs/content/docs/modules/CostModel.mdx index 3bb4723c..52137de2 100644 --- a/docs/content/docs/modules/CostModel.mdx +++ b/docs/content/docs/modules/CostModel.mdx @@ -1,6 +1,7 @@ --- + title: CostModel.ts -nav_order: 48 +nav_order: 49 parent: Modules --- diff --git a/docs/content/docs/modules/Credential.mdx b/docs/content/docs/modules/Credential.mdx index f5c434ff..a0a01431 100644 --- a/docs/content/docs/modules/Credential.mdx +++ b/docs/content/docs/modules/Credential.mdx @@ -1,6 +1,7 @@ --- + title: Credential.ts -nav_order: 49 +nav_order: 50 parent: Modules --- @@ -11,8 +12,10 @@ parent: Modules

Table of contents

- [encoding](#encoding) + - [toBech32](#tobech32) - [toCBORBytes](#tocborbytes) - [toCBORHex](#tocborhex) + - [toHex](#tohex) - [model](#model) - [Credential (type alias)](#credential-type-alias) - [parsing](#parsing) @@ -37,6 +40,19 @@ parent: Modules # encoding +## toBech32 + +Convert a Credential to a bech32 string. +Uses CIP-0005 prefixes: `addr_vkh` for KeyHash, `script` for ScriptHash. + +**Signature** + +```ts +export declare const toBech32: (credential: Credential) => string +``` + +Added in v2.0.0 + ## toCBORBytes Convert a Credential to CBOR bytes. @@ -61,6 +77,18 @@ export declare const toCBORHex: (credential: Credential, options?: CBOR.CodecOpt Added in v2.0.0 +## toHex + +Convert a Credential to a hex string of its hash. + +**Signature** + +```ts +export declare const toHex: (credential: Credential) => string +``` + +Added in v2.0.0 + # model ## Credential (type alias) diff --git a/docs/content/docs/modules/DRep.mdx b/docs/content/docs/modules/DRep.mdx index e3835354..1f3a4938 100644 --- a/docs/content/docs/modules/DRep.mdx +++ b/docs/content/docs/modules/DRep.mdx @@ -1,6 +1,7 @@ --- + title: DRep.ts -nav_order: 55 +nav_order: 56 parent: Modules --- diff --git a/docs/content/docs/modules/DRepCredential.mdx b/docs/content/docs/modules/DRepCredential.mdx index 056cc2d2..a7c53ec6 100644 --- a/docs/content/docs/modules/DRepCredential.mdx +++ b/docs/content/docs/modules/DRepCredential.mdx @@ -1,6 +1,7 @@ --- + title: DRepCredential.ts -nav_order: 56 +nav_order: 57 parent: Modules --- diff --git a/docs/content/docs/modules/Data.mdx b/docs/content/docs/modules/Data.mdx index 81bba2ff..7c339674 100644 --- a/docs/content/docs/modules/Data.mdx +++ b/docs/content/docs/modules/Data.mdx @@ -1,6 +1,7 @@ --- + title: Data.ts -nav_order: 50 +nav_order: 51 parent: Modules --- @@ -20,6 +21,10 @@ parent: Modules - [int](#int) - [list](#list) - [map](#map) +- [encoding](#encoding) + - [spliceConstr](#spliceconstr) + - [spliceList](#splicelist) + - [spliceMap](#splicemap) - [equality](#equality) - [equals](#equals) - [hash](#hash) @@ -39,11 +44,13 @@ parent: Modules - [model](#model) - [Data (type alias)](#data-type-alias) - [DataEncoded (type alias)](#dataencoded-type-alias) + - [Hex (type alias)](#hex-type-alias) - [List (type alias)](#list-type-alias) - [Map (type alias)](#map-type-alias) - [predicates](#predicates) - [isBytes](#isbytes) - [isConstr](#isconstr) + - [isData](#isdata) - [isInt](#isint) - [isList](#islist) - [isMap](#ismap) @@ -53,9 +60,11 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) - [DataSchema](#dataschema) + - [DataValue](#datavalue) - [FromCBORBytes](#fromcborbytes) - [FromCBORHex](#fromcborhex) - [FromCDDL](#fromcddl) + - [Hex](#hex) - [IntSchema](#intschema) - [ListSchema](#listschema) - [MapSchema](#mapschema) @@ -105,7 +114,8 @@ Added in v2.0.0 ## DEFAULT_CBOR_OPTIONS -Default CBOR options for Data encoding/decoding +Default CBOR options for Data encoding/decoding: {@link CBOR.PLUTUS_DATA_OPTIONS}, +the layout the node writes. **Signature** @@ -177,6 +187,73 @@ export declare const map: (entries: Array<[key: Data, value: Data]>) => Map Added in v2.0.0 +# encoding + +## spliceConstr + +A `Constr` over already-encoded fields, in the three tag ranges the Plutus encoding defines. + +⚠️ The tag-102 wrapper `[index, fields]` is DEFINITE while the fields array inside it stays +indefinite. `cardano-serialization-lib` 15.0.3 and `cardano-multiplatform-lib` 6.2 both write +`d866 82 …`; no single codec option can say both, which is why the shape is written here. + +See {@link spliceList} for when to reach for this rather than {@link constr}. + +**Signature** + +```ts +export declare const spliceConstr: (index: bigint, fieldItems: ReadonlyArray) => Uint8Array +``` + +Added in v2.8.0 + +## spliceList + +Assemble `plutus_data` from children that are ALREADY encoded, splicing their bytes. + +⚠️ **Why this exists next to the typed constructors.** {@link fromCBORBytes} records the bytes +every node arrived as and {@link toCBORBytes} replays them, so decoding a child and rebuilding +around it is lossless for anything that can carry a record. One thing cannot: a `bigint` is not +an object, so a non-minimally encoded integer (`19002a` for 42, which the ledger accepts and +nothing here writes) has nowhere to keep its header width. A caller holding encoded children +therefore has a choice between decoding them -- correct except for that integer -- and splicing +them, which is correct for everything. These splice. + +Use the typed constructors ({@link list}, {@link constr}, {@link map}) when the children are +values this process produced. Use these when the children came off a wire and are going back on +one unchanged, which is every datum nested inside another datum. + +The framing matches what the typed encoder writes under the Plutus data options, so the two +routes agree for any child that round-trips: non-empty lists and constructor fields are +indefinite, the empty list is definite, the tag-102 wrapper is definite, and a Plutus map is +definite and keeps the order it was given. + +**Signature** + +```ts +export declare const spliceList: (items: ReadonlyArray) => Uint8Array +``` + +Added in v2.8.0 + +## spliceMap + +A Plutus map over already-encoded keys and values. + +⚠️ Definite-framed, and the entries keep the order given: a Plutus map is NOT sorted. Sorting +it is a different value as far as a script reading it by position is concerned, and a different +hash either way. + +See {@link spliceList} for when to reach for this rather than {@link map}. + +**Signature** + +```ts +export declare const spliceMap: (entries: ReadonlyArray) => Uint8Array +``` + +Added in v2.8.0 + # equality ## equals @@ -326,7 +403,7 @@ Added in v2.0.0 ## toDatumHash Compute the hash of PlutusData using blake2b-256 over its CBOR encoding. -Defaults to CML_DATA_DEFAULT_OPTIONS (indefinite-length arrays/maps). +Defaults to PLUTUS_DATA_OPTIONS, the node layout. **Signature** @@ -428,6 +505,16 @@ export type DataEncoded = Added in v2.0.0 +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + ## List (type alias) PlutusList type alias @@ -478,6 +565,18 @@ export declare const isConstr: (data: unknown) => data is Constr Added in v2.0.0 +## isData + +Whether a value is a {@link Data}, checked structurally and without rebuilding it. + +**Signature** + +```ts +export declare const isData: (input: unknown) => input is Data +``` + +Added in v2.8.0 + ## isInt Type guard to check if a value is a PlutusBigInt @@ -568,24 +667,39 @@ export declare const DataSchema: DataSchema Added in v2.0.0 +## DataValue + +A `Data` checked where it stands, with nothing rebuilt. + +⚠️ **Use this for a class field or any other slot that holds an already-decoded `Data`.** +{@link DataSchema} is a transforming schema, and validating a value through it returns a +STRUCTURAL COPY: a list comes back as a different array holding the same elements. That is +invisible until something keys on identity, and {@link OriginalBytes} does -- so a datum decoded +from the wire and handed to `Redeemer.spend` arrived with its bytes and reached the encoder +without them, which reframed an empty indefinite list and moved `script_data_hash`. + +`Schema.declare` with a type guard performs no transformation, so the value that goes in is the +value that comes out. + +**Signature** + +```ts +export declare const DataValue: Schema.Schema +``` + +Added in v2.8.0 + ## FromCBORBytes CBOR bytes transformation schema for PlutusData using CDDL. -Transforms between CBOR bytes and Data using CDDL encoding. +Decodes through {@link FromCDDL}. Encodes as {@link toCBORBytes} does. **Signature** ```ts export declare const FromCBORBytes: ( options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail, Schema.SchemaClass, never> -> +) => Schema.transformOrFail, never> ``` Added in v2.0.0 @@ -602,14 +716,7 @@ export declare const FromCBORHex: ( options?: CBOR.CodecOptions ) => Schema.transform< Schema.Schema, - Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail, Schema.SchemaClass, never> - > + Schema.transformOrFail, never> > ``` @@ -657,6 +764,24 @@ export declare const FromCDDL: Schema.transformOrFail< Added in v2.0.0 +## Hex + +A `plutus_data` item as CBOR hex. + +⚠️ A script consumer matches a datum by its hash, so these bytes are the value: a re-encoding +that differs by one byte hashes differently. + +Branded so that CBOR hex of one kind cannot stand in for another once it leaves the typed +domain. Non-empty whole bytes is all the shape there is to check. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "PlutusDataHex"> +``` + +Added in v2.4.0 + ## IntSchema Schema for PlutusBigInt data type @@ -725,7 +850,7 @@ Convert CBORValue to PlutusData **Signature** ```ts -export declare const cborValueToPlutusData: (cborValue: CBOR.CBOR) => Data +export declare const cborValueToPlutusData: (cborValue: CBOR.CBOR, fmt?: CBOR.CBORFormat) => Data ``` Added in v2.0.0 @@ -761,26 +886,35 @@ Convert PlutusData to CBORValue **Signature** ```ts -export declare const plutusDataToCBORValue: (data: Data) => CBOR.CBOR +export declare const plutusDataToCBORValue: (data: Data, options?: CBOR.CodecOptions) => CBOR.CBOR ``` Added in v2.0.0 ## toCBORBytes -Encode PlutusData to CBOR bytes +Encode PlutusData to CBOR bytes. + +`options` choose definite or indefinite lists and maps, map key order and +integer widths. These rules hold under every option: + +- A byte string over 64 bytes is written indefinite, in 64-byte chunks. +- An integer from -2^64 to 2^64 - 1 is a CBOR integer. Outside that range it + is a bignum (tag 2 or 3) whose bytes follow the byte string rule. +- A constructor index above 127 is tag 102 over a definite pair + `[index, fields]`; only the fields follow `options`. **Signature** ```ts -export declare const toCBORBytes: (data: Data, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: (data: Data, options?: CBOR.CodecOptions) => Uint8Array ``` Added in v2.0.0 ## toCBORHex -Encode PlutusData to CBOR hex string +Encode PlutusData to CBOR hex string, as {@link toCBORBytes} writes it. **Signature** diff --git a/docs/content/docs/modules/DataJson.mdx b/docs/content/docs/modules/DataJson.mdx index 4f6f69b4..2989cc74 100644 --- a/docs/content/docs/modules/DataJson.mdx +++ b/docs/content/docs/modules/DataJson.mdx @@ -1,6 +1,7 @@ --- + title: DataJson.ts -nav_order: 51 +nav_order: 52 parent: Modules --- diff --git a/docs/content/docs/modules/DatumHash.mdx b/docs/content/docs/modules/DatumHash.mdx index 6b374a80..59c1a865 100644 --- a/docs/content/docs/modules/DatumHash.mdx +++ b/docs/content/docs/modules/DatumHash.mdx @@ -1,6 +1,7 @@ --- + title: DatumHash.ts -nav_order: 52 +nav_order: 53 parent: Modules --- @@ -12,10 +13,10 @@ parent: Modules - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) +- [model](#model) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isDatumHash](#isdatumhash) - [schemas](#schemas) @@ -26,9 +27,13 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) - [testing](#testing) - [arbitrary](#arbitrary) +- [utils](#utils) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -46,17 +51,17 @@ export declare const toBytes: (a: DatumHash, overrideOptions?: ParseOptions) => Added in v2.0.0 -## toHex +# model -Encode DatumHash to hex string. +## Hex (type alias) **Signature** ```ts -export declare const toHex: (a: DatumHash, overrideOptions?: ParseOptions) => string +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 # parsing @@ -72,18 +77,6 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex - -Parse DatumHash from hex string. - -**Signature** - -```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => DatumHash -``` - -Added in v2.0.0 - # predicates ## isDatumHash @@ -192,6 +185,24 @@ export declare const FromHex: Schema.transform< Added in v2.0.0 +## Hex + +A datum hash as hex. + +Validated as well as branded: a 32-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Same shape as a transaction hash. A script consumer matches a datum by this value, so the +two being interchangeable as `string` was a real hazard. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "DatumHashHex"> +``` + +Added in v2.4.0 + # testing ## arbitrary @@ -205,3 +216,21 @@ export declare const arbitrary: FastCheck.Arbitrary ``` Added in v2.0.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => DatumHash +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/DatumOption.mdx b/docs/content/docs/modules/DatumOption.mdx index 68fd9b62..c4ec2974 100644 --- a/docs/content/docs/modules/DatumOption.mdx +++ b/docs/content/docs/modules/DatumOption.mdx @@ -1,6 +1,7 @@ --- + title: DatumOption.ts -nav_order: 53 +nav_order: 54 parent: Modules --- @@ -26,6 +27,7 @@ parent: Modules - [FromCBORBytes](#fromcborbytes-1) - [FromCBORHex](#fromcborhex-1) - [FromCDDL](#fromcddl) + - [makeFromCDDL](#makefromcddl) - [testing](#testing) - [arbitrary](#arbitrary) - [utils](#utils) @@ -74,7 +76,7 @@ Convert DatumOption to CBOR bytes. **Signature** ```ts -export declare const toCBORBytes: (data: DatumOption, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: (data: DatumOption, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => any ``` Added in v2.0.0 @@ -86,7 +88,7 @@ Convert DatumOption to CBOR hex. **Signature** ```ts -export declare const toCBORHex: (data: DatumOption, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (data: DatumOption, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 @@ -161,11 +163,15 @@ Added in v2.0.0 CBOR bytes transformation schema for DatumOption. Transforms between Uint8Array and DatumOption using CBOR encoding. +A new inline datum is written with the `plutusData` options, the rest with +the `ledger` options. Plain options are read as `CBOR.toTxCodecOptions` +reads them. + **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, @@ -196,14 +202,13 @@ Added in v2.0.0 ## FromCBORHex -CBOR hex transformation schema for DatumOption. -Transforms between hex string and DatumOption using CBOR encoding. +CBOR hex transformation schema for DatumOption, as in {@link FromCBORBytes}. **Signature** ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.Schema, Schema.transform< @@ -245,6 +250,8 @@ Where: - [0, Bytes32] represents a datum hash (tag 0 with 32-byte hash) - [1, #6.24(bytes)] represents inline data (tag 1 with CBOR tag 24 containing plutus data as bytes) +A new inline datum is written with `Data.DEFAULT_CBOR_OPTIONS`. + **Signature** ```ts @@ -269,6 +276,38 @@ export declare const FromCDDL: Schema.transformOrFail< Added in v2.0.0 +## makeFromCDDL + +CDDL schema for DatumOption, as in {@link FromCDDL}, that writes a new +inline datum with the `plutusData` options. A decoded inline datum keeps +its original bytes. + +**Signature** + +```ts +export declare const makeFromCDDL: ( + plutusData: CBOR.CodecOptions +) => Schema.transformOrFail< + Schema.Union< + [ + Schema.Tuple2, typeof Schema.Uint8ArrayFromSelf>, + Schema.Tuple2< + Schema.Literal<[1n]>, + Schema.TaggedStruct<"Tag", { tag: Schema.Literal<[24]>; value: typeof Schema.Uint8ArrayFromSelf }> + > + ] + >, + Schema.SchemaClass< + DatumHash.DatumHash | InlineDatum.InlineDatum, + DatumHash.DatumHash | InlineDatum.InlineDatum, + never + >, + never +> +``` + +Added in v2.0.0 + # testing ## arbitrary diff --git a/docs/content/docs/modules/DnsName.mdx b/docs/content/docs/modules/DnsName.mdx index 1c4617bc..7249b536 100644 --- a/docs/content/docs/modules/DnsName.mdx +++ b/docs/content/docs/modules/DnsName.mdx @@ -1,6 +1,7 @@ --- + title: DnsName.ts -nav_order: 54 +nav_order: 55 parent: Modules --- diff --git a/docs/content/docs/modules/Ed25519Signature.mdx b/docs/content/docs/modules/Ed25519Signature.mdx index 118ecf7c..c04bf766 100644 --- a/docs/content/docs/modules/Ed25519Signature.mdx +++ b/docs/content/docs/modules/Ed25519Signature.mdx @@ -1,6 +1,7 @@ --- + title: Ed25519Signature.ts -nav_order: 57 +nav_order: 58 parent: Modules --- @@ -14,10 +15,8 @@ parent: Modules - [arbitrary](#arbitrary-1) - [constructors](#constructors) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) - [Ed25519Signature (class)](#ed25519signature-class) - [toJSON (method)](#tojson-method) @@ -25,11 +24,16 @@ parent: Modules - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) + - [Hex (type alias)](#hex-type-alias) - [predicates](#predicates) - [is](#is) - [schemas](#schemas) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) +- [utils](#utils) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -61,18 +65,6 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex - -Parse Ed25519Signature from hex string (unsafe - throws on error). - -**Signature** - -```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Ed25519Signature -``` - -Added in v2.0.0 - # encoding ## toBytes @@ -87,18 +79,6 @@ export declare const toBytes: (a: Ed25519Signature, overrideOptions?: ParseOptio Added in v2.0.0 -## toHex - -Convert to hex string using optimized lookup table. - -**Signature** - -```ts -export declare const toHex: (a: Ed25519Signature, overrideOptions?: ParseOptions) => string -``` - -Added in v2.0.0 - # model ## Ed25519Signature (class) @@ -155,6 +135,16 @@ toString(): string [Hash.symbol](): number ``` +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + # predicates ## is @@ -203,3 +193,40 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +## Hex + +An Ed25519 signature as hex (64 bytes). + +Validated as well as branded: a 64-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Branded apart from a verification key because a `vkeywitness` holds exactly those two, in +that order, and transposing them yields a witness that is structurally valid and verifies +against nothing. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "Ed25519SignatureHex"> +``` + +Added in v2.4.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => Ed25519Signature +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/EffectRuntime.mdx b/docs/content/docs/modules/EffectRuntime.mdx index 19231a1e..aa6c9eea 100644 --- a/docs/content/docs/modules/EffectRuntime.mdx +++ b/docs/content/docs/modules/EffectRuntime.mdx @@ -1,6 +1,7 @@ --- + title: EffectRuntime.ts -nav_order: 58 +nav_order: 59 parent: Modules --- diff --git a/docs/content/docs/modules/EnterpriseAddress.mdx b/docs/content/docs/modules/EnterpriseAddress.mdx index 98417fa9..acaac3ad 100644 --- a/docs/content/docs/modules/EnterpriseAddress.mdx +++ b/docs/content/docs/modules/EnterpriseAddress.mdx @@ -1,6 +1,7 @@ --- + title: EnterpriseAddress.ts -nav_order: 59 +nav_order: 60 parent: Modules --- diff --git a/docs/content/docs/modules/EpochNo.mdx b/docs/content/docs/modules/EpochNo.mdx index 0f2ff6fc..79c197e4 100644 --- a/docs/content/docs/modules/EpochNo.mdx +++ b/docs/content/docs/modules/EpochNo.mdx @@ -1,6 +1,7 @@ --- + title: EpochNo.ts -nav_order: 60 +nav_order: 61 parent: Modules --- diff --git a/docs/content/docs/modules/FeeValidation.mdx b/docs/content/docs/modules/FeeValidation.mdx index 0debebb8..24ba1e9c 100644 --- a/docs/content/docs/modules/FeeValidation.mdx +++ b/docs/content/docs/modules/FeeValidation.mdx @@ -1,6 +1,7 @@ --- + title: FeeValidation.ts -nav_order: 61 +nav_order: 63 parent: Modules --- diff --git a/docs/content/docs/modules/Fees.mdx b/docs/content/docs/modules/Fees.mdx new file mode 100644 index 00000000..5f7582c5 --- /dev/null +++ b/docs/content/docs/modules/Fees.mdx @@ -0,0 +1,96 @@ +--- + +title: Fees.ts +nav_order: 62 +parent: Modules +--- + +## Fees overview + +The Conway fee components the linear `minFeeA * size + minFeeB` does not cover. + +A transaction carrying redeemers or reference scripts owes these on top of the linear fee, and +a builder that charges only the linear part underpays — the node then rejects it. + +⚠️ Every value here is computed in exact rational arithmetic. The execution prices and the +tier multiplier are rationals in the ledger and decimals on the wire, and `0.0577`, +`0.0000721` and `1.2` are none of them representable in binary floating point — so a fee that +passes through a `number` is a fee computed from a value the chain never specified. + +Added in v2.5.0 + +--- + +

Table of contents

+ +- [constants](#constants) + - [MAX_REF_SCRIPT_SIZE](#max_ref_script_size) +- [fee-calculation](#fee-calculation) + - [refScriptFee](#refscriptfee) + - [scriptExecutionFee](#scriptexecutionfee) + +--- + +# constants + +## MAX_REF_SCRIPT_SIZE + +The Conway reference-script ceiling: `maxRefScriptSizePerTx`, 200 KiB. + +Hardcoded in the Conway era and a protocol parameter from Dijkstra on. A transaction above it +is invalid, so there is no fee to report for one. + +**Signature** + +```ts +export declare const MAX_REF_SCRIPT_SIZE: 204800n +``` + +Added in v2.5.0 + +# fee-calculation + +## refScriptFee + +Conway tiered reference-script fee, over exact rationals. + +The base rate applies to the first `sizeIncrement` bytes and is multiplied by `multiplier` +for each tier after it, with a single `floor` of the accumulated total at the end — which is +what the ledger does. The accumulation never passes through a `number`, because from the +third tier on the per-byte price stops being an integer and a double drifts off the exact +value by enough to land a lovelace under the fee minimum. + +Defaults are the Conway constants: 1.2× per 25,600 bytes. + +**Signature** + +```ts +export declare const refScriptFee: ( + totalSize: bigint, + costPerByte: NonnegativeInterval.NonnegativeInterval, + options?: { readonly multiplier?: NonnegativeInterval.NonnegativeInterval; readonly sizeIncrement?: bigint } +) => bigint +``` + +Added in v2.5.0 + +## scriptExecutionFee + +Conway script-execution fee: `⌈priceMem * totalMem + priceStep * totalSteps⌉`. + +The two prices are combined BEFORE the single ceiling, which is what the ledger's +`txscriptfee` does over a transaction's total execution units — so this is not the sum of two +independently rounded terms, and not a per-redeemer sum of those either. + +**Signature** + +```ts +export declare const scriptExecutionFee: ( + priceMem: NonnegativeInterval.NonnegativeInterval, + priceStep: NonnegativeInterval.NonnegativeInterval, + totalMem: bigint, + totalSteps: bigint +) => bigint +``` + +Added in v2.5.0 diff --git a/docs/content/docs/modules/GovernanceAction.mdx b/docs/content/docs/modules/GovernanceAction.mdx index dd640e8a..b71071f3 100644 --- a/docs/content/docs/modules/GovernanceAction.mdx +++ b/docs/content/docs/modules/GovernanceAction.mdx @@ -1,6 +1,7 @@ --- + title: GovernanceAction.ts -nav_order: 62 +nav_order: 64 parent: Modules --- @@ -13,6 +14,7 @@ parent: Modules - [arbitrary](#arbitrary) - [infoArbitrary](#infoarbitrary) - [encoding](#encoding) + - [govActionIdToCBORHex](#govactionidtocborhex) - [toCBOR](#tocbor) - [toCBORHex](#tocborhex) - [model](#model) @@ -20,6 +22,7 @@ parent: Modules - [parsing](#parsing) - [fromCBOR](#fromcbor) - [fromCBORHex](#fromcborhex) + - [govActionIdFromCBORHex](#govactionidfromcborhex) - [pattern matching](#pattern-matching) - [match](#match) - [predicates](#predicates) @@ -128,6 +131,21 @@ Added in v2.0.0 # encoding +## govActionIdToCBORHex + +Codec pair for a standalone `GovActionId`. + +It identifies a governance action everywhere one is referenced, so it is addressable on its +own, but only its CDDL transform was exported. + +**Signature** + +```ts +export declare const govActionIdToCBORHex: (input: GovActionId, options?: CBOR.CodecOptions) => string +``` + +Added in v2.0.0 + ## toCBOR Encode GovernanceAction to CBOR bytes. @@ -192,6 +210,16 @@ export declare const fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => Added in v2.0.0 +## govActionIdFromCBORHex + +**Signature** + +```ts +export declare const govActionIdFromCBORHex: (hex: string, options?: CBOR.CodecOptions) => GovActionId +``` + +Added in v2.0.0 + # pattern matching ## match diff --git a/docs/content/docs/modules/Hash28.mdx b/docs/content/docs/modules/Hash28.mdx index 60ca9fa9..2ed2c34c 100644 --- a/docs/content/docs/modules/Hash28.mdx +++ b/docs/content/docs/modules/Hash28.mdx @@ -1,6 +1,7 @@ --- + title: Hash28.ts -nav_order: 63 +nav_order: 65 parent: Modules --- diff --git a/docs/content/docs/modules/Header.mdx b/docs/content/docs/modules/Header.mdx index 1b366080..d3968d66 100644 --- a/docs/content/docs/modules/Header.mdx +++ b/docs/content/docs/modules/Header.mdx @@ -1,6 +1,7 @@ --- + title: Header.ts -nav_order: 64 +nav_order: 66 parent: Modules --- diff --git a/docs/content/docs/modules/HeaderBody.mdx b/docs/content/docs/modules/HeaderBody.mdx index c36a70d7..0e812e0c 100644 --- a/docs/content/docs/modules/HeaderBody.mdx +++ b/docs/content/docs/modules/HeaderBody.mdx @@ -1,6 +1,7 @@ --- + title: HeaderBody.ts -nav_order: 65 +nav_order: 67 parent: Modules --- diff --git a/docs/content/docs/modules/IPv4.mdx b/docs/content/docs/modules/IPv4.mdx index 76478df3..14bf1aab 100644 --- a/docs/content/docs/modules/IPv4.mdx +++ b/docs/content/docs/modules/IPv4.mdx @@ -1,6 +1,7 @@ --- + title: IPv4.ts -nav_order: 67 +nav_order: 69 parent: Modules --- diff --git a/docs/content/docs/modules/IPv6.mdx b/docs/content/docs/modules/IPv6.mdx index 81453bc0..97902314 100644 --- a/docs/content/docs/modules/IPv6.mdx +++ b/docs/content/docs/modules/IPv6.mdx @@ -1,6 +1,7 @@ --- + title: IPv6.ts -nav_order: 68 +nav_order: 70 parent: Modules --- diff --git a/docs/content/docs/modules/InlineDatum.mdx b/docs/content/docs/modules/InlineDatum.mdx index c252312d..a618900b 100644 --- a/docs/content/docs/modules/InlineDatum.mdx +++ b/docs/content/docs/modules/InlineDatum.mdx @@ -1,6 +1,7 @@ --- + title: InlineDatum.ts -nav_order: 66 +nav_order: 68 parent: Modules --- @@ -10,6 +11,9 @@ parent: Modules

Table of contents

+- [constructors](#constructors) + - [fromCBORBytes](#fromcborbytes) + - [fromCBORHex](#fromcborhex) - [predicates](#predicates) - [isInlineDatum](#isinlinedatum) - [schemas](#schemas) @@ -24,6 +28,42 @@ parent: Modules --- +# constructors + +## fromCBORBytes + +As {@link fromCBORHex}, for bytes already decoded from the wire. + +**Signature** + +```ts +export declare const fromCBORBytes: (bytes: Uint8Array) => InlineDatum +``` + +Added in v2.7.0 + +## fromCBORHex + +An inline datum from the CBOR a backend sent, KEEPING those bytes. + +⚠️ **Use this, not the constructor, for any datum that came off a wire.** `new InlineDatum(…)` +records nothing, so the datum's only remaining representation is the decoded tree -- and +re-deriving bytes from a tree reframes an EMPTY indefinite array (`9fff` becomes `80`), which +changes the hash. A script consumer matches a datum BY its hash, and `cip113`/`cip139` report +`datum_hex` only from the `OriginalBytes` channel, absent rather than re-derived. + +Every provider that reads a datum off a backend goes through here, so "the bytes survive" is +one decision in one place rather than four copies that can each be forgotten -- which is how +three of those four came to drop them. + +**Signature** + +```ts +export declare const fromCBORHex: (hex: string) => InlineDatum +``` + +Added in v2.7.0 + # predicates ## isInlineDatum diff --git a/docs/content/docs/modules/KESVkey.mdx b/docs/content/docs/modules/KESVkey.mdx index cf21874d..93fda8fa 100644 --- a/docs/content/docs/modules/KESVkey.mdx +++ b/docs/content/docs/modules/KESVkey.mdx @@ -1,6 +1,7 @@ --- + title: KESVkey.ts -nav_order: 70 +nav_order: 72 parent: Modules --- diff --git a/docs/content/docs/modules/KesSignature.mdx b/docs/content/docs/modules/KesSignature.mdx index 797bc2bb..290bdeb8 100644 --- a/docs/content/docs/modules/KesSignature.mdx +++ b/docs/content/docs/modules/KesSignature.mdx @@ -1,6 +1,7 @@ --- + title: KesSignature.ts -nav_order: 69 +nav_order: 71 parent: Modules --- diff --git a/docs/content/docs/modules/KeyHash.mdx b/docs/content/docs/modules/KeyHash.mdx index f94cec26..bca71902 100644 --- a/docs/content/docs/modules/KeyHash.mdx +++ b/docs/content/docs/modules/KeyHash.mdx @@ -1,6 +1,7 @@ --- + title: KeyHash.ts -nav_order: 71 +nav_order: 73 parent: Modules --- @@ -16,20 +17,27 @@ parent: Modules - [fromPrivateKey](#fromprivatekey) - [fromVKey](#fromvkey) - [encoding/decoding](#encodingdecoding) + - [fromBech32](#frombech32) - [fromBytes](#frombytes) - - [fromHex](#fromhex) + - [toBech32](#tobech32) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) + - [Hex (type alias)](#hex-type-alias) - [KeyHash (class)](#keyhash-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) +- [schemas](#schemas) + - [Hex](#hex) - [transformer](#transformer) + - [FromBech32](#frombech32-1) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) +- [utils](#utils) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -75,6 +83,18 @@ Added in v2.0.0 # encoding/decoding +## fromBech32 + +Parse a KeyHash from a bech32 string (addr_vkh1...). + +**Signature** + +```ts +export declare const fromBech32: (i: string, overrideOptions?: ParseOptions) => KeyHash +``` + +Added in v2.0.0 + ## fromBytes Decode a KeyHash from raw bytes. @@ -87,14 +107,14 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex +## toBech32 -Decode a KeyHash from a hex string. +Convert a KeyHash to a bech32 string (addr_vkh1...). **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => KeyHash +export declare const toBech32: (a: KeyHash, overrideOptions?: ParseOptions) => string ``` Added in v2.0.0 @@ -111,19 +131,17 @@ export declare const toBytes: (a: KeyHash, overrideOptions?: ParseOptions) => Ui Added in v2.0.0 -## toHex +# model -Convert a KeyHash to a hex string. +## Hex (type alias) **Signature** ```ts -export declare const toHex: (a: KeyHash, overrideOptions?: ParseOptions) => string +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 - -# model +Added in v2.4.0 ## KeyHash (class) @@ -183,8 +201,45 @@ toString(): string [Hash.symbol](): number ``` +# schemas + +## Hex + +An Ed25519 key hash as hex. + +Validated as well as branded: a 28-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Same shape as a script hash and a policy id, all three 28 bytes. A credential of the wrong +kind travels a long way before anything notices. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "KeyHashHex"> +``` + +Added in v2.4.0 + # transformer +## FromBech32 + +Schema transformer from bech32 string (addr_vkh1...) to KeyHash. +Uses the CIP-0005 `addr_vkh` prefix for address verification key hashes. + +**Signature** + +```ts +export declare const FromBech32: Schema.transformOrFail< + typeof Schema.String, + Schema.SchemaClass, + never +> +``` + +Added in v2.0.0 + ## FromBytes Schema transformer from bytes to KeyHash. @@ -214,3 +269,21 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => KeyHash +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/Label.mdx b/docs/content/docs/modules/Label.mdx index 5f8de512..cd72f2ca 100644 --- a/docs/content/docs/modules/Label.mdx +++ b/docs/content/docs/modules/Label.mdx @@ -1,6 +1,7 @@ --- + title: Label.ts -nav_order: 72 +nav_order: 74 parent: Modules --- diff --git a/docs/content/docs/modules/Language.mdx b/docs/content/docs/modules/Language.mdx index 6c2f28ac..7d91da3e 100644 --- a/docs/content/docs/modules/Language.mdx +++ b/docs/content/docs/modules/Language.mdx @@ -1,6 +1,7 @@ --- + title: Language.ts -nav_order: 73 +nav_order: 75 parent: Modules --- diff --git a/docs/content/docs/modules/Metadata.mdx b/docs/content/docs/modules/Metadata.mdx index d2193a75..50258855 100644 --- a/docs/content/docs/modules/Metadata.mdx +++ b/docs/content/docs/modules/Metadata.mdx @@ -1,6 +1,7 @@ --- + title: Metadata.ts -nav_order: 74 +nav_order: 76 parent: Modules --- diff --git a/docs/content/docs/modules/MinAda.mdx b/docs/content/docs/modules/MinAda.mdx new file mode 100644 index 00000000..02ee37b5 --- /dev/null +++ b/docs/content/docs/modules/MinAda.mdx @@ -0,0 +1,77 @@ +--- + +title: MinAda.ts +nav_order: 77 +parent: Modules +--- + +## MinAda overview + +Minimum lovelace for a transaction output. + +A UTxO must hold at least `(160 + its serialized size) * coinsPerUtxoByte`, and the value is a +fixed point: raising the coin can widen its own CBOR encoding, which raises the size, which +raises the coin. The loop below solves it the way the ledger's own sizing does. + +This lived inside `sdk/builders/internal/txBuilder` where a wallet could not reach it, so +anyone balancing a transaction outside the builder had to reimplement it — and an +under-estimate produces outputs a node rejects. `calculateMinimumUtxoLovelace` in the builder +now delegates here, so there is one implementation. + +Added in v2.0.0 + +--- + +

Table of contents

+ +- [constants](#constants) + - [MAX_ITERATIONS](#max_iterations) + - [UTXO_ENTRY_OVERHEAD_BYTES](#utxo_entry_overhead_bytes) +- [transformation](#transformation) + - [forOutput](#foroutput) + +--- + +# constants + +## MAX_ITERATIONS + +Iteration cap for the fixed point. It converges in two or three passes in practice; the cap +only exists so a pathological input fails instead of spinning. + +**Signature** + +```ts +export declare const MAX_ITERATIONS: 8 +``` + +Added in v2.0.0 + +## UTXO_ENTRY_OVERHEAD_BYTES + +Per-UTxO overhead in bytes, from the Babbage spec (figure 5, UTxO entry size). + +**Signature** + +```ts +export declare const UTXO_ENTRY_OVERHEAD_BYTES: 160n +``` + +Added in v2.0.0 + +# transformation + +## forOutput + +The minimum lovelace `output` must hold at `coinsPerUtxoByte`. + +The output's own coin is ignored — it is what we are solving for — but its address, assets, +datum, script reference and encoding format all affect the size and so the answer. + +**Signature** + +```ts +export declare const forOutput: (output: TxOut.TransactionOutput, coinsPerUtxoByte: bigint) => bigint +``` + +Added in v2.0.0 diff --git a/docs/content/docs/modules/Mint.mdx b/docs/content/docs/modules/Mint.mdx index 1e955c41..5aabd206 100644 --- a/docs/content/docs/modules/Mint.mdx +++ b/docs/content/docs/modules/Mint.mdx @@ -1,6 +1,7 @@ --- + title: Mint.ts -nav_order: 75 +nav_order: 78 parent: Modules --- diff --git a/docs/content/docs/modules/MultiAsset.mdx b/docs/content/docs/modules/MultiAsset.mdx index 8eb64088..e56c0494 100644 --- a/docs/content/docs/modules/MultiAsset.mdx +++ b/docs/content/docs/modules/MultiAsset.mdx @@ -1,6 +1,7 @@ --- + title: MultiAsset.ts -nav_order: 76 +nav_order: 79 parent: Modules --- diff --git a/docs/content/docs/modules/MultiHostName.mdx b/docs/content/docs/modules/MultiHostName.mdx index 9f65c583..154c7987 100644 --- a/docs/content/docs/modules/MultiHostName.mdx +++ b/docs/content/docs/modules/MultiHostName.mdx @@ -1,6 +1,7 @@ --- + title: MultiHostName.ts -nav_order: 77 +nav_order: 80 parent: Modules --- diff --git a/docs/content/docs/modules/NativeScriptJSON.mdx b/docs/content/docs/modules/NativeScriptJSON.mdx index 3850376c..7c9f78be 100644 --- a/docs/content/docs/modules/NativeScriptJSON.mdx +++ b/docs/content/docs/modules/NativeScriptJSON.mdx @@ -1,6 +1,7 @@ --- + title: NativeScriptJSON.ts -nav_order: 78 +nav_order: 81 parent: Modules --- diff --git a/docs/content/docs/modules/NativeScripts.mdx b/docs/content/docs/modules/NativeScripts.mdx index 7ecfac67..bbad1bd4 100644 --- a/docs/content/docs/modules/NativeScripts.mdx +++ b/docs/content/docs/modules/NativeScripts.mdx @@ -1,6 +1,7 @@ --- + title: NativeScripts.ts -nav_order: 79 +nav_order: 82 parent: Modules --- @@ -18,6 +19,7 @@ parent: Modules - [makeScriptNOfK](#makescriptnofk) - [makeScriptPubKey](#makescriptpubkey) - [conversion](#conversion) + - [fromJSON](#fromjson) - [toJSON](#tojson) - [encoding](#encoding) - [toCBORBytes](#tocborbytes) @@ -127,14 +129,36 @@ Added in v2.0.0 # conversion +## fromJSON + +Build a native script from the cardano-cli JSON representation — the inverse of {@link toJSON}. + +⚠️ `before` and `after` are the JSON form's names, and they are the **opposite** way round from +the CDDL's: `before` is `InvalidHereafter` (valid only _before_ that slot) and `after` is +`InvalidBefore`. Getting the pair backwards builds a script that locks when it should open. + +Each node is built through the smart constructors, so `keyHash` is validated as a 28-byte hash +rather than taken on trust. + +**Signature** + +```ts +export declare const fromJSON: (json: NativeScriptJSON.NativeJSON) => NativeScriptVariants +``` + +Added in v2.0.0 + ## toJSON Convert a NativeScript to JSON representation matching cardano-cli format +Throws if `slot` or `required` exceeds `Number.MAX_SAFE_INTEGER`, which the JSON form cannot +carry exactly. {@link fromJSON} is the inverse. + **Signature** ```ts -export declare const toJSON: (script: NativeScriptVariants) => any +export declare const toJSON: (script: NativeScriptVariants) => NativeScriptJSON.NativeJSON ``` Added in v2.0.0 diff --git a/docs/content/docs/modules/Natural.mdx b/docs/content/docs/modules/Natural.mdx index f42dd0b9..43b9cb36 100644 --- a/docs/content/docs/modules/Natural.mdx +++ b/docs/content/docs/modules/Natural.mdx @@ -1,6 +1,7 @@ --- + title: Natural.ts -nav_order: 80 +nav_order: 83 parent: Modules --- diff --git a/docs/content/docs/modules/Network.mdx b/docs/content/docs/modules/Network.mdx index 2921a848..67ae79f6 100644 --- a/docs/content/docs/modules/Network.mdx +++ b/docs/content/docs/modules/Network.mdx @@ -1,6 +1,7 @@ --- + title: Network.ts -nav_order: 81 +nav_order: 84 parent: Modules --- diff --git a/docs/content/docs/modules/NetworkId.mdx b/docs/content/docs/modules/NetworkId.mdx index 71bc9ed4..e9dbd1ef 100644 --- a/docs/content/docs/modules/NetworkId.mdx +++ b/docs/content/docs/modules/NetworkId.mdx @@ -1,6 +1,7 @@ --- + title: NetworkId.ts -nav_order: 82 +nav_order: 85 parent: Modules --- diff --git a/docs/content/docs/modules/NonZeroInt64.mdx b/docs/content/docs/modules/NonZeroInt64.mdx index c4327f0c..66c4bb18 100644 --- a/docs/content/docs/modules/NonZeroInt64.mdx +++ b/docs/content/docs/modules/NonZeroInt64.mdx @@ -1,6 +1,7 @@ --- + title: NonZeroInt64.ts -nav_order: 84 +nav_order: 87 parent: Modules --- diff --git a/docs/content/docs/modules/NonnegativeInterval.mdx b/docs/content/docs/modules/NonnegativeInterval.mdx index 4335fb7d..a8629738 100644 --- a/docs/content/docs/modules/NonnegativeInterval.mdx +++ b/docs/content/docs/modules/NonnegativeInterval.mdx @@ -1,6 +1,7 @@ --- + title: NonnegativeInterval.ts -nav_order: 83 +nav_order: 86 parent: Modules --- @@ -10,6 +11,8 @@ parent: Modules

Table of contents

+- [constructors](#constructors) + - [fromDecimal](#fromdecimal) - [model](#model) - [NonnegativeInterval (class)](#nonnegativeinterval-class) - [toJSON (method)](#tojson-method) @@ -23,9 +26,46 @@ parent: Modules - [FromCBORHex](#fromcborhex) - [FromCDDL](#fromcddl) - [arbitrary](#arbitrary) + - [ceilDiv](#ceildiv) --- +# constructors + +## fromDecimal + +An exact rational from a decimal, with no floating-point step in between. + +Protocol parameters that are rationals in the ledger arrive as decimals over JSON: +`priceMem` is `0.0577`, `treasuryCut` is `0.2`. ⚠️ **None of those is representable in +binary floating point**, so arithmetic that goes through a `number` is arithmetic on a +value the chain never specified — and a fee rounded from it can land below the minimum +the node computed from the exact rational, which is a rejected transaction rather than a +rounding curiosity. + +A `number` is read through its shortest round-tripping decimal (`String(0.0577)` is +`"0.0577"`), which recovers the decimal that was written rather than the binary value it +became: `0.0577` yields `577/10000`, not the dyadic expansion of the nearest double. Pass +a string when the source is text, which skips the double entirely. + +**Signature** + +```ts +export declare const fromDecimal: (value: number | string) => NonnegativeInterval +``` + +**Example** + +```typescript +import * as NonnegativeInterval from "@evolution-sdk/evolution/NonnegativeInterval" + +NonnegativeInterval.fromDecimal(0.0577) // 577/10000 +NonnegativeInterval.fromDecimal("1.2") // 6/5 +NonnegativeInterval.fromDecimal(15) // 15/1 +``` + +Added in v2.5.0 + # model ## NonnegativeInterval (class) @@ -190,3 +230,15 @@ export declare const FromCDDL: Schema.transformOrFail< ```ts export declare const arbitrary: FastCheck.Arbitrary ``` + +## ceilDiv + +Ceiling division for non-negative bigints — `⌈num / den⌉` with no float in the middle. + +**Signature** + +```ts +export declare const ceilDiv: (numerator: bigint, denominator: bigint) => bigint +``` + +Added in v2.5.0 diff --git a/docs/content/docs/modules/Numeric.mdx b/docs/content/docs/modules/Numeric.mdx index a034292f..9a50c8b4 100644 --- a/docs/content/docs/modules/Numeric.mdx +++ b/docs/content/docs/modules/Numeric.mdx @@ -1,6 +1,7 @@ --- + title: Numeric.ts -nav_order: 85 +nav_order: 88 parent: Modules --- diff --git a/docs/content/docs/modules/OperationalCert.mdx b/docs/content/docs/modules/OperationalCert.mdx index 84f203e7..8921b2b0 100644 --- a/docs/content/docs/modules/OperationalCert.mdx +++ b/docs/content/docs/modules/OperationalCert.mdx @@ -1,6 +1,7 @@ --- + title: OperationalCert.ts -nav_order: 86 +nav_order: 89 parent: Modules --- diff --git a/docs/content/docs/modules/OriginalBytes.mdx b/docs/content/docs/modules/OriginalBytes.mdx new file mode 100644 index 00000000..d794aefe --- /dev/null +++ b/docs/content/docs/modules/OriginalBytes.mdx @@ -0,0 +1,57 @@ +--- + +title: OriginalBytes.ts +nav_order: 90 +parent: Modules +--- + +## OriginalBytes overview + +Keeps the exact bytes a value was decoded from. + +The ledger hashes and signs the original bytes of a value, not a fresh +encoding of it. A decoder records the bytes it read against the object it +returns. An encoder that finds recorded bytes for the object it is given +writes those bytes back unchanged. A new or edited value is a new object, +so it has no recorded bytes and gets the default encoding. + +Entries are held in a WeakMap, so they are released with their object. + +Added in v2.0.0 + +--- + +

Table of contents

+ +- [cache](#cache) + - [get](#get) + - [record](#record) + +--- + +# cache + +## get + +Get the bytes that `value` was decoded from, if any were recorded. + +**Signature** + +```ts +export declare const get: (value: object) => Uint8Array | undefined +``` + +Added in v2.0.0 + +## record + +Record the bytes that `value` was decoded from. The bytes are copied, so a +caller that later changes its input buffer does not change the record. + +**Signature** + +```ts +export declare const record: (value: A, bytes: Uint8Array) => A +``` + +Added in v2.0.0 diff --git a/docs/content/docs/modules/PaymentAddress.mdx b/docs/content/docs/modules/PaymentAddress.mdx index ca3d1d98..8af73666 100644 --- a/docs/content/docs/modules/PaymentAddress.mdx +++ b/docs/content/docs/modules/PaymentAddress.mdx @@ -1,6 +1,7 @@ --- + title: PaymentAddress.ts -nav_order: 87 +nav_order: 91 parent: Modules --- diff --git a/docs/content/docs/modules/PlutusV1.mdx b/docs/content/docs/modules/PlutusV1.mdx index a044b08c..36d95373 100644 --- a/docs/content/docs/modules/PlutusV1.mdx +++ b/docs/content/docs/modules/PlutusV1.mdx @@ -1,6 +1,7 @@ --- + title: PlutusV1.ts -nav_order: 93 +nav_order: 97 parent: Modules --- diff --git a/docs/content/docs/modules/PlutusV2.mdx b/docs/content/docs/modules/PlutusV2.mdx index c2d35267..af96375f 100644 --- a/docs/content/docs/modules/PlutusV2.mdx +++ b/docs/content/docs/modules/PlutusV2.mdx @@ -1,6 +1,7 @@ --- + title: PlutusV2.ts -nav_order: 94 +nav_order: 98 parent: Modules --- diff --git a/docs/content/docs/modules/PlutusV3.mdx b/docs/content/docs/modules/PlutusV3.mdx index feea769a..095ba9a3 100644 --- a/docs/content/docs/modules/PlutusV3.mdx +++ b/docs/content/docs/modules/PlutusV3.mdx @@ -1,6 +1,7 @@ --- + title: PlutusV3.ts -nav_order: 95 +nav_order: 99 parent: Modules --- diff --git a/docs/content/docs/modules/Pointer.mdx b/docs/content/docs/modules/Pointer.mdx index f0143da2..69363ab2 100644 --- a/docs/content/docs/modules/Pointer.mdx +++ b/docs/content/docs/modules/Pointer.mdx @@ -1,6 +1,7 @@ --- + title: Pointer.ts -nav_order: 96 +nav_order: 100 parent: Modules --- diff --git a/docs/content/docs/modules/PointerAddress.mdx b/docs/content/docs/modules/PointerAddress.mdx index fbc03d16..e3ef7125 100644 --- a/docs/content/docs/modules/PointerAddress.mdx +++ b/docs/content/docs/modules/PointerAddress.mdx @@ -1,6 +1,7 @@ --- + title: PointerAddress.ts -nav_order: 97 +nav_order: 101 parent: Modules --- @@ -40,7 +41,7 @@ parent: Modules Smart constructor for creating PointerAddress instances -/\*\* +/** FastCheck arbitrary for generating random PointerAddress instances **Signature** diff --git a/docs/content/docs/modules/PolicyId.mdx b/docs/content/docs/modules/PolicyId.mdx index 2c1cc532..11d2f81b 100644 --- a/docs/content/docs/modules/PolicyId.mdx +++ b/docs/content/docs/modules/PolicyId.mdx @@ -1,6 +1,7 @@ --- + title: PolicyId.ts -nav_order: 98 +nav_order: 102 parent: Modules --- @@ -14,8 +15,8 @@ parent: Modules - [arbitrary](#arbitrary-1) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) + - [Hex (type alias)](#hex-type-alias) - [PolicyId (class)](#policyid-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) @@ -24,12 +25,15 @@ parent: Modules - [[Hash.symbol] (method)](#hashsymbol-method) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isPolicyId](#ispolicyid) - [schemas](#schemas) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) +- [utils](#utils) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -61,19 +65,17 @@ export declare const toBytes: (a: PolicyId, overrideOptions?: ParseOptions) => U Added in v2.0.0 -## toHex +# model -Encode PolicyId to hex string. +## Hex (type alias) **Signature** ```ts -export declare const toHex: (a: PolicyId, overrideOptions?: ParseOptions) => string +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 - -# model +Added in v2.4.0 ## PolicyId (class) @@ -146,18 +148,6 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex - -Parse PolicyId from hex string. - -**Signature** - -```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => PolicyId -``` - -Added in v2.0.0 - # predicates ## isPolicyId @@ -203,3 +193,39 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +## Hex + +A minting policy id as hex. + +Validated as well as branded: a 28-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ A policy id IS a script hash, and 28 bytes like a key hash. The brand is what keeps a +credential out of a policy position. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "PolicyIdHex"> +``` + +Added in v2.4.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => PolicyId +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/PoolKeyHash.mdx b/docs/content/docs/modules/PoolKeyHash.mdx index 146a478f..e0b06027 100644 --- a/docs/content/docs/modules/PoolKeyHash.mdx +++ b/docs/content/docs/modules/PoolKeyHash.mdx @@ -1,6 +1,7 @@ --- + title: PoolKeyHash.ts -nav_order: 99 +nav_order: 103 parent: Modules --- diff --git a/docs/content/docs/modules/PoolMetadata.mdx b/docs/content/docs/modules/PoolMetadata.mdx index 6cfa0493..960e060c 100644 --- a/docs/content/docs/modules/PoolMetadata.mdx +++ b/docs/content/docs/modules/PoolMetadata.mdx @@ -1,6 +1,7 @@ --- + title: PoolMetadata.ts -nav_order: 100 +nav_order: 104 parent: Modules --- diff --git a/docs/content/docs/modules/PoolParams.mdx b/docs/content/docs/modules/PoolParams.mdx index 569240bf..cf82d6f8 100644 --- a/docs/content/docs/modules/PoolParams.mdx +++ b/docs/content/docs/modules/PoolParams.mdx @@ -1,6 +1,7 @@ --- + title: PoolParams.ts -nav_order: 101 +nav_order: 105 parent: Modules --- @@ -34,11 +35,13 @@ parent: Modules - [FromBytes](#frombytes-1) - [FromCDDL](#fromcddl) - [FromHex](#fromhex-1) + - [PoolOwnersCDDL](#poolownerscddl) - [transformation](#transformation) - [calculatePoolRewards](#calculatepoolrewards) - [getEffectiveStake](#geteffectivestake) - [utils](#utils) - [CDDLSchema](#cddlschema) + - [poolOwnersArray](#poolownersarray) --- @@ -263,7 +266,18 @@ export declare const FromBytes: ( } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -315,7 +329,18 @@ export declare const FromCDDL: Schema.transformOrFail< { tag: Schema.Literal<[30]>; value: Schema.Tuple2 } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -365,7 +390,18 @@ export declare const FromHex: ( } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -385,6 +421,35 @@ export declare const FromHex: ( Added in v2.0.0 +## PoolOwnersCDDL + +`pool_owners` is `set`: the chain, CSL and CML all write it `#6.258`, and a bare +array is still valid on the way in. + +Modelled as a transform rather than a union in the tuple slot so that the slot's **Type** stays +`ReadonlyArray` and only its Encoded side widens. A union here would change +`CDDLSchema.Type`, which cascades through `Certificate`'s sixteen-arm union and is rejected by +declaration emit. + +**Signature** + +```ts +export declare const PoolOwnersCDDL: Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ +> +``` + +Added in v2.0.0 + # transformation ## calculatePoolRewards @@ -432,7 +497,18 @@ export declare const CDDLSchema: Schema.Tuple< { tag: Schema.Literal<[30]>; value: Schema.Tuple2 } >, typeof Schema.Uint8ArrayFromSelf, - Schema.Array$, + Schema.transform< + Schema.Union< + [ + Schema.TaggedStruct< + "Tag", + { tag: Schema.Literal<[258]>; value: Schema.Array$ } + >, + Schema.Array$ + ] + >, + Schema.Array$ + >, Schema.Array$< Schema.SchemaClass< readonly [0n, bigint | null, any, any] | readonly [1n, bigint | null, string] | readonly [2n, string], @@ -444,3 +520,18 @@ export declare const CDDLSchema: Schema.Tuple< ] > ``` + +## poolOwnersArray + +`pool_owners` as a plain array of key-hash bytes, whether it arrived `#6.258`-tagged or bare. + +`Certificate` flattens `PoolParams.CDDLSchema` into its own tuple, so it needs the untagged +form at its encode boundary; `PoolOwnersCDDL` re-tags it there. + +**Signature** + +```ts +export declare const poolOwnersArray: (slot: unknown) => ReadonlyArray +``` + +Added in v2.0.0 diff --git a/docs/content/docs/modules/Port.mdx b/docs/content/docs/modules/Port.mdx index bf172d3d..08d9bb9c 100644 --- a/docs/content/docs/modules/Port.mdx +++ b/docs/content/docs/modules/Port.mdx @@ -1,6 +1,7 @@ --- + title: Port.ts -nav_order: 102 +nav_order: 106 parent: Modules --- diff --git a/docs/content/docs/modules/PositiveCoin.mdx b/docs/content/docs/modules/PositiveCoin.mdx index 201f519f..34493bf7 100644 --- a/docs/content/docs/modules/PositiveCoin.mdx +++ b/docs/content/docs/modules/PositiveCoin.mdx @@ -1,6 +1,7 @@ --- + title: PositiveCoin.ts -nav_order: 103 +nav_order: 107 parent: Modules --- diff --git a/docs/content/docs/modules/PrivateKey.mdx b/docs/content/docs/modules/PrivateKey.mdx index 2bbdaaf3..cf568aec 100644 --- a/docs/content/docs/modules/PrivateKey.mdx +++ b/docs/content/docs/modules/PrivateKey.mdx @@ -1,6 +1,7 @@ --- + title: PrivateKey.ts -nav_order: 104 +nav_order: 108 parent: Modules --- @@ -32,7 +33,7 @@ parent: Modules - [toHex](#tohex) - [errors](#errors) - [PrivateKeyError (class)](#privatekeyerror-class) - - [\_tag (property)](#_tag-property) + - [_tag (property)](#_tag-property) - [generators](#generators) - [generate](#generate) - [generateExtended](#generateextended) @@ -282,7 +283,7 @@ export declare class PrivateKeyError { Added in v2.0.0 -### \_tag (property) +### _tag (property) **Signature** diff --git a/docs/content/docs/modules/ProposalProcedure.mdx b/docs/content/docs/modules/ProposalProcedure.mdx index 74450dc9..e5d7db70 100644 --- a/docs/content/docs/modules/ProposalProcedure.mdx +++ b/docs/content/docs/modules/ProposalProcedure.mdx @@ -1,6 +1,7 @@ --- + title: ProposalProcedure.ts -nav_order: 105 +nav_order: 109 parent: Modules --- @@ -68,7 +69,7 @@ proposal_procedure = [ deposit : coin, reward_account : reward_account, governance_action : governance_action, - anchor : anchor / null + anchor : anchor ] governance_action = [action_type, action_data] @@ -216,7 +217,7 @@ export declare const CDDLSchema: Schema.Tuple< | readonly [6n], never >, - Schema.NullOr> + Schema.Tuple2 ] > ``` @@ -278,7 +279,7 @@ export declare const FromCBORBytes: ( | readonly [6n], never >, - Schema.NullOr> + Schema.Tuple2 ] >, Schema.SchemaClass, @@ -346,7 +347,7 @@ export declare const FromCBORHex: ( | readonly [6n], never >, - Schema.NullOr> + Schema.Tuple2 ] >, Schema.SchemaClass, @@ -405,7 +406,7 @@ export declare const FromCDDL: Schema.transformOrFail< | readonly [6n], never >, - Schema.NullOr> + Schema.Tuple2 ] >, Schema.SchemaClass, diff --git a/docs/content/docs/modules/ProposalProcedures.mdx b/docs/content/docs/modules/ProposalProcedures.mdx index 71261b90..0c3a6dd0 100644 --- a/docs/content/docs/modules/ProposalProcedures.mdx +++ b/docs/content/docs/modules/ProposalProcedures.mdx @@ -1,6 +1,7 @@ --- + title: ProposalProcedures.ts -nav_order: 106 +nav_order: 110 parent: Modules --- @@ -90,7 +91,7 @@ export declare const single: ( deposit: Coin.Coin, rewardAccount: RewardAccount.RewardAccount, governanceAction: GovernanceAction.GovernanceAction, - anchor: Anchor.Anchor | null + anchor: Anchor.Anchor ) => ProposalProcedures ``` @@ -189,50 +190,7 @@ CDDL schema for ProposalProcedures that produces CBOR-compatible types. **Signature** ```ts -export declare const CDDLSchema: Schema.Array$< - Schema.Tuple< - [ - typeof Schema.BigIntFromSelf, - typeof Schema.Uint8ArrayFromSelf, - Schema.SchemaClass< - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - never - >, - Schema.NullOr> - ] - > -> +export declare const CDDLSchema: typeof Schema.Unknown ``` Added in v2.0.0 @@ -253,50 +211,7 @@ export declare const FromCBORBytes: ( never >, Schema.transformOrFail< - Schema.Array$< - Schema.Tuple< - [ - typeof Schema.BigIntFromSelf, - typeof Schema.Uint8ArrayFromSelf, - Schema.SchemaClass< - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - never - >, - Schema.NullOr> - ] - > - >, + typeof Schema.Unknown, Schema.SchemaClass, never > @@ -323,50 +238,7 @@ export declare const FromCBORHex: ( never >, Schema.transformOrFail< - Schema.Array$< - Schema.Tuple< - [ - typeof Schema.BigIntFromSelf, - typeof Schema.Uint8ArrayFromSelf, - Schema.SchemaClass< - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - never - >, - Schema.NullOr> - ] - > - >, + typeof Schema.Unknown, Schema.SchemaClass, never > @@ -384,50 +256,7 @@ CDDL transformation schema for ProposalProcedures. ```ts export declare const FromCDDL: Schema.transformOrFail< - Schema.Array$< - Schema.Tuple< - [ - typeof Schema.BigIntFromSelf, - typeof Schema.Uint8ArrayFromSelf, - Schema.SchemaClass< - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - | readonly [0n, readonly [any, bigint] | null, ReadonlyMap, any] - | readonly [1n, readonly [any, bigint] | null, readonly [bigint, bigint]] - | readonly [2n, ReadonlyMap, any] - | readonly [3n, readonly [any, bigint] | null] - | readonly [ - 4n, - readonly [any, bigint] | null, - ( - | readonly (readonly [0n | 1n, any])[] - | { readonly _tag: "Tag"; readonly tag: 258; readonly value: readonly (readonly [0n | 1n, any])[] } - ), - ReadonlyMap, - { readonly _tag: "Tag"; readonly tag: 30; readonly value: readonly [bigint, bigint] } - ] - | readonly [5n, readonly [any, bigint] | null, readonly [readonly [string, any], any]] - | readonly [6n], - never - >, - Schema.NullOr> - ] - > - >, + typeof Schema.Unknown, Schema.SchemaClass, never > diff --git a/docs/content/docs/modules/ProtocolParamUpdate.mdx b/docs/content/docs/modules/ProtocolParamUpdate.mdx index 5c32baaa..b6090c46 100644 --- a/docs/content/docs/modules/ProtocolParamUpdate.mdx +++ b/docs/content/docs/modules/ProtocolParamUpdate.mdx @@ -1,6 +1,7 @@ --- + title: ProtocolParamUpdate.ts -nav_order: 107 +nav_order: 111 parent: Modules --- diff --git a/docs/content/docs/modules/ProtocolVersion.mdx b/docs/content/docs/modules/ProtocolVersion.mdx index 1e6e533d..82516ea6 100644 --- a/docs/content/docs/modules/ProtocolVersion.mdx +++ b/docs/content/docs/modules/ProtocolVersion.mdx @@ -1,6 +1,7 @@ --- + title: ProtocolVersion.ts -nav_order: 108 +nav_order: 112 parent: Modules --- diff --git a/docs/content/docs/modules/Redeemer.mdx b/docs/content/docs/modules/Redeemer.mdx index f2ae52ee..9bff42ba 100644 --- a/docs/content/docs/modules/Redeemer.mdx +++ b/docs/content/docs/modules/Redeemer.mdx @@ -1,6 +1,7 @@ --- + title: Redeemer.ts -nav_order: 109 +nav_order: 113 parent: Modules --- @@ -344,32 +345,16 @@ Added in v2.0.0 ## FromCBORBytes CBOR bytes transformation schema for Redeemer using CDDL. -Transforms between CBOR bytes and Redeemer using CDDL encoding. +Transforms between CBOR bytes and Redeemer using CDDL encoding. The data is +written with the `plutusData` options, the rest with the `ledger` options. +Plain options are read as `CBOR.toTxCodecOptions` reads them. **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.Tuple< - [ - Schema.SchemaClass, - Schema.SchemaClass, - Schema.Schema, - Schema.Tuple2 - ] - >, - Schema.SchemaClass, - never - > -> + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => Schema.transformOrFail, never> ``` Added in v2.0.0 @@ -383,28 +368,10 @@ Transforms between CBOR hex string and Redeemer using CDDL encoding. ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.Schema, - Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.Tuple< - [ - Schema.SchemaClass, - Schema.SchemaClass, - Schema.Schema, - Schema.Tuple2 - ] - >, - Schema.SchemaClass, - never - > - > + Schema.transformOrFail, never> > ``` @@ -463,24 +430,24 @@ Added in v2.0.0 ## toCBORBytes -Encode Redeemer to CBOR bytes. +Encode Redeemer to CBOR bytes, as in {@link FromCBORBytes}. **Signature** ```ts -export declare const toCBORBytes: (redeemer: Redeemer, options?: CBOR.CodecOptions) => Uint8Array +export declare const toCBORBytes: (redeemer: Redeemer, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => Uint8Array ``` Added in v2.0.0 ## toCBORHex -Encode Redeemer to CBOR hex string. +Encode Redeemer to CBOR hex string, as in {@link FromCBORBytes}. **Signature** ```ts -export declare const toCBORHex: (redeemer: Redeemer, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (redeemer: Redeemer, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 diff --git a/docs/content/docs/modules/Redeemers.mdx b/docs/content/docs/modules/Redeemers.mdx index 9210ca63..08e54c4c 100644 --- a/docs/content/docs/modules/Redeemers.mdx +++ b/docs/content/docs/modules/Redeemers.mdx @@ -1,6 +1,7 @@ --- + title: Redeemers.ts -nav_order: 110 +nav_order: 114 parent: Modules --- @@ -15,12 +16,14 @@ parent: Modules - [constructors](#constructors) - [makeRedeemerMap](#makeredeemermap) - [encoding](#encoding) + - [spliceMap](#splicemap) - [toCBORBytes](#tocborbytes) - [toCBORBytesMap](#tocborbytesmap) - [toCBORHex](#tocborhex) - [toCBORHexMap](#tocborhexmap) - [hashing](#hashing) - [toScriptDataHash](#toscriptdatahash) + - [toScriptDataHashFromEncoded](#toscriptdatahashfromencoded) - [model](#model) - [RedeemerArray (class)](#redeemerarray-class) - [toArray (method)](#toarray-method) @@ -61,6 +64,8 @@ parent: Modules - [Redeemers](#redeemers) - [utilities](#utilities) - [keyToString](#keytostring) +- [utils](#utils) + - [keepDataBytes](#keepdatabytes) --- @@ -94,6 +99,37 @@ Added in v2.0.0 # encoding +## spliceMap + +A Conway redeemer MAP over data that is already encoded: `{[tag, index] => [data, ex_units]}`. + +⚠️ **The data is spliced, not re-encoded.** Going through {@link Redeemer.Redeemer} means going +through `Data`, and while `Data` keeps the bytes it was decoded from, one thing it cannot keep +is the header width of an integer that IS the whole datum -- a `bigint` is not an object and +has nowhere to carry the record. A redeemer whose bytes change moves `script_data_hash`, which +is a phase-2 failure on chain, so the path that takes bytes keeps them. + +⚠️ The keys are sorted bytewise over their ENCODED form, which is what the ledger requires of a +map it reconstructs. The five arrays are positional and must be the same length: a short one +used to encode `undefined` as a redeemer field, which changed the hash and failed at the node +with nothing pointing back here. + +**Signature** + +```ts +export declare const spliceMap: ( + entries: ReadonlyArray<{ + readonly tag: number + readonly index: bigint + readonly data: Uint8Array + readonly mem: bigint + readonly steps: bigint + }> +) => Uint8Array +``` + +Added in v2.8.0 + ## toCBORBytes Encode to CBOR bytes (array format). @@ -101,7 +137,7 @@ Encode to CBOR bytes (array format). **Signature** ```ts -export declare const toCBORBytes: (data: RedeemerArray, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: (data: RedeemerArray, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => any ``` Added in v2.0.0 @@ -113,7 +149,7 @@ Encode to CBOR bytes (map format). **Signature** ```ts -export declare const toCBORBytesMap: (data: RedeemerMap, options?: CBOR.CodecOptions) => any +export declare const toCBORBytesMap: (data: RedeemerMap, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => any ``` Added in v2.0.0 @@ -125,7 +161,7 @@ Encode to CBOR hex string (array format). **Signature** ```ts -export declare const toCBORHex: (data: RedeemerArray, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (data: RedeemerArray, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 @@ -137,7 +173,7 @@ Encode to CBOR hex string (map format). **Signature** ```ts -export declare const toCBORHexMap: (data: RedeemerMap, options?: CBOR.CodecOptions) => string +export declare const toCBORHexMap: (data: RedeemerMap, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 @@ -157,6 +193,9 @@ The payload format per CDDL spec is raw concatenation (not a CBOR structure): redeemers_bytes || datums_bytes || language_views_bytes ``` +The redeemers and datums are hashed as `TransactionWitnessSet.toCBORBytes` +writes them under `options`. + **Signature** ```ts @@ -164,12 +203,41 @@ export declare const toScriptDataHash: ( redeemers: Redeemers, costModels: CostModel.CostModels, datums?: ReadonlyArray, - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => ScriptDataHash.ScriptDataHash ``` Added in v2.0.0 +## toScriptDataHashFromEncoded + +`script_data_hash` over redeemers and datums that are already encoded. + +`script_data_hash = blake2b256(redeemers ‖ datums ‖ language_views)`, with the Conway special +case that no redeemers but datums present hashes `A0 ‖ datums ‖ A0`. + +⚠️ **The bytes-level sibling of {@link toScriptDataHash}, and the one a wallet wants.** That one +re-encodes the redeemers and the datums from their decoded values, which is correct only as far +as those values can carry their arrival bytes. This takes the bytes the transaction will +actually carry, so the hash is over what gets signed rather than over a re-derivation of it. +Only `languageViewsEncoding` needs the typed model, because the PlutusV1 indefinite quirk lives +there, and it is shared rather than restated. + +`datums` absent and `datums` empty are DIFFERENT: absent omits the field, which is the Conway +special case's precondition. + +**Signature** + +```ts +export declare const toScriptDataHashFromEncoded: ( + redeemers: Uint8Array, + datums: Uint8Array | undefined, + costModels: CostModel.CostModels +) => ScriptDataHash.ScriptDataHash +``` + +Added in v2.8.0 + # model ## RedeemerArray (class) @@ -505,33 +573,19 @@ Added in v2.0.0 ## FromCBORBytes -CBOR bytes schema for array format. +CBOR bytes schema for array format. Each redeemer is written as +`Redeemer.FromCBORBytes(options)` writes it, the array with the `ledger` +options. Plain options are read as `CBOR.toTxCodecOptions` reads them. **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.Array$< - Schema.Tuple< - [ - Schema.SchemaClass, - Schema.SchemaClass, - Schema.Schema, - Schema.Tuple2 - ] - > - >, - Schema.SchemaClass, - never - > + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.SchemaClass, + never > ``` @@ -539,30 +593,19 @@ Added in v2.0.0 ## FromCBORBytesMap -CBOR bytes schema for map format. +CBOR bytes schema for map format. Each redeemer's data is written with the +`plutusData` options, the rest with the `ledger` options. Plain options are +read as `CBOR.toTxCodecOptions` reads them. **Signature** ```ts export declare const FromCBORBytesMap: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.MapFromSelf< - Schema.Tuple2, - Schema.Tuple2< - Schema.Schema, - Schema.Tuple2 - > - >, - Schema.SchemaClass, - never - > + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.SchemaClass, + never > ``` @@ -576,29 +619,13 @@ CBOR hex schema for array format. ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.Schema, - Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.Array$< - Schema.Tuple< - [ - Schema.SchemaClass, - Schema.SchemaClass, - Schema.Schema, - Schema.Tuple2 - ] - > - >, - Schema.SchemaClass, - never - > + Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.SchemaClass, + never > > ``` @@ -613,27 +640,10 @@ CBOR hex schema for map format. ```ts export declare const FromCBORHexMap: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.Schema, - Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.MapFromSelf< - Schema.Tuple2, - Schema.Tuple2< - Schema.Schema, - Schema.Tuple2 - > - >, - Schema.SchemaClass, - never - > - > + Schema.transformOrFail, never> > ``` @@ -731,3 +741,28 @@ export declare const keyToString: ([tag, index]: RedeemerKey) => string ``` Added in v2.0.0 + +# utils + +## keepDataBytes + +Re-attach each redeemer's ARRIVAL BYTES to its decoded `data`. + +⚠️ **Without this, decoding a redeemer map and re-encoding it silently reframes the data.** The +decode goes through `Data.FromCDDL`, which receives a CBOR value with no bytes behind it, so a +datum carrying an empty indefinite array comes back as `d87a80` where `d87a9fff` went in. Three +bytes, a different `script_data_hash`, and a PHASE-2 FAILURE at the node -- and the failure is +invisible locally, because the hash the builder computed over the spliced bytes and the +redeemers it then embedded disagree only once the node recomputes it. + +The bytes are SLICED from the input rather than replayed from a format tree, and paired with the +decoded redeemers positionally: both are in wire order, and a Plutus map keeps the order it was +given. + +**Signature** + +```ts +export declare const keepDataBytes: (redeemers: A, bytes: Uint8Array) => A +``` + +Added in v2.8.0 diff --git a/docs/content/docs/modules/Relay.mdx b/docs/content/docs/modules/Relay.mdx index 1f4ddd96..899fda7d 100644 --- a/docs/content/docs/modules/Relay.mdx +++ b/docs/content/docs/modules/Relay.mdx @@ -1,6 +1,7 @@ --- + title: Relay.ts -nav_order: 111 +nav_order: 115 parent: Modules --- diff --git a/docs/content/docs/modules/RewardAccount.mdx b/docs/content/docs/modules/RewardAccount.mdx index c3b8bf4d..2be09c95 100644 --- a/docs/content/docs/modules/RewardAccount.mdx +++ b/docs/content/docs/modules/RewardAccount.mdx @@ -1,6 +1,7 @@ --- + title: RewardAccount.ts -nav_order: 112 +nav_order: 116 parent: Modules --- diff --git a/docs/content/docs/modules/RewardAddress.mdx b/docs/content/docs/modules/RewardAddress.mdx index 0eff2c70..e58a5b26 100644 --- a/docs/content/docs/modules/RewardAddress.mdx +++ b/docs/content/docs/modules/RewardAddress.mdx @@ -1,6 +1,7 @@ --- + title: RewardAddress.ts -nav_order: 113 +nav_order: 117 parent: Modules --- diff --git a/docs/content/docs/modules/Script.mdx b/docs/content/docs/modules/Script.mdx index 5a5a5b28..c3bac1ed 100644 --- a/docs/content/docs/modules/Script.mdx +++ b/docs/content/docs/modules/Script.mdx @@ -1,6 +1,7 @@ --- + title: Script.ts -nav_order: 114 +nav_order: 118 parent: Modules --- @@ -13,9 +14,11 @@ parent: Modules - [arbitrary](#arbitrary) - [arbitrary](#arbitrary-1) - [model](#model) + - [Hex (type alias)](#hex-type-alias) - [Script](#script) - [schemas](#schemas) - [FromCDDL](#fromcddl) + - [Hex](#hex) - [ScriptCDDL](#scriptcddl) - [utils](#utils) - [FromCBORBytes](#fromcborbytes) @@ -47,6 +50,16 @@ Added in v2.0.0 # model +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + ## Script Script union type following Conway CDDL specification. @@ -103,6 +116,23 @@ export declare const FromCDDL: Schema.transformOrFail< Added in v2.0.0 +## Hex + +A script's bytes as hex, parameters already applied. + +⚠️ The script ITSELF, not its hash. A script hash is 28 bytes; this is the whole program. + +Branded so that CBOR hex of one kind cannot stand in for another once it leaves the typed +domain. Non-empty whole bytes is all the shape there is to check. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "ScriptHex"> +``` + +Added in v2.4.0 + ## ScriptCDDL CDDL schema for Script as tagged tuples. diff --git a/docs/content/docs/modules/ScriptDataHash.mdx b/docs/content/docs/modules/ScriptDataHash.mdx index 6b747789..dc4042b2 100644 --- a/docs/content/docs/modules/ScriptDataHash.mdx +++ b/docs/content/docs/modules/ScriptDataHash.mdx @@ -1,6 +1,7 @@ --- + title: ScriptDataHash.ts -nav_order: 115 +nav_order: 119 parent: Modules --- @@ -14,8 +15,8 @@ parent: Modules - [arbitrary](#arbitrary-1) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) - [model](#model) + - [Hex (type alias)](#hex-type-alias) - [ScriptDataHash (class)](#scriptdatahash-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) @@ -24,12 +25,15 @@ parent: Modules - [[Hash.symbol] (method)](#hashsymbol-method) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isScriptDataHash](#isscriptdatahash) - [schemas](#schemas) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [Hex](#hex) +- [utils](#utils) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -61,19 +65,17 @@ export declare const toBytes: (a: ScriptDataHash, overrideOptions?: ParseOptions Added in v2.0.0 -## toHex +# model -Encode ScriptDataHash to hex string. +## Hex (type alias) **Signature** ```ts -export declare const toHex: (a: ScriptDataHash, overrideOptions?: ParseOptions) => string +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 - -# model +Added in v2.4.0 ## ScriptDataHash (class) @@ -151,18 +153,6 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex - -Parse ScriptDataHash from hex string. - -**Signature** - -```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => ScriptDataHash -``` - -Added in v2.0.0 - # predicates ## isScriptDataHash @@ -211,3 +201,38 @@ export declare const FromHex: Schema.transform< ``` Added in v2.0.0 + +## Hex + +A script-data hash as hex. + +Validated as well as branded: a 32-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Same shape as a transaction hash and a datum hash. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "ScriptDataHashHex"> +``` + +Added in v2.4.0 + +# utils + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => ScriptDataHash +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/ScriptHash.mdx b/docs/content/docs/modules/ScriptHash.mdx index 353552c1..940709c4 100644 --- a/docs/content/docs/modules/ScriptHash.mdx +++ b/docs/content/docs/modules/ScriptHash.mdx @@ -1,6 +1,7 @@ --- + title: ScriptHash.ts -nav_order: 116 +nav_order: 120 parent: Modules --- @@ -15,12 +16,15 @@ parent: Modules - [computation](#computation) - [fromScript](#fromscript) - [encoding](#encoding) + - [toBech32](#tobech32) - [toBytes](#tobytes) - [toHex](#tohex) - [parsing](#parsing) + - [fromBech32](#frombech32) - [fromBytes](#frombytes) - [fromHex](#fromhex) - [schemas](#schemas) + - [FromBech32](#frombech32-1) - [FromBytes](#frombytes-1) - [FromHex](#fromhex-1) - [ScriptHash (class)](#scripthash-class) @@ -70,6 +74,18 @@ Added in v2.0.0 # encoding +## toBech32 + +Convert a ScriptHash to a bech32 string (script1...). + +**Signature** + +```ts +export declare const toBech32: (a: ScriptHash, overrideOptions?: ParseOptions) => string +``` + +Added in v2.0.0 + ## toBytes Convert a ScriptHash to raw bytes. @@ -96,6 +112,18 @@ Added in v2.0.0 # parsing +## fromBech32 + +Parse a ScriptHash from a bech32 string (script1...). + +**Signature** + +```ts +export declare const fromBech32: (i: string, overrideOptions?: ParseOptions) => ScriptHash +``` + +Added in v2.0.0 + ## fromBytes Parse a ScriptHash from raw bytes. @@ -124,6 +152,23 @@ Added in v2.0.0 # schemas +## FromBech32 + +Schema transformer from bech32 string (script1...) to ScriptHash. +Uses the CIP-0005 `script` prefix for script hashes. + +**Signature** + +```ts +export declare const FromBech32: Schema.transformOrFail< + typeof Schema.String, + Schema.SchemaClass, + never +> +``` + +Added in v2.0.0 + ## FromBytes Schema for transforming between Uint8Array and ScriptHash. diff --git a/docs/content/docs/modules/ScriptRef.mdx b/docs/content/docs/modules/ScriptRef.mdx index 57cef6ad..20895155 100644 --- a/docs/content/docs/modules/ScriptRef.mdx +++ b/docs/content/docs/modules/ScriptRef.mdx @@ -1,6 +1,7 @@ --- + title: ScriptRef.ts -nav_order: 117 +nav_order: 121 parent: Modules --- @@ -172,7 +173,7 @@ Added in v2.0.0 ## FromCBORBytes -/\*\* +/** CBOR bytes transformation schema for ScriptRef. **Signature** diff --git a/docs/content/docs/modules/SingleHostAddr.mdx b/docs/content/docs/modules/SingleHostAddr.mdx index add12329..715248ce 100644 --- a/docs/content/docs/modules/SingleHostAddr.mdx +++ b/docs/content/docs/modules/SingleHostAddr.mdx @@ -1,6 +1,7 @@ --- + title: SingleHostAddr.ts -nav_order: 161 +nav_order: 167 parent: Modules --- diff --git a/docs/content/docs/modules/SingleHostName.mdx b/docs/content/docs/modules/SingleHostName.mdx index 5e361972..6ab8b459 100644 --- a/docs/content/docs/modules/SingleHostName.mdx +++ b/docs/content/docs/modules/SingleHostName.mdx @@ -1,6 +1,7 @@ --- + title: SingleHostName.ts -nav_order: 162 +nav_order: 168 parent: Modules --- diff --git a/docs/content/docs/modules/Slot.mdx b/docs/content/docs/modules/Slot.mdx index c5f41a1d..967050bf 100644 --- a/docs/content/docs/modules/Slot.mdx +++ b/docs/content/docs/modules/Slot.mdx @@ -1,6 +1,7 @@ --- + title: Slot.ts -nav_order: 163 +nav_order: 169 parent: Modules --- diff --git a/docs/content/docs/modules/SlotConfig.mdx b/docs/content/docs/modules/SlotConfig.mdx index baa0a733..b2c8762f 100644 --- a/docs/content/docs/modules/SlotConfig.mdx +++ b/docs/content/docs/modules/SlotConfig.mdx @@ -1,6 +1,7 @@ --- + title: SlotConfig.ts -nav_order: 164 +nav_order: 170 parent: Modules --- diff --git a/docs/content/docs/modules/StakeReference.mdx b/docs/content/docs/modules/StakeReference.mdx index e14a9cdc..761304a3 100644 --- a/docs/content/docs/modules/StakeReference.mdx +++ b/docs/content/docs/modules/StakeReference.mdx @@ -1,6 +1,7 @@ --- + title: StakeReference.ts -nav_order: 165 +nav_order: 171 parent: Modules --- diff --git a/docs/content/docs/modules/TSchema.mdx b/docs/content/docs/modules/TSchema.mdx deleted file mode 100644 index d91b3724..00000000 --- a/docs/content/docs/modules/TSchema.mdx +++ /dev/null @@ -1,535 +0,0 @@ ---- -title: TSchema.ts -nav_order: 178 -parent: Modules ---- - -## TSchema overview - ---- - -

Table of contents

- -- [combinators](#combinators) - - [equivalence](#equivalence) -- [constructors](#constructors) - - [TaggedStruct](#taggedstruct) - - [Variant](#variant) -- [schemas](#schemas) - - [ByteArray](#bytearray) - - [Integer](#integer) - - [PlutusData](#plutusdata) -- [utils](#utils) - - [Array](#array) - - [Array (interface)](#array-interface) - - [Boolean](#boolean) - - [Boolean (interface)](#boolean-interface) - - [ByteArray (interface)](#bytearray-interface) - - [Integer (interface)](#integer-interface) - - [Literal](#literal) - - [Literal (interface)](#literal-interface) - - [LiteralOptions (interface)](#literaloptions-interface) - - [Map](#map) - - [Map (interface)](#map-interface) - - [NullOr](#nullor) - - [NullOr (interface)](#nullor-interface) - - [PlutusData (interface)](#plutusdata-interface) - - [Struct](#struct) - - [Struct (interface)](#struct-interface) - - [StructOptions (interface)](#structoptions-interface) - - [Tuple](#tuple) - - [Tuple (interface)](#tuple-interface) - - [UndefineOr (interface)](#undefineor-interface) - - [UndefinedOr](#undefinedor) - - [Union](#union) - - [Union (interface)](#union-interface) - - [compose](#compose) - - [filter](#filter) - - [is](#is) - ---- - -# combinators - -## equivalence - -Creates an equivalence function for a schema that can compare two values for equality. - -This leverages Effect Schema's built-in equivalence generation, which creates -optimized equality checks based on the schema structure. - -**Signature** - -```ts -export declare const equivalence: (schema: Schema.Schema) => Equivalence -``` - -Added in v2.0.0 - -# constructors - -## TaggedStruct - -Creates a tagged struct - a shortcut for creating a Struct with a Literal tag field. - -This is a convenience helper that makes it easy to create structs with discriminator fields, -commonly used in discriminated unions. - -**Signature** - -```ts -export declare const TaggedStruct: < - TagValue extends string, - Fields extends Schema.Struct.Fields, - TagField extends string = "_tag" ->( - tagValue: TagValue, - fields: Fields, - options?: StructOptions & { tagField?: TagField } -) => Struct<{ [K in TagField]: Literal<[TagValue]> } & Fields> -``` - -Added in v2.0.0 - -## Variant - -Creates a variant (tagged union) schema for Aiken-style enum types. - -This is a convenience helper that creates properly discriminated TypeScript types -while maintaining single-level CBOR encoding compatible with Aiken. - -**Signature** - -```ts -export declare const Variant: >( - variants: Variants -) => Union }> }[keyof Variants]>> -``` - -Added in v2.0.0 - -# schemas - -## ByteArray - -ByteArray schema for PlutusData - runtime Uint8Array, encoded as hex string. - -**Signature** - -```ts -export declare const ByteArray: ByteArray -``` - -Added in v2.0.0 - -## Integer - -Integer schema that represents Data.Int for PlutusData. -This enables withSchema compatibility by using the Data type schema directly. - -**Signature** - -```ts -export declare const Integer: Integer -``` - -Added in v2.0.0 - -## PlutusData - -Opaque PlutusData schema for use inside TSchema combinators. -Represents an arbitrary PlutusData value that passes through encoding unchanged. - -Use this when a field can hold any PlutusData without a specific schema. - -**Signature** - -```ts -export declare const PlutusData: PlutusData -``` - -Added in v2.0.0 - -# utils - -## Array - -Creates a schema for arrays - just passes through to Schema.Array directly - -**Signature** - -```ts -export declare const Array: (items: S) => Array -``` - -Added in v1.0.0 - -## Array (interface) - -**Signature** - -```ts -export interface Array extends Schema.Array$ {} -``` - -## Boolean - -Schema for boolean values using Plutus Data Constructor - -- False with index 0 -- True with index 1 - -**Signature** - -```ts -export declare const Boolean: Boolean -``` - -Added in v2.0.0 - -## Boolean (interface) - -**Signature** - -```ts -export interface Boolean - extends Schema.transform, typeof Schema.Boolean> {} -``` - -## ByteArray (interface) - -**Signature** - -```ts -export interface ByteArray extends Schema.Schema {} -``` - -## Integer (interface) - -**Signature** - -```ts -export interface Integer extends Schema.SchemaClass {} -``` - -## Literal - -Creates a schema for literal types with Plutus Data Constructor transformation - -**Signature** - -```ts -export declare const Literal: { - >>( - ...self: Literals - ): Literal - >>( - ...args: [...Literals, LiteralOptions] - ): Literal -} -``` - -Added in v2.0.0 - -## Literal (interface) - -**Signature** - -```ts -export interface Literal> - extends Schema.transform, Schema.Literal<[...Literals]>> {} -``` - -## LiteralOptions (interface) - -Options for Literal schema - -**Signature** - -```ts -export interface LiteralOptions { - /** - * Custom Constr index for this literal (default: auto-incremented from 0) - * Useful when matching Plutus contract constructor indices - */ - index?: number - /** - * When used in a Union, controls whether this Literal should be "flattened" (unwrapped). - * - true: Encodes as Constr(index, []) directly - * - false: Encodes as Constr(unionPos, [Constr(index, [])]) (nested) - * - * Default: true when index is specified, false otherwise - */ - flatInUnion?: boolean -} -``` - -## Map - -Creates a schema for maps with Plutus Map type annotation -Maps are represented as a list of constructor pairs, where each pair -is a constructor with index 0 and fields [key, value] - -**Signature** - -```ts -export declare const Map: (key: K, value: V) => Map -``` - -Added in v1.0.0 - -## Map (interface) - -**Signature** - -```ts -export interface Map - extends Schema.transform< - Schema.SchemaClass, globalThis.Map, never>, - Schema.MapFromSelf - > {} -``` - -## NullOr - -Creates a schema for nullable types that transforms to/from Plutus Data Constructor -Represents optional values as: - -- Just(value) with index 0 -- Nothing with index 1 - -**Signature** - -```ts -export declare const NullOr: (self: S) => NullOr -``` - -Added in v2.0.0 - -## NullOr (interface) - -**Signature** - -```ts -export interface NullOr - extends Schema.transform, Schema.NullOr> {} -``` - -## PlutusData (interface) - -**Signature** - -```ts -export interface PlutusData extends Schema.Schema {} -``` - -## Struct - -Creates a schema for struct types using Plutus Data Constructor -Objects are represented as a constructor with index (default 0) and fields as an array - -**Signature** - -```ts -export declare const Struct: ( - fields: Fields, - options?: StructOptions -) => Struct -``` - -Added in v2.0.0 - -## Struct (interface) - -**Signature** - -```ts -export interface Struct - extends Schema.transform, Schema.Struct> {} -``` - -## StructOptions (interface) - -Options for Struct schema - -**Signature** - -```ts -export interface StructOptions { - /** - * Custom Constr index for this struct (default: 0) - * Useful when creating union variants with specific indices - */ - index?: number - /** - * When used in a Union, controls whether this Struct should be "flattened" (unwrapped). - * - true: Encodes as Constr(index, [fields]) directly - * - false: Encodes as Constr(unionPos, [Constr(index, [fields])]) (nested) - * - * Default: true when index is specified, false otherwise - */ - flatInUnion?: boolean - /** - * When used as a field in a parent Struct, controls whether this Struct's fields - * should be spread (merged) into the parent's field array. - * - true: Inner Struct fields are merged directly into parent - * - false: Inner Struct is kept as a nested Constr - * - * Default: false - * - * Note: This only applies when the Struct is a field value, not when used in Union. - */ - flatFields?: boolean - /** - * Name of a field to treat as a discriminant tag (e.g., "_tag", "type"). - * - * Auto-detection: Fields named "_tag", "type", "kind", or "variant" containing - * Literal values are automatically stripped from CBOR encoding and injected during decoding. - * - * This option allows you to: - * - Explicitly specify a custom tag field name - * - Disable auto-detection with `tagField: false` - * - * Default: auto-detect from KNOWN_TAG_FIELDS - */ - tagField?: string | false -} -``` - -## Tuple - -Creates a schema for tuple types - just passes through to Schema.Tuple directly - -**Signature** - -```ts -export declare const Tuple: (element: [...Elements]) => Tuple -``` - -Added in v2.0.0 - -## Tuple (interface) - -**Signature** - -```ts -export interface Tuple extends Schema.Tuple {} -``` - -## UndefineOr (interface) - -**Signature** - -```ts -export interface UndefineOr - extends Schema.transform, Schema.UndefinedOr> {} -``` - -## UndefinedOr - -Creates a schema for undefined types that transforms to/from Plutus Data Constructor -Represents optional values as: - -- Just(value) with index 0 -- Nothing with index 1 - -**Signature** - -```ts -export declare const UndefinedOr: (self: S) => UndefineOr -``` - -Added in v2.0.0 - -## Union - -Creates a schema for union types using Plutus Data Constructor -Unions are represented as a constructor with index 0, 1, 2... and fields as an array - -Members marked with flat: true will be encoded directly using their index -instead of being wrapped in an additional Constr layer. - -**Signature** - -```ts -export declare const Union: >(...members: Members) => Union -``` - -Added in v2.0.0 - -## Union (interface) - -**Signature** - -```ts -export interface Union> - extends Schema.transformOrFail< - Schema.SchemaClass, - Schema.SchemaClass, Schema.Schema.Type, never>, - never - > {} -``` - -## compose - -**Signature** - -```ts -export declare const compose: { - >( - to: To & Schema.Schema, C, Schema.Schema.Context> - ): (from: From) => Schema.transform - ( - to: To - ): >( - from: From & Schema.Schema, Schema.Schema.Context> - ) => Schema.transform - ( - to: To, - options?: { readonly strict: true } - ): ( - from: From & Schema.Schema, Schema.Schema.Encoded, Schema.Schema.Context> - ) => Schema.transform - ( - to: To, - options: { readonly strict: false } - ): (from: From) => Schema.transform - >( - from: From, - to: To & Schema.Schema, C, Schema.Schema.Context> - ): Schema.transform - , To extends Schema.Schema.Any>( - from: From & Schema.Schema, Schema.Schema.Context>, - to: To - ): Schema.transform - ( - from: From & Schema.Schema, Schema.Schema.Encoded, Schema.Schema.Context>, - to: To, - options?: { readonly strict: true } - ): Schema.transform - ( - from: From, - to: To, - options: { readonly strict: false } - ): Schema.transform -} -``` - -## filter - -**Signature** - -```ts -export declare const filter: typeof Schema.filter -``` - -## is - -**Signature** - -```ts -export declare const is: ( - schema: Schema.Schema, - options?: SchemaAST.ParseOptions -) => (u: unknown, overrideOptions?: SchemaAST.ParseOptions | number) => u is A -``` diff --git a/docs/content/docs/modules/Text.mdx b/docs/content/docs/modules/Text.mdx index d95d0c6d..0bc24b54 100644 --- a/docs/content/docs/modules/Text.mdx +++ b/docs/content/docs/modules/Text.mdx @@ -1,6 +1,7 @@ --- + title: Text.ts -nav_order: 166 +nav_order: 172 parent: Modules --- diff --git a/docs/content/docs/modules/Text128.mdx b/docs/content/docs/modules/Text128.mdx index 9fff7a4b..be97156a 100644 --- a/docs/content/docs/modules/Text128.mdx +++ b/docs/content/docs/modules/Text128.mdx @@ -1,6 +1,7 @@ --- + title: Text128.ts -nav_order: 167 +nav_order: 173 parent: Modules --- diff --git a/docs/content/docs/modules/Time.mdx b/docs/content/docs/modules/Time.mdx index bcf166f0..54bd5988 100644 --- a/docs/content/docs/modules/Time.mdx +++ b/docs/content/docs/modules/Time.mdx @@ -1,6 +1,7 @@ --- + title: Time.ts -nav_order: 168 +nav_order: 174 parent: Modules --- diff --git a/docs/content/docs/modules/Transaction.mdx b/docs/content/docs/modules/Transaction.mdx index e8959fc8..8776eab7 100644 --- a/docs/content/docs/modules/Transaction.mdx +++ b/docs/content/docs/modules/Transaction.mdx @@ -1,6 +1,7 @@ --- + title: Transaction.ts -nav_order: 169 +nav_order: 175 parent: Modules --- @@ -10,11 +11,15 @@ parent: Modules

Table of contents

+- [constructors](#constructors) + - [fromEncoded](#fromencoded) - [encoding](#encoding) - [addVKeyWitnesses](#addvkeywitnesses) - [addVKeyWitnessesBytes](#addvkeywitnessesbytes) - [addVKeyWitnessesHex](#addvkeywitnesseshex) - [extractBodyBytes](#extractbodybytes) + - [getIntendedCodecOptions](#getintendedcodecoptions) + - [setIntendedCodecOptions](#setintendedcodecoptions) - [toCBORBytesWithFormat](#tocborbyteswithformat) - [toCBORHexWithFormat](#tocborhexwithformat) - [model](#model) @@ -33,6 +38,7 @@ parent: Modules - [FromCBORHex](#fromcborhex) - [FromCDDL](#fromcddl) - [arbitrary](#arbitrary) + - [cborHeaderSize](#cborheadersize) - [fromCBORBytes](#fromcborbytes-1) - [fromCBORHex](#fromcborhex-1) - [toCBORBytes](#tocborbytes) @@ -40,6 +46,30 @@ parent: Modules --- +# constructors + +## fromEncoded + +Assemble a signed transaction from a body and auxiliary data that are already encoded. + +The body arrives as bytes because that is what was hashed and signed: decoding it and +re-encoding it is how a co-signed transaction acquires a different id than the one its first +signature covers. {@link fromCBORBytes} on `TransactionBody` records the arrival bytes, so the +body this carries re-encodes exactly, and `isValid` defaults to the only value a wallet submits. + +**Signature** + +```ts +export declare const fromEncoded: (input: { + readonly body: Uint8Array + readonly witnessSet: TransactionWitnessSet.TransactionWitnessSet + readonly auxiliaryData?: Uint8Array + readonly isValid?: boolean +}) => Transaction +``` + +Added in v2.8.0 + # encoding ## addVKeyWitnesses @@ -116,10 +146,40 @@ export declare const extractBodyBytes: (txBytes: Uint8Array) => Uint8Array Added in v2.0.0 +## getIntendedCodecOptions + +The options this transaction is meant to be serialized with, if any were recorded. + +**Signature** + +```ts +export declare const getIntendedCodecOptions: (data: Transaction) => CBOR.CodecOptions | undefined +``` + +Added in v2.2.0 + +## setIntendedCodecOptions + +Record the options this transaction is meant to be serialized with. + +Intended for builders: a transaction whose hashes were computed under non-default options must +be encoded under those same options wherever it goes next. + +**Signature** + +```ts +export declare const setIntendedCodecOptions: (data: Transaction, options: CBOR.CodecOptions) => void +``` + +Added in v2.2.0 + ## toCBORBytesWithFormat Convert a Transaction to CBOR bytes using an explicit root format tree. +The witness set is written as `TransactionWitnessSet.toCBORBytesWithFormat` +writes it. + **Signature** ```ts @@ -130,7 +190,8 @@ Added in v2.0.0 ## toCBORHexWithFormat -Convert a Transaction to CBOR hex string using an explicit root format tree. +Convert a Transaction to CBOR hex string using an explicit root format tree, +as in {@link toCBORBytesWithFormat}. **Signature** @@ -244,60 +305,36 @@ export declare const CDDLSchema: Schema.declare< ## FromCBORBytes -CBOR bytes transformation schema for Transaction. +CBOR bytes transformation schema for Transaction. The body and the witness +set are written as `TransactionBody.FromCBORBytes(options)` and +`TransactionWitnessSet.FromCBORBytes(options)` write them, the rest with +the `ledger` options. Plain options are read as `CBOR.toTxCodecOptions` +reads them. **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.declare< - readonly [Map, Map, boolean, CBOR.CBOR], - readonly [Map, Map, boolean, CBOR.CBOR], - readonly [], - never - >, - Schema.SchemaClass, - never - > + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.SchemaClass, + never > ``` ## FromCBORHex -CBOR hex transformation schema for Transaction. +CBOR hex transformation schema for Transaction, as in {@link FromCBORBytes}. **Signature** ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< - Schema.transform< - Schema.Schema, - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - > - >, - Schema.transformOrFail< - Schema.declare< - readonly [Map, Map, boolean, CBOR.CBOR], - readonly [Map, Map, boolean, CBOR.CBOR], - readonly [], - never - >, - Schema.SchemaClass, - never - > + Schema.Schema, + Schema.transformOrFail, never> > ``` @@ -328,6 +365,25 @@ export declare const FromCDDL: Schema.transformOrFail< export declare const arbitrary: FastCheck.Arbitrary ``` +## cborHeaderSize + +The byte width of the CBOR item header at `offset`. + +Paired with {@link CBOR.decodeItemWithOffset} this is what slices an element out of a CBOR +array **byte-exactly** — `decodeItemWithOffset` gives the end of an item, this gives the start +of the first one inside a container. `extractBodyBytes` is one such slice; a wallet that +reviews a transaction before signing needs the same for the witness set and the auxiliary +data, and a re-encode is not a substitute because a span that differs by one byte is a +different transaction id. + +**Signature** + +```ts +export declare const cborHeaderSize: (data: Uint8Array, offset: number) => number +``` + +Added in v2.2.0 + ## fromCBORBytes **Signature** @@ -349,7 +405,7 @@ export declare const fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => **Signature** ```ts -export declare const toCBORBytes: (data: Transaction, options?: CBOR.CodecOptions) => Uint8Array +export declare const toCBORBytes: (data: Transaction, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => Uint8Array ``` ## toCBORHex @@ -357,5 +413,5 @@ export declare const toCBORBytes: (data: Transaction, options?: CBOR.CodecOption **Signature** ```ts -export declare const toCBORHex: (data: Transaction, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (data: Transaction, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` diff --git a/docs/content/docs/modules/TransactionBody.mdx b/docs/content/docs/modules/TransactionBody.mdx index b637eb0c..2b9bfe32 100644 --- a/docs/content/docs/modules/TransactionBody.mdx +++ b/docs/content/docs/modules/TransactionBody.mdx @@ -1,6 +1,7 @@ --- + title: TransactionBody.ts -nav_order: 170 +nav_order: 176 parent: Modules --- @@ -10,6 +11,8 @@ parent: Modules

Table of contents

+- [constructors](#constructors) + - [fromEncoded](#fromencoded) - [conversion](#conversion) - [fromCBORBytes](#fromcborbytes) - [fromCBORBytesWithFormat](#fromcborbyteswithformat) @@ -33,13 +36,47 @@ parent: Modules - [CDDLSchema](#cddlschema) - [FromCBORBytes](#fromcborbytes-1) - [FromCBORHex](#fromcborhex-1) -- [utils](#utils) - [FromCDDL](#fromcddl) +- [utils](#utils) - [arbitrary](#arbitrary) - [isTransactionBody](#istransactionbody) --- +# constructors + +## fromEncoded + +Assemble a body from parts that are already encoded. + +⚠️ **This is what a transaction builder needs and the typed constructor is not.** A builder +accumulates body fields from plugins as bytes -- a certificate from one, a withdrawal map from +another, a `script_data_hash` computed over bytes it does not model -- and has no typed value +for most of them. Without this it either reaches for a hex-shaped service of its own (which is +how a 109-operation parallel codec came to exist) or re-derives the bytes it was given. + +`inputs` and `outputs` are item bytes and are written as the `#6.258` set and the array Conway +expects. `fields` carries everything else by its CDDL key; a key this type does not model +throws rather than being dropped, because a dropped field is a body the caller did not ask for +and will sign anyway. + +The result is an ordinary {@link TransactionBody}, so it has NO recorded arrival bytes and +{@link toCBORBytes} encodes it structurally -- which is correct: it was built here, not decoded. + +**Signature** + +```ts +export declare const fromEncoded: (input: { + readonly inputs: ReadonlyArray + readonly outputs: ReadonlyArray + readonly fee: bigint + readonly ttl?: bigint + readonly fields?: ReadonlyArray +}) => TransactionBody +``` + +Added in v2.8.0 + # conversion ## fromCBORBytes @@ -97,7 +134,7 @@ Convert TransactionBody to CBOR bytes. **Signature** ```ts -export declare const toCBORBytes: (data: TransactionBody, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: (data: TransactionBody, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => any ``` Added in v2.0.0 @@ -121,7 +158,7 @@ Convert TransactionBody to CBOR hex string. **Signature** ```ts -export declare const toCBORHex: (data: TransactionBody, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (data: TransactionBody, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 @@ -267,11 +304,15 @@ Added in v2.0.0 CBOR bytes transformation schema for TransactionBody. Transforms between CBOR bytes and TransactionBody using Conway CDDL specification. +A new inline datum is written with the `plutusData` options, the rest with +the `ledger` options. Plain options are read as `CBOR.toTxCodecOptions` +reads them. + **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, @@ -290,37 +331,37 @@ Added in v2.0.0 ## FromCBORHex -CBOR hex transformation schema for TransactionBody. -Transforms between CBOR hex string and TransactionBody using Conway CDDL specification. +CBOR hex transformation schema for TransactionBody, as in {@link FromCBORBytes}. **Signature** ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< + Schema.Schema, Schema.transform< - Schema.Schema, Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, Schema.declare, never + >, + Schema.transformOrFail< + Schema.declare, Map, readonly [], never>, + Schema.SchemaClass, + never > - >, - Schema.transformOrFail< - Schema.declare, Map, readonly [], never>, - Schema.SchemaClass, - never > > ``` Added in v2.0.0 -# utils - ## FromCDDL +CDDL transformation schema for TransactionBody. A new inline datum is +written with `Data.DEFAULT_CBOR_OPTIONS`. + **Signature** ```ts @@ -331,6 +372,10 @@ export declare const FromCDDL: Schema.transformOrFail< > ``` +Added in v2.0.0 + +# utils + ## arbitrary **Signature** diff --git a/docs/content/docs/modules/TransactionHash.mdx b/docs/content/docs/modules/TransactionHash.mdx index 5a96ce42..40d1c48f 100644 --- a/docs/content/docs/modules/TransactionHash.mdx +++ b/docs/content/docs/modules/TransactionHash.mdx @@ -1,6 +1,7 @@ --- + title: TransactionHash.ts -nav_order: 171 +nav_order: 177 parent: Modules --- @@ -15,13 +16,15 @@ parent: Modules - [encoding](#encoding) - [toBytes](#tobytes) - [toHex](#tohex) +- [model](#model) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isTransactionHash](#istransactionhash) - [schemas](#schemas) - [FromBytes](#frombytes-1) + - [Hex](#hex) - [TransactionHash (class)](#transactionhash-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) @@ -29,7 +32,8 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) - [utils](#utils) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [fromHex](#fromhex-1) --- @@ -68,33 +72,33 @@ Encode TransactionHash to hex string. **Signature** ```ts -export declare const toHex: (a: TransactionHash, overrideOptions?: ParseOptions) => string +export declare const toHex: (value: Parameters[0]) => Hex ``` Added in v2.0.0 -# parsing - -## fromBytes +# model -Parse TransactionHash from bytes. +## Hex (type alias) **Signature** ```ts -export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => TransactionHash +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 -## fromHex +# parsing + +## fromBytes -Parse TransactionHash from hex string. +Parse TransactionHash from bytes. **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => TransactionHash +export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) => TransactionHash ``` Added in v2.0.0 @@ -130,6 +134,25 @@ export declare const FromBytes: Schema.transform< Added in v2.0.0 +## Hex + +A transaction hash as hex. + +Validated as well as branded: a 32-byte lowercase or uppercase hex string. {@link toHex} +returns this type, so the kind of a hex string survives leaving the typed domain — upstream of +this, every hash and key was an unmarked `string` once encoded. + +⚠️ Branded apart from every other 32-byte hash hex. They are the same shape, and the type +system is the only thing standing between a transaction hash and a datum hash. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "TransactionHashHex"> +``` + +Added in v2.4.0 + ## TransactionHash (class) Schema for TransactionHash. @@ -198,3 +221,11 @@ export declare const FromHex: Schema.transform< > > ``` + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => TransactionHash +``` diff --git a/docs/content/docs/modules/TransactionIndex.mdx b/docs/content/docs/modules/TransactionIndex.mdx index 01d6052b..29a61b54 100644 --- a/docs/content/docs/modules/TransactionIndex.mdx +++ b/docs/content/docs/modules/TransactionIndex.mdx @@ -1,6 +1,7 @@ --- + title: TransactionIndex.ts -nav_order: 172 +nav_order: 178 parent: Modules --- diff --git a/docs/content/docs/modules/TransactionInput.mdx b/docs/content/docs/modules/TransactionInput.mdx index f0daef64..f9fa4acb 100644 --- a/docs/content/docs/modules/TransactionInput.mdx +++ b/docs/content/docs/modules/TransactionInput.mdx @@ -1,6 +1,7 @@ --- + title: TransactionInput.ts -nav_order: 173 +nav_order: 179 parent: Modules --- diff --git a/docs/content/docs/modules/TransactionMetadatum.mdx b/docs/content/docs/modules/TransactionMetadatum.mdx index dccce85e..76a7c5de 100644 --- a/docs/content/docs/modules/TransactionMetadatum.mdx +++ b/docs/content/docs/modules/TransactionMetadatum.mdx @@ -1,6 +1,7 @@ --- + title: TransactionMetadatum.ts -nav_order: 174 +nav_order: 180 parent: Modules --- @@ -34,12 +35,12 @@ parent: Modules - [BytesSchema](#bytesschema) - [FromCBORBytes](#fromcborbytes-1) - [FromCBORHex](#fromcborhex-1) - - [IntSchema](#intschema) - [ListSchema](#listschema) - [MapSchema](#mapschema) - [TextSchema](#textschema) - [TransactionMetadatumSchema](#transactionmetadatumschema) - [utils](#utils) + - [IntSchema](#intschema) - [arbitrary](#arbitrary) --- @@ -362,18 +363,6 @@ export declare const FromCBORHex: ( Added in v2.0.0 -## IntSchema - -Schema for TransactionMetadatum integer type - -**Signature** - -```ts -export declare const IntSchema: Schema.refine -``` - -Added in v2.0.0 - ## ListSchema Schema for TransactionMetadatum list type @@ -454,6 +443,20 @@ Added in v2.0.0 # utils +## IntSchema + +⚠️ The CDDL is `transaction_metadatum = ... / int / ...` where `int = uint / nint`, so the +range is -2^64 .. 2^64-1 -- NOT a signed 64-bit integer. This was `Numeric.Int64`, which meant +a metadatum carrying any value in [2^63, 2^64-1] could neither be built nor, worse, **read off +the chain**: decoding `1bffffffffffffffff` failed outright. That is valid CBOR a transaction +can legitimately carry. + +**Signature** + +```ts +export declare const IntSchema: Schema.refine +``` + ## arbitrary **Signature** diff --git a/docs/content/docs/modules/TransactionMetadatumLabels.mdx b/docs/content/docs/modules/TransactionMetadatumLabels.mdx index bebd157a..fa490dec 100644 --- a/docs/content/docs/modules/TransactionMetadatumLabels.mdx +++ b/docs/content/docs/modules/TransactionMetadatumLabels.mdx @@ -1,6 +1,7 @@ --- + title: TransactionMetadatumLabels.ts -nav_order: 175 +nav_order: 181 parent: Modules --- diff --git a/docs/content/docs/modules/TransactionOutput.mdx b/docs/content/docs/modules/TransactionOutput.mdx index b0b0d0ce..3a455ad1 100644 --- a/docs/content/docs/modules/TransactionOutput.mdx +++ b/docs/content/docs/modules/TransactionOutput.mdx @@ -1,528 +1,59 @@ --- + title: TransactionOutput.ts -nav_order: 176 +nav_order: 182 parent: Modules --- ## TransactionOutput overview ---- - -

Table of contents

- -- [arbitrary](#arbitrary) - - [arbitrary](#arbitrary-1) -- [decoding](#decoding) - - [fromCBORBytes](#fromcborbytes) - - [fromCBORHex](#fromcborhex) -- [encoding](#encoding) - - [toCBORBytes](#tocborbytes) - - [toCBORHex](#tocborhex) -- [model](#model) - - [BabbageTransactionOutput (class)](#babbagetransactionoutput-class) - - [toJSON (method)](#tojson-method) - - [toString (method)](#tostring-method) - - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - - [[Equal.symbol] (method)](#equalsymbol-method) - - [[Hash.symbol] (method)](#hashsymbol-method) - - [ShelleyTransactionOutput (class)](#shelleytransactionoutput-class) - - [toJSON (method)](#tojson-method-1) - - [toString (method)](#tostring-method-1) - - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method-1) - - [[Equal.symbol] (method)](#equalsymbol-method-1) - - [[Hash.symbol] (method)](#hashsymbol-method-1) -- [schemas](#schemas) - - [TransactionOutput](#transactionoutput) -- [transformation](#transformation) - - [FromBabbageTransactionOutputCDDLSchema](#frombabbagetransactionoutputcddlschema) - - [FromShelleyTransactionOutputCDDLSchema](#fromshelleytransactionoutputcddlschema) -- [transformer](#transformer) - - [FromCBORBytes](#fromcborbytes-1) - - [FromCBORHex](#fromcborhex-1) - - [FromCDDL](#fromcddl) -- [utils](#utils) - - [CDDLSchema](#cddlschema) - - [ShelleyTransactionOutputCDDL](#shelleytransactionoutputcddl) - - [TransactionOutput (type alias)](#transactionoutput-type-alias) - ---- - -# arbitrary - -## arbitrary - -**Signature** - -```ts -export declare const arbitrary: FastCheck.Arbitrary -``` - -Added in v2.0.0 - -# decoding - -## fromCBORBytes - -Parse TransactionOutput from CBOR bytes. - -**Signature** - -```ts -export declare const fromCBORBytes: ( - bytes: Uint8Array, - options?: CBOR.CodecOptions -) => ShelleyTransactionOutput | BabbageTransactionOutput -``` - -Added in v2.0.0 - -## fromCBORHex - -Parse TransactionOutput from CBOR hex. - -**Signature** - -```ts -export declare const fromCBORHex: ( - hex: string, - options?: CBOR.CodecOptions -) => ShelleyTransactionOutput | BabbageTransactionOutput -``` - -Added in v2.0.0 - -# encoding - -## toCBORBytes - -Convert TransactionOutput to CBOR bytes. - -**Signature** - -```ts -export declare const toCBORBytes: (data: TransactionOutput, options?: CBOR.CodecOptions) => any -``` - -Added in v2.0.0 - -## toCBORHex - -Convert TransactionOutput to CBOR hex. - -**Signature** - -```ts -export declare const toCBORHex: (data: TransactionOutput, options?: CBOR.CodecOptions) => string -``` - -Added in v2.0.0 - -# model - -## BabbageTransactionOutput (class) - -Babbage-era transaction output format - -CDDL: - -``` -babbage_transaction_output = - {0 : address, 1 : value, ? 2 : datum_option, ? 3 : script_ref} -``` - -**Signature** - -```ts -export declare class BabbageTransactionOutput -``` - -Added in v2.0.0 - -### toJSON (method) - -**Signature** - -```ts -toJSON() -``` - -### toString (method) - -**Signature** - -```ts -toString(): string -``` - -### [Inspectable.NodeInspectSymbol] (method) - -**Signature** - -```ts -[Inspectable.NodeInspectSymbol](): unknown -``` - -### [Equal.symbol] (method) - -**Signature** - -```ts -[Equal.symbol](that: unknown): boolean -``` - -### [Hash.symbol] (method) - -**Signature** - -```ts -[Hash.symbol](): number -``` - -## ShelleyTransactionOutput (class) - -Shelley-era transaction output format - -CDDL: +Transaction outputs. -``` -shelley_transaction_output = [address, amount : value, ? Bytes32] -``` +This module used to carry a SECOND, parallel model of a transaction output -- a union of a +`ShelleyTransactionOutput` and a `BabbageTransactionOutput` class, with `address: AddressEras` +and `amount: Value` -- while `TxOut` carried the one `TransactionBody`, the builders and the +sdk actually use (`address: Address`, `assets: Assets`, one class covering both eras). -**Signature** +Both were public from the package entry point, under names that gave no hint which was which, +and they rejected each other: an output built with this module could not be placed in a +`TransactionBody`, and the error said `Expected TransactionOutput, actual [toString threw]` +about a value that was a `TransactionOutput` -- the other one. -```ts -export declare class ShelleyTransactionOutput -``` +The name now refers to the model that works. Everything here is `TxOut`. Added in v2.0.0 -### toJSON (method) - -**Signature** - -```ts -toJSON() -``` - -### toString (method) - -**Signature** - -```ts -toString(): string -``` - -### [Inspectable.NodeInspectSymbol] (method) - -**Signature** - -```ts -[Inspectable.NodeInspectSymbol](): unknown -``` - -### [Equal.symbol] (method) - -**Signature** - -```ts -[Equal.symbol](that: unknown): boolean -``` - -### [Hash.symbol] (method) - -**Signature** - -```ts -[Hash.symbol](): number -``` - -# schemas - -## TransactionOutput - -Union type for transaction outputs - -CDDL: - -``` -transaction_output = shelley_transaction_output / babbage_transaction_output -``` - -**Signature** - -```ts -export declare const TransactionOutput: Schema.Union<[typeof ShelleyTransactionOutput, typeof BabbageTransactionOutput]> -``` - -Added in v2.0.0 - -# transformation - -## FromBabbageTransactionOutputCDDLSchema - -CDDL schema for Babbage transaction outputs - -**Signature** - -```ts -export declare const FromBabbageTransactionOutputCDDLSchema: Schema.transformOrFail< - Schema.MapFromSelf>, - Schema.SchemaClass, - never -> -``` - -Added in v2.0.0 - -## FromShelleyTransactionOutputCDDLSchema - -CDDL schema for Shelley transaction outputs - -**Signature** - -```ts -export declare const FromShelleyTransactionOutputCDDLSchema: Schema.transformOrFail< - Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] - >, - Schema.SchemaClass, - never -> -``` - -Added in v2.0.0 - -# transformer - -## FromCBORBytes - -CBOR bytes transformation schema for TransactionOutput. - -**Signature** +--- -```ts -export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.Union< - [ - Schema.transformOrFail< - Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] - >, - Schema.SchemaClass, - never - >, - Schema.transformOrFail< - Schema.MapFromSelf>, - Schema.SchemaClass, - never - > - ] - > -> -``` +

Table of contents

-Added in v2.0.0 +- [exports](#exports) + - [From "./TxOut.js"](#from-txoutjs) -## FromCBORHex +--- -CBOR hex transformation schema for TransactionOutput. +# exports -**Signature** +## From "./TxOut.js" -```ts -export declare const FromCBORHex: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.Schema, - Schema.transform< - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.Union< - [ - Schema.transformOrFail< - Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] - >, - Schema.SchemaClass, - never - >, - Schema.transformOrFail< - Schema.MapFromSelf>, - Schema.SchemaClass, - never - > - ] - > - > -> -``` +Transaction outputs. -Added in v2.0.0 +This module used to carry a SECOND, parallel model of a transaction output -- a union of a +`ShelleyTransactionOutput` and a `BabbageTransactionOutput` class, with `address: AddressEras` +and `amount: Value` -- while `TxOut` carried the one `TransactionBody`, the builders and the +sdk actually use (`address: Address`, `assets: Assets`, one class covering both eras). -## FromCDDL +Both were public from the package entry point, under names that gave no hint which was which, +and they rejected each other: an output built with this module could not be placed in a +`TransactionBody`, and the error said `Expected TransactionOutput, actual [toString threw]` +about a value that was a `TransactionOutput` -- the other one. -CDDL schema for transaction outputs +The name now refers to the model that works. Everything here is `TxOut`. **Signature** ```ts -export declare const FromCDDL: Schema.Union< - [ - Schema.transformOrFail< - Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] - >, - Schema.SchemaClass, - never - >, - Schema.transformOrFail< - Schema.MapFromSelf>, - Schema.SchemaClass, - never - > - ] -> +export * from "./TxOut.js" ``` Added in v2.0.0 - -# utils - -## CDDLSchema - -**Signature** - -```ts -export declare const CDDLSchema: Schema.Union< - [ - Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] - >, - Schema.MapFromSelf> - ] -> -``` - -## ShelleyTransactionOutputCDDL - -**Signature** - -```ts -export declare const ShelleyTransactionOutputCDDL: Schema.Tuple< - [ - typeof Schema.Uint8ArrayFromSelf, - Schema.Union< - [ - typeof Schema.BigIntFromSelf, - Schema.Tuple2< - typeof Schema.BigIntFromSelf, - Schema.SchemaClass< - ReadonlyMap>, - ReadonlyMap>, - never - > - > - ] - >, - Schema.Element - ] -> -``` - -## TransactionOutput (type alias) - -**Signature** - -```ts -export type TransactionOutput = typeof TransactionOutput.Type -``` diff --git a/docs/content/docs/modules/TransactionWitnessSet.mdx b/docs/content/docs/modules/TransactionWitnessSet.mdx index 275ff898..94e99561 100644 --- a/docs/content/docs/modules/TransactionWitnessSet.mdx +++ b/docs/content/docs/modules/TransactionWitnessSet.mdx @@ -1,6 +1,7 @@ --- + title: TransactionWitnessSet.ts -nav_order: 177 +nav_order: 183 parent: Modules --- @@ -14,6 +15,7 @@ parent: Modules - [arbitrary](#arbitrary-1) - [constructors](#constructors) - [empty](#empty) + - [fromEncoded](#fromencoded) - [fromNativeScripts](#fromnativescripts) - [fromVKeyWitnesses](#fromvkeywitnesses) - [encoding](#encoding) @@ -36,17 +38,17 @@ parent: Modules - [[Equal.symbol] (method)](#equalsymbol-method-1) - [[Hash.symbol] (method)](#hashsymbol-method-1) - [parsing](#parsing) - - [fromCBORBytes](#fromcborbytes) - [fromCBORBytesWithFormat](#fromcborbyteswithformat) - [fromCBORHex](#fromcborhex) - [fromCBORHexWithFormat](#fromcborhexwithformat) - [schemas](#schemas) - [CDDLSchema](#cddlschema) + - [FromCBORBytes](#fromcborbytes) + - [FromCBORHex](#fromcborhex-1) - [FromCDDL](#fromcddl) - [utils](#utils) - - [FromCBORBytes](#fromcborbytes-1) - - [FromCBORHex](#fromcborhex-1) - [PlutusScript (type alias)](#plutusscript-type-alias) + - [fromCBORBytes](#fromcborbytes-1) --- @@ -78,6 +80,40 @@ export declare const empty: () => TransactionWitnessSet Added in v2.0.0 +## fromEncoded + +Assemble a witness set from parts that are already encoded. + +The counterpart of `TransactionBody.fromEncoded`, and needed for the same reason: a builder +holds a witness set's contents as bytes, produced by whatever supplied the scripts. + +`fields` carries the script fields (3, 6, 7), `plutus_data` (4) and `redeemers` (5) by their +CDDL key. The script fields and `plutus_data` are given as the whole encoded `#6.258` set and +split into items; `redeemers` is the encoded map. + +⚠️ Keys 4 and 5 are the two that are NOT script-shaped, and a version of this table that +handled only the script shape made assembling the witness set of ANY Plutus transaction throw -- +including the sizing pass every fee estimate runs. No vector reached it because every +transaction under test had been script-free. + +⚠️ `plutus_data` items go through `Data.fromCBORBytes`, which records each datum's arrival +bytes, so a datum re-encodes as it came. Splitting the set with `CBOR.splitArrayItems` is the +other half of that: decoding the set and re-encoding its items would reframe them before the +datums were ever read. + +**Signature** + +```ts +export declare const fromEncoded: (input: { + readonly vkeyWitnesses?: ReadonlyArray<{ readonly vkey: Uint8Array; readonly signature: Uint8Array }> + readonly nativeScripts?: ReadonlyArray + readonly bootstrapWitnesses?: ReadonlyArray + readonly fields?: ReadonlyArray +}) => TransactionWitnessSet +``` + +Added in v2.8.0 + ## fromNativeScripts Create a TransactionWitnessSet with only native scripts. @@ -106,12 +142,15 @@ Added in v2.0.0 ## toCBORBytes -Convert a TransactionWitnessSet to CBOR bytes. +Convert a TransactionWitnessSet to CBOR bytes, as in {@link FromCBORBytes}. **Signature** ```ts -export declare const toCBORBytes: (data: TransactionWitnessSet, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: ( + data: TransactionWitnessSet, + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => any ``` Added in v2.0.0 @@ -120,6 +159,10 @@ Added in v2.0.0 Convert a TransactionWitnessSet to CBOR bytes using an explicit root format tree. +Datums and redeemers the format tree covers keep their captured format. A +datum or redeemer added to a decoded witness set is written as +{@link toCBORBytes} writes it under the default options. + **Signature** ```ts @@ -130,19 +173,23 @@ Added in v2.0.0 ## toCBORHex -Convert a TransactionWitnessSet to CBOR hex string. +Convert a TransactionWitnessSet to CBOR hex string, as in {@link toCBORBytes}. **Signature** ```ts -export declare const toCBORHex: (data: TransactionWitnessSet, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: ( + data: TransactionWitnessSet, + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => string ``` Added in v2.0.0 ## toCBORHexWithFormat -Convert a TransactionWitnessSet to CBOR hex string using an explicit root format tree. +Convert a TransactionWitnessSet to CBOR hex string using an explicit root +format tree, as in {@link toCBORBytesWithFormat}. **Signature** @@ -318,18 +365,6 @@ Added in v2.0.0 # parsing -## fromCBORBytes - -Parse a TransactionWitnessSet from CBOR bytes. - -**Signature** - -```ts -export declare const fromCBORBytes: (bytes: Uint8Array, options?: CBOR.CodecOptions) => TransactionWitnessSet -``` - -Added in v2.0.0 - ## fromCBORBytesWithFormat Parse a TransactionWitnessSet from CBOR bytes and return the root format tree. @@ -394,15 +429,20 @@ export declare const CDDLSchema: Schema.declare, Map, Map, readonly [], never>, +export declare const FromCBORBytes: ( + options?: CBOR.TxCodecOptions | CBOR.CodecOptions +) => Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, Schema.SchemaClass, never > @@ -410,53 +450,46 @@ export declare const FromCDDL: Schema.transformOrFail< Added in v2.0.0 -# utils +## FromCBORHex -## FromCBORBytes +CBOR hex transformation schema for TransactionWitnessSet, as in +{@link FromCBORBytes}. **Signature** ```ts -export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions +export declare const FromCBORHex: ( + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< + Schema.Schema, Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - >, - Schema.transformOrFail< - Schema.declare, Map, readonly [], never>, Schema.SchemaClass, never > > ``` -## FromCBORHex +Added in v2.0.0 + +## FromCDDL + +CDDL transformation schema for TransactionWitnessSet. **Signature** ```ts -export declare const FromCBORHex: ( - options?: CBOR.CodecOptions -) => Schema.transform< - Schema.transform< - Schema.Schema, - Schema.transformOrFail< - typeof Schema.Uint8ArrayFromSelf, - Schema.declare, - never - > - >, - Schema.transformOrFail< - Schema.declare, Map, readonly [], never>, - Schema.SchemaClass, - never - > +export declare const FromCDDL: Schema.transformOrFail< + Schema.declare, Map, readonly [], never>, + Schema.SchemaClass, + never > ``` +Added in v2.0.0 + +# utils + ## PlutusScript (type alias) **Signature** @@ -464,3 +497,11 @@ export declare const FromCBORHex: ( ```ts export type PlutusScript = typeof PlutusScript.Type ``` + +## fromCBORBytes + +**Signature** + +```ts +export declare const fromCBORBytes: (bytes: Uint8Array, options?: CBOR.CodecOptions) => TransactionWitnessSet +``` diff --git a/docs/content/docs/modules/TxOut.mdx b/docs/content/docs/modules/TxOut.mdx index 3f19ac8d..e26df916 100644 --- a/docs/content/docs/modules/TxOut.mdx +++ b/docs/content/docs/modules/TxOut.mdx @@ -1,6 +1,7 @@ --- + title: TxOut.ts -nav_order: 179 +nav_order: 184 parent: Modules --- @@ -33,6 +34,7 @@ parent: Modules - [FromBabbageTransactionOutputCDDL](#frombabbagetransactionoutputcddl) - [FromCDDL](#fromcddl) - [FromShelleyTransactionOutputCDDL](#fromshelleytransactionoutputcddl) + - [makeFromCDDL](#makefromcddl) - [transformer](#transformer) - [FromCBORBytes](#fromcborbytes-1) - [FromCBORHex](#fromcborhex-1) @@ -86,7 +88,7 @@ Convert TransactionOutput to CBOR bytes. **Signature** ```ts -export declare const toCBORBytes: (data: TransactionOutput, options?: CBOR.CodecOptions) => any +export declare const toCBORBytes: (data: TransactionOutput, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => any ``` Added in v2.0.0 @@ -98,7 +100,7 @@ Convert TransactionOutput to CBOR hex. **Signature** ```ts -export declare const toCBORHex: (data: TransactionOutput, options?: CBOR.CodecOptions) => string +export declare const toCBORHex: (data: TransactionOutput, options?: CBOR.TxCodecOptions | CBOR.CodecOptions) => string ``` Added in v2.0.0 @@ -259,6 +261,8 @@ Encoding logic: Decoding: Accepts both formats +A new inline datum is written with `Data.DEFAULT_CBOR_OPTIONS`. + **Signature** ```ts @@ -312,17 +316,53 @@ export declare const FromShelleyTransactionOutputCDDL: Schema.transformOrFail< Added in v2.0.0 +## makeFromCDDL + +CDDL transformation schema for transaction outputs, as in {@link FromCDDL}, +that writes a new inline datum with the `plutusData` options. + +**Signature** + +```ts +export declare const makeFromCDDL: ( + plutusData: CBOR.CodecOptions +) => Schema.transformOrFail< + Schema.Union< + [ + Schema.Tuple< + [ + typeof Schema.Uint8ArrayFromSelf, + Schema.SchemaClass< + bigint | readonly [bigint, ReadonlyMap>], + bigint | readonly [bigint, ReadonlyMap>], + never + >, + Schema.Element + ] + >, + Schema.MapFromSelf> + ] + >, + Schema.SchemaClass, + never +> +``` + +Added in v2.0.0 + # transformer ## FromCBORBytes -CBOR bytes transformation schema for TransactionOutput. +CBOR bytes transformation schema for TransactionOutput. A new inline datum +is written with the `plutusData` options, the rest with the `ledger` +options. Plain options are read as `CBOR.toTxCodecOptions` reads them. **Signature** ```ts export declare const FromCBORBytes: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.transformOrFail< typeof Schema.Uint8ArrayFromSelf, @@ -356,13 +396,14 @@ Added in v2.0.0 ## FromCBORHex -CBOR hex transformation schema for TransactionOutput. +CBOR hex transformation schema for TransactionOutput, as in +{@link FromCBORBytes}. **Signature** ```ts export declare const FromCBORHex: ( - options?: CBOR.CodecOptions + options?: CBOR.TxCodecOptions | CBOR.CodecOptions ) => Schema.transform< Schema.Schema, Schema.transform< diff --git a/docs/content/docs/modules/UPLC.mdx b/docs/content/docs/modules/UPLC.mdx index ebb9bce9..a1b92bf3 100644 --- a/docs/content/docs/modules/UPLC.mdx +++ b/docs/content/docs/modules/UPLC.mdx @@ -1,6 +1,7 @@ --- + title: UPLC.ts -nav_order: 183 +nav_order: 188 parent: Modules --- @@ -357,9 +358,10 @@ Added in v2.0.0 Create a UPLC Constant term from PlutusData. The data is CBOR-encoded and stored as a constant of type Data. -Uses Aiken-compatible encoding (indefinite-length arrays/maps) by default, -which matches the on-chain format. An optional `options` parameter allows -customizing the CBOR encoding for testing or compatibility purposes. +Encodes with PLUTUS_DATA_OPTIONS by default: the node layout, with +indefinite-length lists and constructor fields and definite-length maps. +This matches Aiken `cbor.serialise()`. An optional `options` parameter +allows customizing the CBOR encoding for testing or compatibility purposes. **Signature** @@ -525,9 +527,7 @@ UPLC data type (recursive for pair/list). ```ts export type DataType = - | PrimitiveDataType - | { readonly pair: readonly [DataType, DataType] } - | { readonly list: DataType } + PrimitiveDataType | { readonly pair: readonly [DataType, DataType] } | { readonly list: DataType } ``` Added in v2.0.0 @@ -771,8 +771,11 @@ The function takes a CBOR-encoded script and applies each parameter by wrapping the script body in a series of Application nodes, where each parameter is converted to a UPLC Constant of type Data. -Uses Aiken-compatible encoding (indefinite-length arrays/maps) by default. -Pass custom CBOR options for compatibility with other encoding formats. +Encodes parameters with PLUTUS_DATA_OPTIONS by default: the node layout, +with indefinite-length lists and constructor fields and definite-length +maps. This matches `aiken blueprint apply`, so the applied script hash +agrees. Pass custom CBOR options for compatibility with other encoding +formats. **Signature** diff --git a/docs/content/docs/modules/UTxO.mdx b/docs/content/docs/modules/UTxO.mdx index 58bc281e..ef772702 100644 --- a/docs/content/docs/modules/UTxO.mdx +++ b/docs/content/docs/modules/UTxO.mdx @@ -1,6 +1,7 @@ --- + title: UTxO.ts -nav_order: 185 +nav_order: 190 parent: Modules --- diff --git a/docs/content/docs/modules/Unit.mdx b/docs/content/docs/modules/Unit.mdx index a01c08a6..05745fa1 100644 --- a/docs/content/docs/modules/Unit.mdx +++ b/docs/content/docs/modules/Unit.mdx @@ -1,6 +1,7 @@ --- + title: Unit.ts -nav_order: 180 +nav_order: 185 parent: Modules --- diff --git a/docs/content/docs/modules/UnitInterval.mdx b/docs/content/docs/modules/UnitInterval.mdx index cca3a31a..32abc125 100644 --- a/docs/content/docs/modules/UnitInterval.mdx +++ b/docs/content/docs/modules/UnitInterval.mdx @@ -1,6 +1,7 @@ --- + title: UnitInterval.ts -nav_order: 181 +nav_order: 186 parent: Modules --- @@ -14,6 +15,9 @@ parent: Modules - [arbitrary](#arbitrary-1) - [constructors](#constructors) - [fromBigDecimal](#frombigdecimal) +- [encoding](#encoding) + - [toCBORBytes](#tocborbytes) + - [toCBORHex](#tocborhex) - [model](#model) - [UnitInterval (class)](#unitinterval-class) - [toJSON (method)](#tojson-method) @@ -21,9 +25,12 @@ parent: Modules - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) +- [parsing](#parsing) + - [fromCBORBytes](#fromcborbytes) + - [fromCBORHex](#fromcborhex) - [schemas](#schemas) - - [FromCBORBytes](#fromcborbytes) - - [FromCBORHex](#fromcborhex) + - [FromCBORBytes](#fromcborbytes-1) + - [FromCBORHex](#fromcborhex-1) - [FromCDDL](#fromcddl) - [transformation](#transformation) - [toBigDecimal](#tobigdecimal) @@ -60,6 +67,32 @@ export declare const fromBigDecimal: (value: BigDecimal.BigDecimal) => UnitInter Added in v2.0.0 +# encoding + +## toCBORBytes + +Convert UnitInterval to CBOR bytes. + +**Signature** + +```ts +export declare const toCBORBytes: (input: UnitInterval, options?: CBOR.CodecOptions) => any +``` + +Added in v2.0.0 + +## toCBORHex + +Convert UnitInterval to a CBOR hex string. + +**Signature** + +```ts +export declare const toCBORHex: (input: UnitInterval, options?: CBOR.CodecOptions) => string +``` + +Added in v2.0.0 + # model ## UnitInterval (class) @@ -146,6 +179,32 @@ Hash code generation. Added in v2.0.0 +# parsing + +## fromCBORBytes + +Parse UnitInterval from CBOR bytes. + +**Signature** + +```ts +export declare const fromCBORBytes: (bytes: Uint8Array, options?: CBOR.CodecOptions) => UnitInterval +``` + +Added in v2.0.0 + +## fromCBORHex + +Parse UnitInterval from a CBOR hex string. + +**Signature** + +```ts +export declare const fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => UnitInterval +``` + +Added in v2.0.0 + # schemas ## FromCBORBytes diff --git a/docs/content/docs/modules/UnixTime.mdx b/docs/content/docs/modules/UnixTime.mdx index 5d6a20c2..415fc349 100644 --- a/docs/content/docs/modules/UnixTime.mdx +++ b/docs/content/docs/modules/UnixTime.mdx @@ -1,6 +1,7 @@ --- + title: UnixTime.ts -nav_order: 182 +nav_order: 187 parent: Modules --- diff --git a/docs/content/docs/modules/Url.mdx b/docs/content/docs/modules/Url.mdx index 79ee8944..e09d1889 100644 --- a/docs/content/docs/modules/Url.mdx +++ b/docs/content/docs/modules/Url.mdx @@ -1,6 +1,7 @@ --- + title: Url.ts -nav_order: 184 +nav_order: 189 parent: Modules --- diff --git a/docs/content/docs/modules/VKey.mdx b/docs/content/docs/modules/VKey.mdx index cd0bb7a5..e97b5e32 100644 --- a/docs/content/docs/modules/VKey.mdx +++ b/docs/content/docs/modules/VKey.mdx @@ -1,6 +1,7 @@ --- + title: VKey.ts -nav_order: 187 +nav_order: 192 parent: Modules --- @@ -15,13 +16,14 @@ parent: Modules - [verify](#verify) - [encoding](#encoding) - [toBytes](#tobytes) - - [toHex](#tohex) +- [model](#model) + - [Hex (type alias)](#hex-type-alias) - [parsing](#parsing) - [fromBytes](#frombytes) - - [fromHex](#fromhex) - [predicates](#predicates) - [isVKey](#isvkey) - [schemas](#schemas) + - [Hex](#hex) - [VKey (class)](#vkey-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) @@ -32,7 +34,9 @@ parent: Modules - [arbitrary](#arbitrary) - [utils](#utils) - [FromBytes](#frombytes-1) - - [FromHex](#fromhex-1) + - [FromHex](#fromhex) + - [fromHex](#fromhex-1) + - [toHex](#tohex) --- @@ -78,17 +82,17 @@ export declare const toBytes: (a: VKey, overrideOptions?: ParseOptions) => Uint8 Added in v2.0.0 -## toHex +# model -Convert a VKey to a hex string. +## Hex (type alias) **Signature** ```ts -export declare const toHex: (a: VKey, overrideOptions?: ParseOptions) => string +export type Hex = typeof Hex.Type ``` -Added in v2.0.0 +Added in v2.4.0 # parsing @@ -105,34 +109,39 @@ export declare const fromBytes: (i: Uint8Array, overrideOptions?: ParseOptions) Added in v2.0.0 -## fromHex +# predicates -Parse a VKey from a hex string. -Expects exactly 64 hex characters (32 bytes). +## isVKey + +Check if the given value is a valid VKey **Signature** ```ts -export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => VKey +export declare const isVKey: (u: unknown, overrideOptions?: ParseOptions | number) => u is VKey ``` Added in v2.0.0 -# predicates +# schemas -## isVKey +## Hex -Check if the given value is a valid VKey +An Ed25519 verification key as hex (32 bytes). + +Validated as well as branded: a 32-byte hex string, either case. {@link toHex} returns +this type, so the kind survives leaving the typed domain. + +⚠️ Not the 64-byte BIP32 extended form: a verifier handed the extended form where this belongs +fails on every signature. See {@link Bip32PublicKey.Hex}. **Signature** ```ts -export declare const isVKey: (u: unknown, overrideOptions?: ParseOptions | number) => u is VKey +export declare const Hex: Schema.brand, "VKeyHex"> ``` -Added in v2.0.0 - -# schemas +Added in v2.4.0 ## VKey (class) @@ -226,3 +235,19 @@ export declare const FromHex: Schema.transform< Schema.transform, Schema.SchemaClass> > ``` + +## fromHex + +**Signature** + +```ts +export declare const fromHex: (i: string, overrideOptions?: ParseOptions) => VKey +``` + +## toHex + +**Signature** + +```ts +export declare const toHex: (value: Parameters[0]) => Hex +``` diff --git a/docs/content/docs/modules/Value.mdx b/docs/content/docs/modules/Value.mdx index 32c1e5be..ab7f77e7 100644 --- a/docs/content/docs/modules/Value.mdx +++ b/docs/content/docs/modules/Value.mdx @@ -1,6 +1,7 @@ --- + title: Value.ts -nav_order: 186 +nav_order: 191 parent: Modules --- @@ -19,6 +20,7 @@ parent: Modules - [generators](#generators) - [arbitrary](#arbitrary) - [model](#model) + - [Hex (type alias)](#hex-type-alias) - [ValueCDDL (type alias)](#valuecddl-type-alias) - [ordering](#ordering) - [geq](#geq) @@ -33,6 +35,7 @@ parent: Modules - [FromCBORBytes](#fromcborbytes-1) - [FromCBORHex](#fromcborhex-1) - [FromCDDL](#fromcddl) + - [Hex](#hex) - [OnlyCoin (class)](#onlycoin-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) @@ -125,6 +128,16 @@ Added in v2.0.0 # model +## Hex (type alias) + +**Signature** + +```ts +export type Hex = typeof Hex.Type +``` + +Added in v2.4.0 + ## ValueCDDL (type alias) TypeScript type for the raw CDDL representation. @@ -335,6 +348,23 @@ export declare const FromCDDL: Schema.transformOrFail< Added in v2.0.0 +## Hex + +A `value` as CBOR hex. + +The CBOR encoding of a value, not a hash of one: length varies with the number of assets. + +Branded so that CBOR hex of one kind cannot stand in for another once it leaves the typed +domain. Non-empty whole bytes is all the shape there is to check. + +**Signature** + +```ts +export declare const Hex: Schema.brand, "ValueHex"> +``` + +Added in v2.4.0 + ## OnlyCoin (class) Schema for Value representing both ADA and native assets. diff --git a/docs/content/docs/modules/VotingProcedures.mdx b/docs/content/docs/modules/VotingProcedures.mdx index 8a686160..a96116a3 100644 --- a/docs/content/docs/modules/VotingProcedures.mdx +++ b/docs/content/docs/modules/VotingProcedures.mdx @@ -1,6 +1,7 @@ --- + title: VotingProcedures.ts -nav_order: 188 +nav_order: 193 parent: Modules --- @@ -19,6 +20,9 @@ parent: Modules - [encoding](#encoding) - [toCBORBytes](#tocborbytes) - [toCBORHex](#tocborhex) + - [voterToCBORBytes](#votertocborbytes) + - [voterToCBORHex](#votertocborhex) + - [votingProcedureToCBORHex](#votingproceduretocborhex) - [helpers](#helpers) - [multiVote](#multivote) - [singleVote](#singlevote) @@ -32,6 +36,9 @@ parent: Modules - [parsing](#parsing) - [fromCBORBytes](#fromcborbytes) - [fromCBORHex](#fromcborhex) + - [voterFromCBORBytes](#voterfromcborbytes) + - [voterFromCBORHex](#voterfromcborhex) + - [votingProcedureFromCBORHex](#votingprocedurefromcborhex) - [pattern matching](#pattern-matching) - [matchVote](#matchvote) - [matchVoter](#matchvoter) @@ -181,6 +188,42 @@ export declare const toCBORHex: (data: VotingProcedures, options?: CBOR.CodecOpt Added in v2.0.0 +## voterToCBORBytes + +Codec pair for a standalone `Voter`. + +`Voter` and `VotingProcedure` are addressable on their own -- a wallet builds a vote before it +has a `VotingProcedures` map to put it in -- but only their CDDL transforms were exported, so +encoding one meant reaching through `Schema.encodeSync` and the CBOR writer by hand. + +**Signature** + +```ts +export declare const voterToCBORBytes: (input: Voter, options?: CBOR.CodecOptions) => Uint8Array +``` + +Added in v2.0.0 + +## voterToCBORHex + +**Signature** + +```ts +export declare const voterToCBORHex: (input: Voter, options?: CBOR.CodecOptions) => string +``` + +Added in v2.0.0 + +## votingProcedureToCBORHex + +**Signature** + +```ts +export declare const votingProcedureToCBORHex: (input: VotingProcedure, options?: CBOR.CodecOptions) => string +``` + +Added in v2.0.0 + # helpers ## multiVote @@ -306,6 +349,42 @@ export declare const fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => Added in v2.0.0 +## voterFromCBORBytes + +**Signature** + +```ts +export declare const voterFromCBORBytes: ( + bytes: Uint8Array, + options?: CBOR.CodecOptions +) => ConstitutionalCommitteeVoter | DRepVoter | StakePoolVoter +``` + +Added in v2.0.0 + +## voterFromCBORHex + +**Signature** + +```ts +export declare const voterFromCBORHex: ( + hex: string, + options?: CBOR.CodecOptions +) => ConstitutionalCommitteeVoter | DRepVoter | StakePoolVoter +``` + +Added in v2.0.0 + +## votingProcedureFromCBORHex + +**Signature** + +```ts +export declare const votingProcedureFromCBORHex: (hex: string, options?: CBOR.CodecOptions) => VotingProcedure +``` + +Added in v2.0.0 + # pattern matching ## matchVote diff --git a/docs/content/docs/modules/VrfCert.mdx b/docs/content/docs/modules/VrfCert.mdx index 33dc0986..89ac05a5 100644 --- a/docs/content/docs/modules/VrfCert.mdx +++ b/docs/content/docs/modules/VrfCert.mdx @@ -1,6 +1,7 @@ --- + title: VrfCert.ts -nav_order: 189 +nav_order: 194 parent: Modules --- diff --git a/docs/content/docs/modules/VrfKeyHash.mdx b/docs/content/docs/modules/VrfKeyHash.mdx index e55cd5d2..a64e85ff 100644 --- a/docs/content/docs/modules/VrfKeyHash.mdx +++ b/docs/content/docs/modules/VrfKeyHash.mdx @@ -1,6 +1,7 @@ --- + title: VrfKeyHash.ts -nav_order: 190 +nav_order: 195 parent: Modules --- diff --git a/docs/content/docs/modules/VrfVkey.mdx b/docs/content/docs/modules/VrfVkey.mdx index 5876e7dd..f60e4583 100644 --- a/docs/content/docs/modules/VrfVkey.mdx +++ b/docs/content/docs/modules/VrfVkey.mdx @@ -1,6 +1,7 @@ --- + title: VrfVkey.ts -nav_order: 191 +nav_order: 196 parent: Modules --- diff --git a/docs/content/docs/modules/Withdrawals.mdx b/docs/content/docs/modules/Withdrawals.mdx index a0e2cf6f..991446ad 100644 --- a/docs/content/docs/modules/Withdrawals.mdx +++ b/docs/content/docs/modules/Withdrawals.mdx @@ -1,6 +1,7 @@ --- + title: Withdrawals.ts -nav_order: 192 +nav_order: 197 parent: Modules --- diff --git a/docs/content/docs/modules/_meta.json b/docs/content/docs/modules/_meta.json index 0e3ca056..f5d712c6 100644 --- a/docs/content/docs/modules/_meta.json +++ b/docs/content/docs/modules/_meta.json @@ -30,6 +30,7 @@ "Bytes80": "Bytes80", "Bytes96": "Bytes96", "CBOR": "CBOR", + "CBORBuilder": "CBORBuilder", "Certificate": "Certificate", "Codec": "Codec", "Coin": "Coin", @@ -50,6 +51,7 @@ "EnterpriseAddress": "EnterpriseAddress", "EpochNo": "EpochNo", "FeeValidation": "FeeValidation", + "Fees": "Fees", "GovernanceAction": "GovernanceAction", "Hash28": "Hash28", "Header": "Header", @@ -63,6 +65,7 @@ "Label": "Label", "Language": "Language", "Metadata": "Metadata", + "MinAda": "MinAda", "Mint": "Mint", "MultiAsset": "MultiAsset", "MultiHostName": "MultiHostName", @@ -75,6 +78,7 @@ "NonnegativeInterval": "NonnegativeInterval", "Numeric": "Numeric", "OperationalCert": "OperationalCert", + "OriginalBytes": "OriginalBytes", "PaymentAddress": "PaymentAddress", "PlutusV1": "PlutusV1", "PlutusV2": "PlutusV2", @@ -106,7 +110,6 @@ "Slot": "Slot", "SlotConfig": "SlotConfig", "StakeReference": "StakeReference", - "TSchema": "TSchema", "Text": "Text", "Text128": "Text128", "Time": "Time", diff --git a/docs/content/docs/modules/blueprint/Codegen.mdx b/docs/content/docs/modules/blueprint/Codegen.mdx index 93a73335..402df165 100644 --- a/docs/content/docs/modules/blueprint/Codegen.mdx +++ b/docs/content/docs/modules/blueprint/Codegen.mdx @@ -1,4 +1,5 @@ --- + title: blueprint/Codegen.ts nav_order: 17 parent: Modules diff --git a/docs/content/docs/modules/blueprint/CodegenConfig.mdx b/docs/content/docs/modules/blueprint/CodegenConfig.mdx index d83125ea..5a99a24b 100644 --- a/docs/content/docs/modules/blueprint/CodegenConfig.mdx +++ b/docs/content/docs/modules/blueprint/CodegenConfig.mdx @@ -1,4 +1,5 @@ --- + title: blueprint/CodegenConfig.ts nav_order: 18 parent: Modules diff --git a/docs/content/docs/modules/blueprint/Types.mdx b/docs/content/docs/modules/blueprint/Types.mdx index 68258c57..a7ca7f5b 100644 --- a/docs/content/docs/modules/blueprint/Types.mdx +++ b/docs/content/docs/modules/blueprint/Types.mdx @@ -1,4 +1,5 @@ --- + title: blueprint/Types.ts nav_order: 19 parent: Modules diff --git a/docs/content/docs/modules/cose/Header.mdx b/docs/content/docs/modules/cose/Header.mdx index 80803712..4c88360f 100644 --- a/docs/content/docs/modules/cose/Header.mdx +++ b/docs/content/docs/modules/cose/Header.mdx @@ -1,6 +1,7 @@ --- + title: cose/Header.ts -nav_order: 41 +nav_order: 42 parent: Modules --- @@ -23,12 +24,22 @@ Added in v2.0.0 - [headerMapToCBORBytes](#headermaptocborbytes) - [headerMapToCBORHex](#headermaptocborhex) - [Model](#model) - - [HeaderMap (class)](#headermap-class) + - [Headers (class)](#headers-class) - [toJSON (method)](#tojson-method) - [toString (method)](#tostring-method) - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method) - [[Equal.symbol] (method)](#equalsymbol-method) - [[Hash.symbol] (method)](#hashsymbol-method) +- [Schemas](#schemas) + - [HeaderMapFromCBORBytes](#headermapfromcborbytes-1) + - [HeaderMapFromCBORHex](#headermapfromcborhex-1) +- [utils](#utils) + - [HeaderMap (class)](#headermap-class) + - [toJSON (method)](#tojson-method-1) + - [toString (method)](#tostring-method-1) + - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method-1) + - [[Equal.symbol] (method)](#equalsymbol-method-1) + - [[Hash.symbol] (method)](#hashsymbol-method-1) - [setAlgorithmId (method)](#setalgorithmid-method) - [algorithmId (method)](#algorithmid-method) - [setCriticality (method)](#setcriticality-method) @@ -44,15 +55,6 @@ Added in v2.0.0 - [setHeader (method)](#setheader-method) - [header (method)](#header-method) - [keys (method)](#keys-method) - - [Headers (class)](#headers-class) - - [toJSON (method)](#tojson-method-1) - - [toString (method)](#tostring-method-1) - - [[Inspectable.NodeInspectSymbol] (method)](#inspectablenodeinspectsymbol-method-1) - - [[Equal.symbol] (method)](#equalsymbol-method-1) - - [[Hash.symbol] (method)](#hashsymbol-method-1) -- [Schemas](#schemas) - - [HeaderMapFromCBORBytes](#headermapfromcborbytes-1) - - [HeaderMapFromCBORHex](#headermapfromcborhex-1) --- @@ -134,18 +136,117 @@ Added in v2.0.0 # Model -## HeaderMap (class) +## Headers (class) -Map of COSE header labels to values (RFC 8152). +COSE protected and unprotected headers (RFC 8152). **Signature** ```ts -export declare class HeaderMap +export declare class Headers +``` + +Added in v2.0.0 + +### toJSON (method) + +**Signature** + +```ts +toJSON() +``` + +### toString (method) + +**Signature** + +```ts +toString(): string +``` + +### [Inspectable.NodeInspectSymbol] (method) + +**Signature** + +```ts +[Inspectable.NodeInspectSymbol](): unknown +``` + +### [Equal.symbol] (method) + +**Signature** + +```ts +[Equal.symbol](that: unknown): boolean +``` + +### [Hash.symbol] (method) + +**Signature** + +```ts +[Hash.symbol](): number +``` + +# Schemas + +## HeaderMapFromCBORBytes + +CBOR bytes transformation schema for HeaderMap. + +**Signature** + +```ts +export declare const HeaderMapFromCBORBytes: ( + options?: CBOR.CodecOptions +) => Schema.transformOrFail< + Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.declare, + never + >, + Schema.SchemaClass, + never +> +``` + +Added in v2.0.0 + +## HeaderMapFromCBORHex + +CBOR hex transformation schema for HeaderMap. + +**Signature** + +```ts +export declare const HeaderMapFromCBORHex: ( + options?: CBOR.CodecOptions +) => Schema.transform< + Schema.Schema, + Schema.transformOrFail< + Schema.transformOrFail< + typeof Schema.Uint8ArrayFromSelf, + Schema.declare, + never + >, + Schema.SchemaClass, + never + > +> ``` Added in v2.0.0 +# utils + +## HeaderMap (class) + +**Signature** + +```ts +export declare class HeaderMap +``` + ### toJSON (method) **Signature** @@ -346,6 +447,11 @@ Added in v2.0.0 Get custom header. +⚠️ Structural, not by object identity. `this.headers.get(label)` answered `undefined` for a +label that IS present, because the caller's `labelFromInt(n)` is a different object from the +one in the map — which is why every reader in this package hand-walked `entries()` rather +than calling this. + **Signature** ```ts @@ -365,104 +471,3 @@ keys(): ReadonlyArray