@pizzaton/ton 0.0.0-stage → 0.1.1

package/CONTRACTS.md

@@ -0,0 +1,239 @@
+# @pizzaton/ton contract integrations
+
+Protocol-specific TON contract integrations now live inside `@pizzaton/ton`.
+This guide covers the native wrapper, source catalog, and module-client
+subpaths; the separate `@pizzaton/contracts` workspace package has been
+retired.
+
+The package owns contract-specific descriptors, versioned adapters, message
+builders, state decoders, and integration fixtures. It does not duplicate TON
+primitives, standard payloads, wallet implementations, or provider behavior.
+
+## Scope
+
+The package currently provides:
+
+- immutable source and audit metadata for official and candidate contracts;
+- a catalog that records exact source commits and security warnings;
+- a typed `ContractModuleClient` for modules implementing `TonContractModule` from `@pizzaton/ton/contracts`;
+- source-pinned native wrappers for Multix DAO and the JVault vesting, airdrop, decentralized launchpad, fixed staking, floating staking, and staking-v2 contract families;
+- source-pinned native wrappers for the supplied Ton-Raffles NFT launchpad, modern and jetton-priced sales, auction, swap, scalable airdrop, off-chain proofs, shopping cart, NFT staking/lending, and PizzaTon jetton-locker contracts;
+- source-pinned native wrappers for Memeland BCL factory/minters/wallets and FeeCollector, plus the TONresistor bonding-curve master, curve, and custom Jetton minter/wallet contracts;
+- Hipo treasury, hGRAM parent, and wallet wrappers with current deposit/unstake message layouts, dynamic fee and wallet getters, and append-only treasury state decoding;
+- the Multix per-sale storage contract, including its buy, TON claim, token claim, veto, and unlock-option encodings;
+- exact message builders, initialization serializers, read-method accessors, and send methods that route through `TonContractClient` from `@pizzaton/ton`;
+- shared registry and client exports from `@pizzaton/ton`.
+
+The catalog is not a deployment allowlist. Entries marked `research-only`, `experimental`, or `audit-evidence` must not be used with production funds. A production module will only be added after its exact source, compiler output, code/data hashes, deployment configuration, and audit scope are verified.
+
+## Usage
+
+```ts
+import {
+	CONTRACT_CATALOG,
+	ContractModuleClient,
+	getContractDescriptor,
+} from "@pizzaton/ton/contracts";
+
+const descriptor = getContractDescriptor("tonresistor/bonding-curve", 1);
+if (!descriptor || descriptor.readiness !== "official-reference") {
+	throw new Error("This integration is not an official reference adapter");
+}
+
+console.log(CONTRACT_CATALOG["official/jetton"].source.commitUrl);
+```
+
+## Native wrappers
+
+Wrappers are exported from `@pizzaton/ton/contracts/wrappers` and versioned
+by source revision in the catalog. They accept `ContractProvider` and `Sender`
+only at the operation boundary, so the package does not own a wallet session
+or network connection.
+
+```ts
+import { Address } from "@ton/core";
+import {
+	JVaultStakingPool,
+	JVaultStakeWallet,
+	MultixDaoContract,
+	MultixStorageContract,
+} from "@pizzaton/ton/contracts/wrappers";
+
+const pool = JVaultStakingPool.createFromAddress(Address.parse(poolAddress));
+const stakeWallet = JVaultStakeWallet.createFromAddress(
+	Address.parse(stakeWalletAddress),
+);
+
+const poolState = await pool.getStorageData(provider);
+await stakeWallet.sendUnstakeRequest(
+	provider,
+	sender,
+	100n, // jetton base units
+	350_000_000n, // nanoTON attached value
+);
+
+const dao = MultixDaoContract.createFromAddress(Address.parse(daoAddress));
+const daoState = await dao.getState(provider);
+const storage = MultixStorageContract.createFromAddress(Address.parse(storageAddress));
+await storage.sendClaimRequestFull(provider, sender, 100_000_000n, contractTonBalance);
+```
+
+Memeland and TONresistor use protocol-specific message formats. Their wrappers
+keep the source-defined field order and use explicit value budgets so callers
+can account for deployment/trade gas instead of hiding a network-dependent
+amount:
+
+```ts
+import {
+	MEMELAND_GAS,
+	MemelandBclFactory,
+	TonResistorBondingCurve,
+} from "@pizzaton/ton/contracts/wrappers";
+
+const factory = MemelandBclFactory.createFromAddress(factoryAddress);
+await factory.sendDeployCoin(provider, sender, deploymentValue, {
+	author: authorAddress,
+	name: "Pizza",
+		symbol: "PIZZA",
+}, {
+	deploymentFee: 500_000_000n,
+	deploymentGas: MEMELAND_GAS.coinDeployment,
+});
+
+const curve = TonResistorBondingCurve.createFromAddress(curveAddress);
+await curve.sendBuy(provider, sender, tonValue, minimumJettonsOut);
+const curveState = await curve.getCurveData(provider);
+```
+
+### Hipo liquid staking
+
+The Hipo adapter follows the upstream treasury deposit, wallet unstake, and
+getter schemas pinned in the [integration guide](https://github.com/HipoFinance/contract/blob/f7ca3db515b72b0f8e3fe63ffc64ca749e9765e0/docs/integration.md).
+It includes only the published mainnet address helpers; resolve testnet
+addresses from an authoritative deployment source before using another
+network. Fees are dynamic, so read them before each operation and add an
+application-owned gas margin:
+
+```ts
+import { HipoParent, HipoTreasury, HipoWallet } from "@pizzaton/ton/contracts/hipo";
+
+const treasury = HipoTreasury.createMainnet();
+const depositFees = await treasury.getTreasuryFees(provider);
+await treasury.sendDepositCoins(
+	provider,
+	sender,
+	{ coins: 0n }, // use attached value after Hipo's current fee
+	depositFees.depositCoinsFee + depositGasMargin,
+);
+
+const parent = HipoParent.createMainnet();
+const walletAddress = await parent.getWalletAddress(provider, ownerAddress);
+const wallet = HipoWallet.createFromAddress(walletAddress);
+const walletFees = await wallet.getWalletFees(provider);
+await wallet.sendUnstakeTokens(
+	provider,
+	sender,
+	{ tokens: hgramAmount, returnExcess: ownerAddress },
+	walletFees.unstakeTokensFee + unstakeGasMargin,
+);
+```
+
+Hipo's `get_treasury_state` tuple is append-only. The wrapper decodes the
+stable 24-field prefix, the seven fields known from the pinned revision, and
+reports any future tail values through `unknownAppendValueCount`. Protocol
+dictionaries and optional proposed-governor data remain raw cells so callers
+can decode them against the exact upstream version they use. The catalog marks
+Hipo as an official source reference with admin-controlled upgrades; this does
+not verify any deployed code hash or constitute production approval.
+
+TONresistor’s custom Jetton messages expose explicit inline/reference forward
+payload variants through `TonResistorForwardPayload`; use the reference form
+for a payload that does not fit safely in the root cell.
+
+The complete native family exports are `MemelandBclFactory`,
+`MemelandBclJettonMinter`, `MemelandBclJettonWallet`, `MemelandFeeCollector`,
+`TonResistorBondingCurveMaster`, `TonResistorBondingCurve`,
+`TonResistorJettonMinter`, and `TonResistorJettonWallet`. These are adapters
+for the pinned upstream revisions, not copies of their FunC/Tolk source or a
+replacement for independently verifying the deployed code hash.
+
+`Cell` parameters on `MultixDaoContract` and batch airdrop methods represent
+the nested records or dictionaries defined by the upstream Tact/FunC source.
+This keeps the generated ABI authoritative instead of maintaining a second
+incompatible schema in this package. The outer message headers and field order
+are encoded by the wrappers and covered by tests.
+
+For JVault, use `JVaultStakingPool`, `JVaultStakeWallet`, `JVaultPoolFactory`,
+`JVaultReferrerWallet`, `JVaultInviteeWallet`, `JVaultVesting`,
+`JVaultVestingFactory`, `JVaultAirdropMain`, `JVaultAirdropUser`, the fixed
+and floating staking wrappers, `JVaultIcoSale`, `JVaultRefWallet`,
+`JVaultLaunchpadSftItem`, and `JVaultSaleAdmin`. Use
+`uint256CoinsDictionary`, `buildJVaultVestingCodeDictionary`, and
+`buildJVaultReferenceDictionary` for the protocol-specific dictionary shapes.
+The auxiliary `JVaultFixedPoolsAdmin`, `JVaultFloatingPoolsAdmin`,
+`JVaultFloatingSharecoms`, and `JVaultSbtSingle` wrappers cover the remaining
+deployed contracts in the supplied JVault repositories.
+The package does not depend on `@jvault/sdk` or any protocol SDK; all builders
+are native and use only `@pizzaton/ton` plus official `@ton/core` primitives.
+
+Ton-Raffles wrappers are exported from the root as
+`TonRafflesNftLaunchpadSale`, `TonRafflesModernNftSale`,
+`TonRafflesJettonPricedNftSale`, `TonRafflesNftAuctionV2`,
+`TonRafflesNftSwapV2`, `TonRafflesScalableAirdrop`,
+`TonRafflesAirdropHelper`, `TonRafflesOffchainProofTask`,
+`TonRafflesShoppingCart`, `TonRafflesNftStakingMaster`,
+`TonRafflesNftStakingHelper`, `TonRafflesNftLendingMaster`, and the
+`PizzaTonJettonLocker*` wrappers. The scalable airdrop config requires an
+explicit nonce so derived addresses remain deterministic; do not copy the
+upstream sample's random nonce behavior into deployment tooling.
+
+An adapter should implement the shared module contract and use official `@ton/core` types. The client accepts the same `ContractProvider` and `Sender` abstractions used by `@pizzaton/ton`:
+
+```ts
+import type { Address, Contract, ContractProvider, Sender } from "@ton/core";
+import type { ContractModule } from "@pizzaton/ton/contracts";
+import { ContractModuleClient } from "@pizzaton/ton/contracts";
+
+type Config = { readonly owner: Address };
+type State = { readonly owner: Address };
+type Action = { readonly queryId: bigint };
+
+declare const module: ContractModule<Config, State, Action>;
+declare const contract: Contract;
+declare const provider: ContractProvider;
+declare const sender: Sender;
+
+const client = new ContractModuleClient(module, { contract, provider, sender });
+const body = client.buildMessage({ queryId: 1n });
+await client.send({ queryId: 1n }, { value: 100_000_000n });
+```
+
+The `module` must be a real protocol adapter created with `createContractModule`, and its descriptor must match the pinned source. No placeholder adapter is registered in the catalog.
+
+## Package boundaries
+
+- Use `@pizzaton/ton/core` for addresses, amounts, metadata, networks, and errors.
+- Use `@pizzaton/ton/contracts` for the generic module contract and provider-backed client.
+- Use `@pizzaton/ton/contracts/wrappers` for the native wrapper catalog, or `@pizzaton/ton/contracts/hipo` for Hipo's focused wrapper surface.
+- Use `@pizzaton/ton/transactions` and `@pizzaton/ton/connect` for wallet transaction intents and TON Connect delivery.
+- Keep product-specific launchpad orchestration outside this package. This
+  package owns reusable protocol wrappers; PizzaTon business rules, pricing,
+  and revenue routing belong in application/domain packages.
+
+## Verification requirements for a production adapter
+
+1. Pin the source commit and compiler/toolchain.
+2. Record deployed code and data hashes.
+3. Verify all internal, external, bounced, deployment, upgrade, refund, and timeout paths in an emulator.
+4. Add trace-level tests for insufficient gas, action failure, interleaving, replay, and malformed cells.
+5. Verify standard Jetton/NFT sender authenticity and workchain assumptions.
+6. Match the independent audit to the exact source and compiled artifact.
+7. Register a production adapter only after review approval.
+
+## Development
+
+```sh
+bun run --filter @pizzaton/ton check-types
+bun run --filter @pizzaton/ton lint
+bun run --filter @pizzaton/ton test
+```