what is contract meta used in dapp-offer-up?

[dckc]

In office hours today, someone asked about some code from the contract in dapp-offer-up:

export const meta = {
  customTermsShape: M.splitRecord(
    { tradePrice: AmountShape },
    { maxItems: M.bigint() },
  ),
};
// compatibility with an earlier contract metadata API
export const customTermsShape = meta.customTermsShape;

https://github.com/Agoric/dapp-offer-up/blob/6a14bcfc62c6008c379524f300e9176ec7dc1534/contract/src/offer-up.contract.js#L56-L63

https://github.com/Agoric/dapp-agoric-basics/blob/main/contract/src/postal-service.contract.js#L8

[turadg]

#8045

[dckc]

I'm struggling to find much explanation of customTermsShape and privateArgsShape in #8045.

[kbennett2000]

A first stab at defining meta in Agoric:

In an Agoric smart contract, meta is an object that contains metadata about the contract's custom terms. meta is a static object that describes the shape of the custom terms expected by the contract, helping external tools and clients to interact with the contract correctly.

An example of meta in a smart contract:

export const meta = {
  customTermsShape: M.splitRecord(
    { tradePrice: AmountShape },
    { maxItems: M.bigint() },
  ),
};

The meta object has a single property called customTermsShape, which defines the shape (structure) of the custom terms expected by the contract. Custom terms are additional parameters that can be passed to the contract when it is instantiated, beyond the standard issuers and brands terms.

In the example above, the custom terms are defined using the M.splitRecord function from the @endo/patterns library. It specifies that the custom terms should be an object with two properties:

• tradePrice: It should be an Amount.
• maxItems: It should be a bigint. This property is optional, as indicated by the empty object as the second argument to M.splitRecord.

The meta object is not directly used within the contract code itself. Instead, it provides information about the contract's expected terms to external tools and interfaces that interact with the contract. For example, it can be used by client applications or UI components to know what parameters they need to provide when creating an instance of the contract.

The line export const customTermsShape = meta.customTermsShape; is added for backward compatibility with an earlier version of the contract metadata API.

[dckc]

In an Agoric smart contract, meta is an object that contains metadata about the contract's custom terms.

It's also about privateArgs, upgradability, and perhaps other things in the future.

agoric-sdk/packages/zoe/src/contractFacet/types-ambient.d.ts

Lines 219 to 222 in 247cc9b

	type ContractMeta = {
	customTermsShape?: CopyRecord<any> | undefined;
	privateArgsShape?: CopyRecord<any> | undefined;
	upgradability?: 'none' | 'canBeUpgraded' | 'canUpgrade' | undefined;

Custom terms are additional parameters that can be passed to the contract when it is instantiated.

right... we have docs on that under starting a contract etc.

customTermsShape is a pattern applied during zcf.getTerms(). getTerms fails if the terms don't match.

And privateArgsShape is a pattern applied when zoe is starting the contract. E(zoe).startInstance(installation, issuers, terms, privateArgs) fails if the code of installation exports privateArgsShape and the given privateArgs doesn't match.

[dckc]

Also, note that putting customTermsShape and privateArgsShape in a meta export is an API that's newer than what's on chain.

The API on chain is that you have to export customTermsShape and privateArgsShape themselves.

Zoe/zcf have not yet been upgraded since mainnet1B-rc3 Jun 2023.

So the relevant code is:

agoric-sdk/packages/zoe/src/contractFacet/zcfZygote.js

Lines 225 to 231 in ba3b776

	const {
	start,
	buildRootObject,
	privateArgsShape,
	customTermsShape,
	prepare,
	} = await evaluateContract();

...

agoric-sdk/packages/zoe/src/contractFacet/zcfZygote.js

Lines 376 to 378 in ba3b776

	if (privateArgsShape) {
	mustMatch(privateArgs, privateArgsShape, 'privateArgs');
	}

...

agoric-sdk/packages/zoe/src/contractFacet/zcfZygote.js

Lines 299 to 309 in ba3b776

	getTerms: () => {
	const terms = getInstanceRecHolder().getTerms();
	// If the contract provided customTermsShape, validate the customTerms.
	if (customTermsShape) {
	const { brands: _b, issuers: _i, ...customTerms } = terms;
	mustMatch(harden(customTerms), customTermsShape, 'customTerms');
	}
	return terms;
	},