contract.ts 39 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120
  1. import { Interface, Typed } from "../abi/index.js";
  2. import { isAddressable, resolveAddress } from "../address/index.js";
  3. // import from provider.ts instead of index.ts to prevent circular dep
  4. // from EtherscanProvider
  5. import { copyRequest, Log, TransactionResponse } from "../providers/provider.js";
  6. import {
  7. defineProperties, getBigInt, isCallException, isHexString, resolveProperties,
  8. isError, makeError, assert, assertArgument
  9. } from "../utils/index.js";
  10. import {
  11. ContractEventPayload, ContractUnknownEventPayload,
  12. ContractTransactionResponse,
  13. EventLog, UndecodedEventLog
  14. } from "./wrappers.js";
  15. import type { EventFragment, FunctionFragment, InterfaceAbi, ParamType, Result } from "../abi/index.js";
  16. import type { Addressable, NameResolver } from "../address/index.js";
  17. import type { EventEmitterable, Listener } from "../utils/index.js";
  18. import type {
  19. BlockTag, ContractRunner, Provider, TransactionRequest, TopicFilter
  20. } from "../providers/index.js";
  21. import type {
  22. BaseContractMethod,
  23. ContractEventName,
  24. ContractInterface,
  25. ContractMethodArgs,
  26. ContractMethod,
  27. ContractEventArgs,
  28. ContractEvent,
  29. ContractTransaction,
  30. DeferredTopicFilter,
  31. WrappedFallback
  32. } from "./types.js";
  33. const BN_0 = BigInt(0);
  34. interface ContractRunnerCaller extends ContractRunner {
  35. call: (tx: TransactionRequest) => Promise<string>;
  36. }
  37. interface ContractRunnerEstimater extends ContractRunner {
  38. estimateGas: (tx: TransactionRequest) => Promise<bigint>;
  39. }
  40. interface ContractRunnerSender extends ContractRunner {
  41. sendTransaction: (tx: TransactionRequest) => Promise<TransactionResponse>;
  42. }
  43. interface ContractRunnerResolver extends ContractRunner {
  44. resolveName: (name: string | Addressable) => Promise<null | string>;
  45. }
  46. function canCall(value: any): value is ContractRunnerCaller {
  47. return (value && typeof(value.call) === "function");
  48. }
  49. function canEstimate(value: any): value is ContractRunnerEstimater {
  50. return (value && typeof(value.estimateGas) === "function");
  51. }
  52. function canResolve(value: any): value is ContractRunnerResolver {
  53. return (value && typeof(value.resolveName) === "function");
  54. }
  55. function canSend(value: any): value is ContractRunnerSender {
  56. return (value && typeof(value.sendTransaction) === "function");
  57. }
  58. function getResolver(value: any): undefined | NameResolver {
  59. if (value != null) {
  60. if (canResolve(value)) { return value; }
  61. if (value.provider) { return value.provider; }
  62. }
  63. return undefined;
  64. }
  65. class PreparedTopicFilter implements DeferredTopicFilter {
  66. #filter: Promise<TopicFilter>;
  67. readonly fragment!: EventFragment;
  68. constructor(contract: BaseContract, fragment: EventFragment, args: Array<any>) {
  69. defineProperties<PreparedTopicFilter>(this, { fragment });
  70. if (fragment.inputs.length < args.length) {
  71. throw new Error("too many arguments");
  72. }
  73. // Recursively descend into args and resolve any addresses
  74. const runner = getRunner(contract.runner, "resolveName");
  75. const resolver = canResolve(runner) ? runner: null;
  76. this.#filter = (async function() {
  77. const resolvedArgs = await Promise.all(fragment.inputs.map((param, index) => {
  78. const arg = args[index];
  79. if (arg == null) { return null; }
  80. return param.walkAsync(args[index], (type, value) => {
  81. if (type === "address") {
  82. if (Array.isArray(value)) {
  83. return Promise.all(value.map((v) => resolveAddress(v, resolver)));
  84. }
  85. return resolveAddress(value, resolver);
  86. }
  87. return value;
  88. });
  89. }));
  90. return contract.interface.encodeFilterTopics(fragment, resolvedArgs);
  91. })();
  92. }
  93. getTopicFilter(): Promise<TopicFilter> {
  94. return this.#filter;
  95. }
  96. }
  97. // A = Arguments passed in as a tuple
  98. // R = The result type of the call (i.e. if only one return type,
  99. // the qualified type, otherwise Result)
  100. // D = The type the default call will return (i.e. R for view/pure,
  101. // TransactionResponse otherwise)
  102. //export interface ContractMethod<A extends Array<any> = Array<any>, R = any, D extends R | ContractTransactionResponse = ContractTransactionResponse> {
  103. function getRunner<T extends ContractRunner>(value: any, feature: keyof ContractRunner): null | T {
  104. if (value == null) { return null; }
  105. if (typeof(value[feature]) === "function") { return value; }
  106. if (value.provider && typeof(value.provider[feature]) === "function") {
  107. return value.provider;
  108. }
  109. return null;
  110. }
  111. function getProvider(value: null | ContractRunner): null | Provider {
  112. if (value == null) { return null; }
  113. return value.provider || null;
  114. }
  115. /**
  116. * @_ignore:
  117. */
  118. export async function copyOverrides<O extends string = "data" | "to">(arg: any, allowed?: Array<string>): Promise<Omit<ContractTransaction, O>> {
  119. // Make sure the overrides passed in are a valid overrides object
  120. const _overrides = Typed.dereference(arg, "overrides");
  121. assertArgument(typeof(_overrides) === "object", "invalid overrides parameter", "overrides", arg);
  122. // Create a shallow copy (we'll deep-ify anything needed during normalizing)
  123. const overrides = copyRequest(_overrides);
  124. assertArgument(overrides.to == null || (allowed || [ ]).indexOf("to") >= 0,
  125. "cannot override to", "overrides.to", overrides.to);
  126. assertArgument(overrides.data == null || (allowed || [ ]).indexOf("data") >= 0,
  127. "cannot override data", "overrides.data", overrides.data);
  128. // Resolve any from
  129. if (overrides.from) { overrides.from = overrides.from; }
  130. return <Omit<ContractTransaction, O>>overrides;
  131. }
  132. /**
  133. * @_ignore:
  134. */
  135. export async function resolveArgs(_runner: null | ContractRunner, inputs: ReadonlyArray<ParamType>, args: Array<any>): Promise<Array<any>> {
  136. // Recursively descend into args and resolve any addresses
  137. const runner = getRunner(_runner, "resolveName");
  138. const resolver = canResolve(runner) ? runner: null;
  139. return await Promise.all(inputs.map((param, index) => {
  140. return param.walkAsync(args[index], (type, value) => {
  141. value = Typed.dereference(value, type);
  142. if (type === "address") { return resolveAddress(value, resolver); }
  143. return value;
  144. });
  145. }));
  146. }
  147. function buildWrappedFallback(contract: BaseContract): WrappedFallback {
  148. const populateTransaction = async function(overrides?: Omit<TransactionRequest, "to">): Promise<ContractTransaction> {
  149. // If an overrides was passed in, copy it and normalize the values
  150. const tx: ContractTransaction = <any>(await copyOverrides<"data">(overrides, [ "data" ]));
  151. tx.to = await contract.getAddress();
  152. if (tx.from) {
  153. tx.from = await resolveAddress(tx.from, getResolver(contract.runner));
  154. }
  155. const iface = contract.interface;
  156. const noValue = (getBigInt((tx.value || BN_0), "overrides.value") === BN_0);
  157. const noData = ((tx.data || "0x") === "0x");
  158. if (iface.fallback && !iface.fallback.payable && iface.receive && !noData && !noValue) {
  159. assertArgument(false, "cannot send data to receive or send value to non-payable fallback", "overrides", overrides);
  160. }
  161. assertArgument(iface.fallback || noData,
  162. "cannot send data to receive-only contract", "overrides.data", tx.data);
  163. // Only allow payable contracts to set non-zero value
  164. const payable = iface.receive || (iface.fallback && iface.fallback.payable);
  165. assertArgument(payable || noValue,
  166. "cannot send value to non-payable fallback", "overrides.value", tx.value);
  167. // Only allow fallback contracts to set non-empty data
  168. assertArgument(iface.fallback || noData,
  169. "cannot send data to receive-only contract", "overrides.data", tx.data);
  170. return tx;
  171. }
  172. const staticCall = async function(overrides?: Omit<TransactionRequest, "to">): Promise<string> {
  173. const runner = getRunner(contract.runner, "call");
  174. assert(canCall(runner), "contract runner does not support calling",
  175. "UNSUPPORTED_OPERATION", { operation: "call" });
  176. const tx = await populateTransaction(overrides);
  177. try {
  178. return await runner.call(tx);
  179. } catch (error: any) {
  180. if (isCallException(error) && error.data) {
  181. throw contract.interface.makeError(error.data, tx);
  182. }
  183. throw error;
  184. }
  185. }
  186. const send = async function(overrides?: Omit<TransactionRequest, "to">): Promise<ContractTransactionResponse> {
  187. const runner = contract.runner;
  188. assert(canSend(runner), "contract runner does not support sending transactions",
  189. "UNSUPPORTED_OPERATION", { operation: "sendTransaction" });
  190. const tx = await runner.sendTransaction(await populateTransaction(overrides));
  191. const provider = getProvider(contract.runner);
  192. // @TODO: the provider can be null; make a custom dummy provider that will throw a
  193. // meaningful error
  194. return new ContractTransactionResponse(contract.interface, <Provider>provider, tx);
  195. }
  196. const estimateGas = async function(overrides?: Omit<TransactionRequest, "to">): Promise<bigint> {
  197. const runner = getRunner(contract.runner, "estimateGas");
  198. assert(canEstimate(runner), "contract runner does not support gas estimation",
  199. "UNSUPPORTED_OPERATION", { operation: "estimateGas" });
  200. return await runner.estimateGas(await populateTransaction(overrides));
  201. }
  202. const method = async (overrides?: Omit<TransactionRequest, "to">) => {
  203. return await send(overrides);
  204. };
  205. defineProperties<any>(method, {
  206. _contract: contract,
  207. estimateGas,
  208. populateTransaction,
  209. send, staticCall
  210. });
  211. return <WrappedFallback>method;
  212. }
  213. function buildWrappedMethod<A extends Array<any> = Array<any>, R = any, D extends R | ContractTransactionResponse = ContractTransactionResponse>(contract: BaseContract, key: string): BaseContractMethod<A, R, D> {
  214. const getFragment = function(...args: ContractMethodArgs<A>): FunctionFragment {
  215. const fragment = contract.interface.getFunction(key, args);
  216. assert(fragment, "no matching fragment", "UNSUPPORTED_OPERATION", {
  217. operation: "fragment",
  218. info: { key, args }
  219. });
  220. return fragment;
  221. }
  222. const populateTransaction = async function(...args: ContractMethodArgs<A>): Promise<ContractTransaction> {
  223. const fragment = getFragment(...args);
  224. // If an overrides was passed in, copy it and normalize the values
  225. let overrides: Omit<ContractTransaction, "data" | "to"> = { };
  226. if (fragment.inputs.length + 1 === args.length) {
  227. overrides = await copyOverrides(args.pop());
  228. if (overrides.from) {
  229. overrides.from = await resolveAddress(overrides.from, getResolver(contract.runner));
  230. }
  231. }
  232. if (fragment.inputs.length !== args.length) {
  233. throw new Error("internal error: fragment inputs doesn't match arguments; should not happen");
  234. }
  235. const resolvedArgs = await resolveArgs(contract.runner, fragment.inputs, args);
  236. return Object.assign({ }, overrides, await resolveProperties({
  237. to: contract.getAddress(),
  238. data: contract.interface.encodeFunctionData(fragment, resolvedArgs)
  239. }));
  240. }
  241. const staticCall = async function(...args: ContractMethodArgs<A>): Promise<R> {
  242. const result = await staticCallResult(...args);
  243. if (result.length === 1) { return result[0]; }
  244. return <R><unknown>result;
  245. }
  246. const send = async function(...args: ContractMethodArgs<A>): Promise<ContractTransactionResponse> {
  247. const runner = contract.runner;
  248. assert(canSend(runner), "contract runner does not support sending transactions",
  249. "UNSUPPORTED_OPERATION", { operation: "sendTransaction" });
  250. const tx = await runner.sendTransaction(await populateTransaction(...args));
  251. const provider = getProvider(contract.runner);
  252. // @TODO: the provider can be null; make a custom dummy provider that will throw a
  253. // meaningful error
  254. return new ContractTransactionResponse(contract.interface, <Provider>provider, tx);
  255. }
  256. const estimateGas = async function(...args: ContractMethodArgs<A>): Promise<bigint> {
  257. const runner = getRunner(contract.runner, "estimateGas");
  258. assert(canEstimate(runner), "contract runner does not support gas estimation",
  259. "UNSUPPORTED_OPERATION", { operation: "estimateGas" });
  260. return await runner.estimateGas(await populateTransaction(...args));
  261. }
  262. const staticCallResult = async function(...args: ContractMethodArgs<A>): Promise<Result> {
  263. const runner = getRunner(contract.runner, "call");
  264. assert(canCall(runner), "contract runner does not support calling",
  265. "UNSUPPORTED_OPERATION", { operation: "call" });
  266. const tx = await populateTransaction(...args);
  267. let result = "0x";
  268. try {
  269. result = await runner.call(tx);
  270. } catch (error: any) {
  271. if (isCallException(error) && error.data) {
  272. throw contract.interface.makeError(error.data, tx);
  273. }
  274. throw error;
  275. }
  276. const fragment = getFragment(...args);
  277. return contract.interface.decodeFunctionResult(fragment, result);
  278. };
  279. const method = async (...args: ContractMethodArgs<A>) => {
  280. const fragment = getFragment(...args);
  281. if (fragment.constant) { return await staticCall(...args); }
  282. return await send(...args);
  283. };
  284. defineProperties<any>(method, {
  285. name: contract.interface.getFunctionName(key),
  286. _contract: contract, _key: key,
  287. getFragment,
  288. estimateGas,
  289. populateTransaction,
  290. send, staticCall, staticCallResult,
  291. });
  292. // Only works on non-ambiguous keys (refined fragment is always non-ambiguous)
  293. Object.defineProperty(method, "fragment", {
  294. configurable: false,
  295. enumerable: true,
  296. get: () => {
  297. const fragment = contract.interface.getFunction(key);
  298. assert(fragment, "no matching fragment", "UNSUPPORTED_OPERATION", {
  299. operation: "fragment",
  300. info: { key }
  301. });
  302. return fragment;
  303. }
  304. });
  305. return <BaseContractMethod<A, R, D>>method;
  306. }
  307. function buildWrappedEvent<A extends Array<any> = Array<any>>(contract: BaseContract, key: string): ContractEvent<A> {
  308. const getFragment = function(...args: ContractEventArgs<A>): EventFragment {
  309. const fragment = contract.interface.getEvent(key, args);
  310. assert(fragment, "no matching fragment", "UNSUPPORTED_OPERATION", {
  311. operation: "fragment",
  312. info: { key, args }
  313. });
  314. return fragment;
  315. }
  316. const method = function(...args: ContractMethodArgs<A>): PreparedTopicFilter {
  317. return new PreparedTopicFilter(contract, getFragment(...args), args);
  318. };
  319. defineProperties<any>(method, {
  320. name: contract.interface.getEventName(key),
  321. _contract: contract, _key: key,
  322. getFragment
  323. });
  324. // Only works on non-ambiguous keys (refined fragment is always non-ambiguous)
  325. Object.defineProperty(method, "fragment", {
  326. configurable: false,
  327. enumerable: true,
  328. get: () => {
  329. const fragment = contract.interface.getEvent(key);
  330. assert(fragment, "no matching fragment", "UNSUPPORTED_OPERATION", {
  331. operation: "fragment",
  332. info: { key }
  333. });
  334. return fragment;
  335. }
  336. });
  337. return <ContractEvent<A>><unknown>method;
  338. }
  339. type Sub = {
  340. tag: string;
  341. listeners: Array<{ listener: Listener, once: boolean }>,
  342. start: () => void;
  343. stop: () => void;
  344. };
  345. // The combination of TypeScrype, Private Fields and Proxies makes
  346. // the world go boom; so we hide variables with some trickery keeping
  347. // a symbol attached to each BaseContract which its sub-class (even
  348. // via a Proxy) can reach and use to look up its internal values.
  349. const internal = Symbol.for("_ethersInternal_contract");
  350. type Internal = {
  351. addrPromise: Promise<string>;
  352. addr: null | string;
  353. deployTx: null | ContractTransactionResponse;
  354. subs: Map<string, Sub>;
  355. };
  356. const internalValues: WeakMap<BaseContract, Internal> = new WeakMap();
  357. function setInternal(contract: BaseContract, values: Internal): void {
  358. internalValues.set(contract[internal], values);
  359. }
  360. function getInternal(contract: BaseContract): Internal {
  361. return internalValues.get(contract[internal]) as Internal;
  362. }
  363. function isDeferred(value: any): value is DeferredTopicFilter {
  364. return (value && typeof(value) === "object" && ("getTopicFilter" in value) &&
  365. (typeof(value.getTopicFilter) === "function") && value.fragment);
  366. }
  367. async function getSubInfo(contract: BaseContract, event: ContractEventName): Promise<{ fragment: null | EventFragment, tag: string, topics: TopicFilter }> {
  368. let topics: Array<null | string | Array<string>>;
  369. let fragment: null | EventFragment = null;
  370. // Convert named events to topicHash and get the fragment for
  371. // events which need deconstructing.
  372. if (Array.isArray(event)) {
  373. const topicHashify = function(name: string): string {
  374. if (isHexString(name, 32)) { return name; }
  375. const fragment = contract.interface.getEvent(name);
  376. assertArgument(fragment, "unknown fragment", "name", name);
  377. return fragment.topicHash;
  378. }
  379. // Array of Topics and Names; e.g. `[ "0x1234...89ab", "Transfer(address)" ]`
  380. topics = event.map((e) => {
  381. if (e == null) { return null; }
  382. if (Array.isArray(e)) { return e.map(topicHashify); }
  383. return topicHashify(e);
  384. });
  385. } else if (event === "*") {
  386. topics = [ null ];
  387. } else if (typeof(event) === "string") {
  388. if (isHexString(event, 32)) {
  389. // Topic Hash
  390. topics = [ event ];
  391. } else {
  392. // Name or Signature; e.g. `"Transfer", `"Transfer(address)"`
  393. fragment = contract.interface.getEvent(event);
  394. assertArgument(fragment, "unknown fragment", "event", event);
  395. topics = [ fragment.topicHash ];
  396. }
  397. } else if (isDeferred(event)) {
  398. // Deferred Topic Filter; e.g. `contract.filter.Transfer(from)`
  399. topics = await event.getTopicFilter();
  400. } else if ("fragment" in event) {
  401. // ContractEvent; e.g. `contract.filter.Transfer`
  402. fragment = event.fragment;
  403. topics = [ fragment.topicHash ];
  404. } else {
  405. assertArgument(false, "unknown event name", "event", event);
  406. }
  407. // Normalize topics and sort TopicSets
  408. topics = topics.map((t) => {
  409. if (t == null) { return null; }
  410. if (Array.isArray(t)) {
  411. const items = Array.from(new Set(t.map((t) => t.toLowerCase())).values());
  412. if (items.length === 1) { return items[0]; }
  413. items.sort();
  414. return items;
  415. }
  416. return t.toLowerCase();
  417. });
  418. const tag = topics.map((t) => {
  419. if (t == null) { return "null"; }
  420. if (Array.isArray(t)) { return t.join("|"); }
  421. return t;
  422. }).join("&");
  423. return { fragment, tag, topics }
  424. }
  425. async function hasSub(contract: BaseContract, event: ContractEventName): Promise<null | Sub> {
  426. const { subs } = getInternal(contract);
  427. return subs.get((await getSubInfo(contract, event)).tag) || null;
  428. }
  429. async function getSub(contract: BaseContract, operation: string, event: ContractEventName): Promise<Sub> {
  430. // Make sure our runner can actually subscribe to events
  431. const provider = getProvider(contract.runner);
  432. assert(provider, "contract runner does not support subscribing",
  433. "UNSUPPORTED_OPERATION", { operation });
  434. const { fragment, tag, topics } = await getSubInfo(contract, event);
  435. const { addr, subs } = getInternal(contract);
  436. let sub = subs.get(tag);
  437. if (!sub) {
  438. const address: string | Addressable = (addr ? addr: contract);
  439. const filter = { address, topics };
  440. const listener = (log: Log) => {
  441. let foundFragment = fragment;
  442. if (foundFragment == null) {
  443. try {
  444. foundFragment = contract.interface.getEvent(log.topics[0]);
  445. } catch (error) { }
  446. }
  447. // If fragment is null, we do not deconstruct the args to emit
  448. if (foundFragment) {
  449. const _foundFragment = foundFragment;
  450. const args = fragment ? contract.interface.decodeEventLog(fragment, log.data, log.topics): [ ];
  451. emit(contract, event, args, (listener: null | Listener) => {
  452. return new ContractEventPayload(contract, listener, event, _foundFragment, log);
  453. });
  454. } else {
  455. emit(contract, event, [ ], (listener: null | Listener) => {
  456. return new ContractUnknownEventPayload(contract, listener, event, log);
  457. });
  458. }
  459. };
  460. let starting: Array<Promise<any>> = [ ];
  461. const start = () => {
  462. if (starting.length) { return; }
  463. starting.push(provider.on(filter, listener));
  464. };
  465. const stop = async () => {
  466. if (starting.length == 0) { return; }
  467. let started = starting;
  468. starting = [ ];
  469. await Promise.all(started);
  470. provider.off(filter, listener);
  471. };
  472. sub = { tag, listeners: [ ], start, stop };
  473. subs.set(tag, sub);
  474. }
  475. return sub;
  476. }
  477. // We use this to ensure one emit resolves before firing the next to
  478. // ensure correct ordering (note this cannot throw and just adds the
  479. // notice to the event queu using setTimeout).
  480. let lastEmit: Promise<any> = Promise.resolve();
  481. type PayloadFunc = (listener: null | Listener) => ContractUnknownEventPayload;
  482. async function _emit(contract: BaseContract, event: ContractEventName, args: Array<any>, payloadFunc: null | PayloadFunc): Promise<boolean> {
  483. await lastEmit;
  484. const sub = await hasSub(contract, event);
  485. if (!sub) { return false; }
  486. const count = sub.listeners.length;
  487. sub.listeners = sub.listeners.filter(({ listener, once }) => {
  488. const passArgs = Array.from(args);
  489. if (payloadFunc) {
  490. passArgs.push(payloadFunc(once ? null: listener));
  491. }
  492. try {
  493. listener.call(contract, ...passArgs);
  494. } catch (error) { }
  495. return !once;
  496. });
  497. if (sub.listeners.length === 0) {
  498. sub.stop();
  499. getInternal(contract).subs.delete(sub.tag);
  500. }
  501. return (count > 0);
  502. }
  503. async function emit(contract: BaseContract, event: ContractEventName, args: Array<any>, payloadFunc: null | PayloadFunc): Promise<boolean> {
  504. try {
  505. await lastEmit;
  506. } catch (error) { }
  507. const resultPromise = _emit(contract, event, args, payloadFunc);
  508. lastEmit = resultPromise;
  509. return await resultPromise;
  510. }
  511. const passProperties = [ "then" ];
  512. export class BaseContract implements Addressable, EventEmitterable<ContractEventName> {
  513. /**
  514. * The target to connect to.
  515. *
  516. * This can be an address, ENS name or any [[Addressable]], such as
  517. * another contract. To get the resovled address, use the ``getAddress``
  518. * method.
  519. */
  520. readonly target!: string | Addressable;
  521. /**
  522. * The contract Interface.
  523. */
  524. readonly interface!: Interface;
  525. /**
  526. * The connected runner. This is generally a [[Provider]] or a
  527. * [[Signer]], which dictates what operations are supported.
  528. *
  529. * For example, a **Contract** connected to a [[Provider]] may
  530. * only execute read-only operations.
  531. */
  532. readonly runner!: null | ContractRunner;
  533. /**
  534. * All the Events available on this contract.
  535. */
  536. readonly filters!: Record<string, ContractEvent>;
  537. /**
  538. * @_ignore:
  539. */
  540. readonly [internal]: any;
  541. /**
  542. * The fallback or receive function if any.
  543. */
  544. readonly fallback!: null | WrappedFallback;
  545. /**
  546. * Creates a new contract connected to %%target%% with the %%abi%% and
  547. * optionally connected to a %%runner%% to perform operations on behalf
  548. * of.
  549. */
  550. constructor(target: string | Addressable, abi: Interface | InterfaceAbi, runner?: null | ContractRunner, _deployTx?: null | TransactionResponse) {
  551. assertArgument(typeof(target) === "string" || isAddressable(target),
  552. "invalid value for Contract target", "target", target);
  553. if (runner == null) { runner = null; }
  554. const iface = Interface.from(abi);
  555. defineProperties<BaseContract>(this, { target, runner, interface: iface });
  556. Object.defineProperty(this, internal, { value: { } });
  557. let addrPromise;
  558. let addr: null | string = null;
  559. let deployTx: null | ContractTransactionResponse = null;
  560. if (_deployTx) {
  561. const provider = getProvider(runner);
  562. // @TODO: the provider can be null; make a custom dummy provider that will throw a
  563. // meaningful error
  564. deployTx = new ContractTransactionResponse(this.interface, <Provider>provider, _deployTx);
  565. }
  566. let subs = new Map();
  567. // Resolve the target as the address
  568. if (typeof(target) === "string") {
  569. if (isHexString(target)) {
  570. addr = target;
  571. addrPromise = Promise.resolve(target);
  572. } else {
  573. const resolver = getRunner(runner, "resolveName");
  574. if (!canResolve(resolver)) {
  575. throw makeError("contract runner does not support name resolution", "UNSUPPORTED_OPERATION", {
  576. operation: "resolveName"
  577. });
  578. }
  579. addrPromise = resolver.resolveName(target).then((addr) => {
  580. if (addr == null) {
  581. throw makeError("an ENS name used for a contract target must be correctly configured", "UNCONFIGURED_NAME", {
  582. value: target
  583. });
  584. }
  585. getInternal(this).addr = addr;
  586. return addr;
  587. });
  588. }
  589. } else {
  590. addrPromise = target.getAddress().then((addr) => {
  591. if (addr == null) { throw new Error("TODO"); }
  592. getInternal(this).addr = addr;
  593. return addr;
  594. });
  595. }
  596. // Set our private values
  597. setInternal(this, { addrPromise, addr, deployTx, subs });
  598. // Add the event filters
  599. const filters = new Proxy({ }, {
  600. get: (target, prop, receiver) => {
  601. // Pass important checks (like `then` for Promise) through
  602. if (typeof(prop) === "symbol" || passProperties.indexOf(prop) >= 0) {
  603. return Reflect.get(target, prop, receiver);
  604. }
  605. try {
  606. return this.getEvent(prop);
  607. } catch (error) {
  608. if (!isError(error, "INVALID_ARGUMENT") || error.argument !== "key") {
  609. throw error;
  610. }
  611. }
  612. return undefined;
  613. },
  614. has: (target, prop) => {
  615. // Pass important checks (like `then` for Promise) through
  616. if (passProperties.indexOf(<string>prop) >= 0) {
  617. return Reflect.has(target, prop);
  618. }
  619. return Reflect.has(target, prop) || this.interface.hasEvent(String(prop));
  620. }
  621. });
  622. defineProperties<BaseContract>(this, { filters });
  623. defineProperties<BaseContract>(this, {
  624. fallback: ((iface.receive || iface.fallback) ? (buildWrappedFallback(this)): null)
  625. });
  626. // Return a Proxy that will respond to functions
  627. return new Proxy(this, {
  628. get: (target, prop, receiver) => {
  629. if (typeof(prop) === "symbol" || prop in target || passProperties.indexOf(prop) >= 0) {
  630. return Reflect.get(target, prop, receiver);
  631. }
  632. // Undefined properties should return undefined
  633. try {
  634. return target.getFunction(prop);
  635. } catch (error) {
  636. if (!isError(error, "INVALID_ARGUMENT") || error.argument !== "key") {
  637. throw error;
  638. }
  639. }
  640. return undefined;
  641. },
  642. has: (target, prop) => {
  643. if (typeof(prop) === "symbol" || prop in target || passProperties.indexOf(prop) >= 0) {
  644. return Reflect.has(target, prop);
  645. }
  646. return target.interface.hasFunction(prop);
  647. }
  648. });
  649. }
  650. /**
  651. * Return a new Contract instance with the same target and ABI, but
  652. * a different %%runner%%.
  653. */
  654. connect(runner: null | ContractRunner): BaseContract {
  655. return new BaseContract(this.target, this.interface, runner);
  656. }
  657. /**
  658. * Return a new Contract instance with the same ABI and runner, but
  659. * a different %%target%%.
  660. */
  661. attach(target: string | Addressable): BaseContract {
  662. return new BaseContract(target, this.interface, this.runner);
  663. }
  664. /**
  665. * Return the resolved address of this Contract.
  666. */
  667. async getAddress(): Promise<string> { return await getInternal(this).addrPromise; }
  668. /**
  669. * Return the deployed bytecode or null if no bytecode is found.
  670. */
  671. async getDeployedCode(): Promise<null | string> {
  672. const provider = getProvider(this.runner);
  673. assert(provider, "runner does not support .provider",
  674. "UNSUPPORTED_OPERATION", { operation: "getDeployedCode" });
  675. const code = await provider.getCode(await this.getAddress());
  676. if (code === "0x") { return null; }
  677. return code;
  678. }
  679. /**
  680. * Resolve to this Contract once the bytecode has been deployed, or
  681. * resolve immediately if already deployed.
  682. */
  683. async waitForDeployment(): Promise<this> {
  684. // We have the deployement transaction; just use that (throws if deployement fails)
  685. const deployTx = this.deploymentTransaction();
  686. if (deployTx) {
  687. await deployTx.wait();
  688. return this;
  689. }
  690. // Check for code
  691. const code = await this.getDeployedCode();
  692. if (code != null) { return this; }
  693. // Make sure we can subscribe to a provider event
  694. const provider = getProvider(this.runner);
  695. assert(provider != null, "contract runner does not support .provider",
  696. "UNSUPPORTED_OPERATION", { operation: "waitForDeployment" });
  697. return new Promise((resolve, reject) => {
  698. const checkCode = async () => {
  699. try {
  700. const code = await this.getDeployedCode();
  701. if (code != null) { return resolve(this); }
  702. provider.once("block", checkCode);
  703. } catch (error) {
  704. reject(error);
  705. }
  706. };
  707. checkCode();
  708. });
  709. }
  710. /**
  711. * Return the transaction used to deploy this contract.
  712. *
  713. * This is only available if this instance was returned from a
  714. * [[ContractFactory]].
  715. */
  716. deploymentTransaction(): null | ContractTransactionResponse {
  717. return getInternal(this).deployTx;
  718. }
  719. /**
  720. * Return the function for a given name. This is useful when a contract
  721. * method name conflicts with a JavaScript name such as ``prototype`` or
  722. * when using a Contract programatically.
  723. */
  724. getFunction<T extends ContractMethod = ContractMethod>(key: string | FunctionFragment): T {
  725. if (typeof(key) !== "string") { key = key.format(); }
  726. const func = buildWrappedMethod(this, key);
  727. return <T>func;
  728. }
  729. /**
  730. * Return the event for a given name. This is useful when a contract
  731. * event name conflicts with a JavaScript name such as ``prototype`` or
  732. * when using a Contract programatically.
  733. */
  734. getEvent(key: string | EventFragment): ContractEvent {
  735. if (typeof(key) !== "string") { key = key.format(); }
  736. return buildWrappedEvent(this, key);
  737. }
  738. /**
  739. * @_ignore:
  740. */
  741. async queryTransaction(hash: string): Promise<Array<EventLog>> {
  742. throw new Error("@TODO");
  743. }
  744. /*
  745. // @TODO: this is a non-backwards compatible change, but will be added
  746. // in v7 and in a potential SmartContract class in an upcoming
  747. // v6 release
  748. async getTransactionReceipt(hash: string): Promise<null | ContractTransactionReceipt> {
  749. const provider = getProvider(this.runner);
  750. assert(provider, "contract runner does not have a provider",
  751. "UNSUPPORTED_OPERATION", { operation: "queryTransaction" });
  752. const receipt = await provider.getTransactionReceipt(hash);
  753. if (receipt == null) { return null; }
  754. return new ContractTransactionReceipt(this.interface, provider, receipt);
  755. }
  756. */
  757. /**
  758. * Provide historic access to event data for %%event%% in the range
  759. * %%fromBlock%% (default: ``0``) to %%toBlock%% (default: ``"latest"``)
  760. * inclusive.
  761. */
  762. async queryFilter(event: ContractEventName, fromBlock?: BlockTag, toBlock?: BlockTag): Promise<Array<EventLog | Log>> {
  763. if (fromBlock == null) { fromBlock = 0; }
  764. if (toBlock == null) { toBlock = "latest"; }
  765. const { addr, addrPromise } = getInternal(this);
  766. const address = (addr ? addr: (await addrPromise));
  767. const { fragment, topics } = await getSubInfo(this, event);
  768. const filter = { address, topics, fromBlock, toBlock };
  769. const provider = getProvider(this.runner);
  770. assert(provider, "contract runner does not have a provider",
  771. "UNSUPPORTED_OPERATION", { operation: "queryFilter" });
  772. return (await provider.getLogs(filter)).map((log) => {
  773. let foundFragment = fragment;
  774. if (foundFragment == null) {
  775. try {
  776. foundFragment = this.interface.getEvent(log.topics[0]);
  777. } catch (error) { }
  778. }
  779. if (foundFragment) {
  780. try {
  781. return new EventLog(log, this.interface, foundFragment);
  782. } catch (error: any) {
  783. return new UndecodedEventLog(log, error);
  784. }
  785. }
  786. return new Log(log, provider);
  787. });
  788. }
  789. /**
  790. * Add an event %%listener%% for the %%event%%.
  791. */
  792. async on(event: ContractEventName, listener: Listener): Promise<this> {
  793. const sub = await getSub(this, "on", event);
  794. sub.listeners.push({ listener, once: false });
  795. sub.start();
  796. return this;
  797. }
  798. /**
  799. * Add an event %%listener%% for the %%event%%, but remove the listener
  800. * after it is fired once.
  801. */
  802. async once(event: ContractEventName, listener: Listener): Promise<this> {
  803. const sub = await getSub(this, "once", event);
  804. sub.listeners.push({ listener, once: true });
  805. sub.start();
  806. return this;
  807. }
  808. /**
  809. * Emit an %%event%% calling all listeners with %%args%%.
  810. *
  811. * Resolves to ``true`` if any listeners were called.
  812. */
  813. async emit(event: ContractEventName, ...args: Array<any>): Promise<boolean> {
  814. return await emit(this, event, args, null);
  815. }
  816. /**
  817. * Resolves to the number of listeners of %%event%% or the total number
  818. * of listeners if unspecified.
  819. */
  820. async listenerCount(event?: ContractEventName): Promise<number> {
  821. if (event) {
  822. const sub = await hasSub(this, event);
  823. if (!sub) { return 0; }
  824. return sub.listeners.length;
  825. }
  826. const { subs } = getInternal(this);
  827. let total = 0;
  828. for (const { listeners } of subs.values()) {
  829. total += listeners.length;
  830. }
  831. return total;
  832. }
  833. /**
  834. * Resolves to the listeners subscribed to %%event%% or all listeners
  835. * if unspecified.
  836. */
  837. async listeners(event?: ContractEventName): Promise<Array<Listener>> {
  838. if (event) {
  839. const sub = await hasSub(this, event);
  840. if (!sub) { return [ ]; }
  841. return sub.listeners.map(({ listener }) => listener);
  842. }
  843. const { subs } = getInternal(this);
  844. let result: Array<Listener> = [ ];
  845. for (const { listeners } of subs.values()) {
  846. result = result.concat(listeners.map(({ listener }) => listener));
  847. }
  848. return result;
  849. }
  850. /**
  851. * Remove the %%listener%% from the listeners for %%event%% or remove
  852. * all listeners if unspecified.
  853. */
  854. async off(event: ContractEventName, listener?: Listener): Promise<this> {
  855. const sub = await hasSub(this, event);
  856. if (!sub) { return this; }
  857. if (listener) {
  858. const index = sub.listeners.map(({ listener }) => listener).indexOf(listener);
  859. if (index >= 0) { sub.listeners.splice(index, 1); }
  860. }
  861. if (listener == null || sub.listeners.length === 0) {
  862. sub.stop();
  863. getInternal(this).subs.delete(sub.tag);
  864. }
  865. return this;
  866. }
  867. /**
  868. * Remove all the listeners for %%event%% or remove all listeners if
  869. * unspecified.
  870. */
  871. async removeAllListeners(event?: ContractEventName): Promise<this> {
  872. if (event) {
  873. const sub = await hasSub(this, event);
  874. if (!sub) { return this; }
  875. sub.stop();
  876. getInternal(this).subs.delete(sub.tag);
  877. } else {
  878. const { subs } = getInternal(this);
  879. for (const { tag, stop } of subs.values()) {
  880. stop();
  881. subs.delete(tag);
  882. }
  883. }
  884. return this;
  885. }
  886. /**
  887. * Alias for [on].
  888. */
  889. async addListener(event: ContractEventName, listener: Listener): Promise<this> {
  890. return await this.on(event, listener);
  891. }
  892. /**
  893. * Alias for [off].
  894. */
  895. async removeListener(event: ContractEventName, listener: Listener): Promise<this> {
  896. return await this.off(event, listener);
  897. }
  898. /**
  899. * Create a new Class for the %%abi%%.
  900. */
  901. static buildClass<T = ContractInterface>(abi: Interface | InterfaceAbi): new (target: string, runner?: null | ContractRunner) => BaseContract & Omit<T, keyof BaseContract> {
  902. class CustomContract extends BaseContract {
  903. constructor(address: string, runner: null | ContractRunner = null) {
  904. super(address, abi, runner);
  905. }
  906. }
  907. return CustomContract as any;
  908. };
  909. /**
  910. * Create a new BaseContract with a specified Interface.
  911. */
  912. static from<T = ContractInterface>(target: string, abi: Interface | InterfaceAbi, runner?: null | ContractRunner): BaseContract & Omit<T, keyof BaseContract> {
  913. if (runner == null) { runner = null; }
  914. const contract = new this(target, abi, runner );
  915. return contract as any;
  916. }
  917. }
  918. function _ContractBase(): new (target: string | Addressable, abi: Interface | InterfaceAbi, runner?: null | ContractRunner) => BaseContract & Omit<ContractInterface, keyof BaseContract> {
  919. return BaseContract as any;
  920. }
  921. /**
  922. * A [[BaseContract]] with no type guards on its methods or events.
  923. */
  924. export class Contract extends _ContractBase() { }