generate metadata on build

[vicentevieytes]

Summary

Automate generation of build/contracts-pkg.json.

• Added generateContractsPkg.ts script: Reads CONTRACT_VERSION from each Tolk source file directly, builds contracts-pkg.json with per-contract versions and the package version from package.json
• Hooked it into yarn build so every local and Nix build produces the file automatically
• Bumped package.json version to 1.6.0 (was a placeholder 0.0.1); this field is now the authoritative version for the contracts package release as well.
• Updated the publish workflow: pushed tags that match contracts/* trigger a release. Another workflow creates and pushes dirty release tag on every merge to main.
• Unified contracts release naming under contracts/<version> and dropped `ton-contracts-build-..

---

Release process going forward

1. Contract changes: bump CONTRACT_VERSION in the .tolk source (e.g. "1.6.1"). The build picks that up automatically into contracts-pkg.json. CI publishes an artifact tagged as `1.6.0+.

2. Ready to ship: create a PR bumping the version on package.json to 1.6.1. Then tag a main commit as contracts/1.6.1 and push it.

3. Workflow detects the tag push, creates GitHub release tagged contracts/1.6.1 with a clean contracts-pkg.json (no SHA suffix). That tag is what Go consumers reference via ContractsPackageLatestSupported.

---

TODO Integrate changesets
Wire changesets/changesets to be used to trigger and orchestrate this workflow release. Right now it's only triggered due to tags being pushed.

[Copilot]

Pull request overview

Automates generation and publication of contracts-pkg.json metadata for compiled contract artifacts, and updates the release workflow to use contracts/<version> tags driven by contracts/package.json.

Changes:

• Added contracts/scripts/generateContractsPkg.ts to generate build/contracts-pkg.json by extracting CONTRACT_VERSION from Tolk sources.
• Hooked metadata generation into yarn build and bumped contracts/package.json version to 1.6.0.
• Updated the GitHub Actions publish workflow to detect version bumps as the release signal and to embed +<sha> build metadata for non-release builds.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
contracts/scripts/generateContractsPkg.ts	New script to generate contracts-pkg.json from Tolk sources + package version.
contracts/package.json	Bumps version and runs the metadata generator as part of yarn build.
.github/workflows/contracts-publish-compiled-artifacts.yml	Adds release detection logic, stages/patches contracts-pkg.json version, and changes release tag naming to contracts/<version>.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[krebernisak]

We can't have this requirement globally as we might vendor third party contracts, like Jetton contracts, which don't follow this model and we don't want to update their source to add it.

We also want to be able to package those types contracts to be able to interact with them in a standard way (deploy, use) - the pkg should also be host a contracts-pkg.json metadata file.

[vicentevieytes]

We can't have this requirement globally as we might vendor third party contracts, like Jetton contracts, which don't follow this model and we don't want to update their source to add it.

Yeah I see that being an issue in the not so distant future, but right now we are only packaging and using our own contracts all of which follow this specification.

There are type() and version() static getters for the wrappers of each of the contracts and those are asserted against the actual contract on the CI tests. We could use those instead of getting the type and version from the contract code itself, but that means that the metadata won't be immediately updated locally when the version is bumped in the code and it will only impact when you update it in the wrapper.

I think this implementation that parses the version from the contract is good enough for now so i'd defer this for pragmatism's sake. I'll scope a ticket to follow up.

[krebernisak]

imo we should simplify this reasoning about what is a release

1. A workflow should trigger on a tag, and build/publish artifacts - this is an official release train. We merge a release branch and a tag is created which triggers package builds and GHA Release creation.
2. Additionally, we can have ad-hoc dirty releases with:
   • Whenever contract changes are merged to main
   • Whenever a workflow is triggered manually - maybe useful to release from a long running branch

Why would "$CURRENT_VERSION" != "$PREV_VERSION" signal a release? Where do you even find the PREV_VERSION?

There is only the current version at the current commit and this version is written in contracts/package.json, and then it's only about the trigger:

• tag: version is the current version
• merge to main: version is the current version + (dirty)
• manual trigger: version is the current version + (dirty)

---

To simplify and compose workflows, maybe we could have one to create the <version>+<sha> dirty tags, and a second one which would be triggered on tag push and create a release (build + publish).

[vicentevieytes]

Where do you even find the PREV_VERSION?

It's the version value on package.json before the change is introduced, but I agree it's not too clean of an approach

To simplify and compose workflows, maybe we could have one to create the + dirty tags, and a second one which would be triggered on tag push and create a release (build + publish).

Yeah I think that makes sense

[vicentevieytes]

@krebernisak done separating and simplifying the workflow:

• One workflow triggers a release every time a contracts/* tag is pushed
• The other workflow creates a dirty build contracts/version+sha tag and pushes it, triggering the first workflow

[krebernisak]

Think this might not be necessary and we can keep the version as is, not append the to it - rather, we can just have the contractsPkg.sha added as a separate field in the metadata.

Is this a clean or dirty package release is determined by the tag used to load it, not contractsPkg.version

You can imagine same commit being tagged twice, once via the standard release train (clean release) and once manually as a dirty commit - two different tags should point to the same identical packages, not different packages hosting different metadata.

[vicentevieytes]

Ok then I think we can just drop the build sha from the metadata json and use it only in the tag. This will simplify and it will leave contracts built locally or with nix with the same metadata file as the package built on CI.

The tag itself can identify when the release is a package in-between versions and a full release, that doesn't need to be inside the metadata.